# Magnitude Type Checking Strategy: Why Targeted Per‑Package Checks Beat `tsc -b` in Monorepos

> Discover Magnitude's type checking strategy. Learn why isolated per-package `tsc` runs offer faster feedback and stricter dependency boundaries than `tsc -b` for monorepos.

- Repository: [Magnitude/magnitude](https://github.com/magnitudedev/magnitude)
- Tags: deep-dive
- Published: 2026-09-06

---

**Magnitude enforces type safety through isolated, per‑package `tsc` runs rather than a project‑wide `tsc -b` build, prioritizing fast feedback, strict dependency boundaries, and Effect‑TS compatibility.**

The [magnitudedev/magnitude](https://github.com/magnitudedev/magnitude) repository is a large TypeScript monorepo containing dozens of discrete packages—from `@magnitudedev/agent` and `@magnitudedev/sdk` to `@magnitudedev/acn-protocol`. Each package maintains its own [`tsconfig.json`](https://github.com/magnitudedev/magnitude/blob/main/tsconfig.json), and the project's [`AGENTS.md`](https://github.com/magnitudedev/magnitude/blob/main/AGENTS.md) (line 65) codifies a strict policy: run targeted type checks per package, never a monolithic `tsc -b`. This article breaks down the **Magnitude type checking strategy** and the architectural rationale behind it.

---

## What Is Targeted Per‑Package Type Checking?

In Magnitude, **targeted per‑package type checking** means invoking the TypeScript compiler separately for each package using its dedicated configuration:

```bash

# Type-check the agent package only

bunx tsc -p packages/agent/tsconfig.json

# Type-check the SDK package only

bunx tsc -p packages/sdk/tsconfig.json

```

Each `packages/*/tsconfig.json` defines package‑specific compiler options, path aliases, and `noEmit: true` for pure validation. This contrasts with `tsc -b`, which would build the entire project graph in a single invocation using TypeScript project references.

---

## Why Magnitude Avoids `tsc -b`

The decision to reject project‑wide `tsc -b` rests on five architectural pillars derived directly from the codebase structure and documented practices.

### Isolation of Dependencies

Packages in Magnitude have independent dependency graphs. A `tsc -b` run would force every package to resolve types against the entire repository, pulling in unnecessary definitions and risking **spurious type errors** from version conflicts or ambient type pollution. Per‑package configs keep each compilation unit hermetic.

### Fast Incremental Feedback

Targeted checks compile only changed files within a single package. In a monorepo with hundreds of source files, this **dramatically reduces compile time** and keeps developer feedback tight. The `bunx tsc -p` pattern completes in seconds versus minutes for a full build.

### Clear Ownership Boundaries

Magnitude organizes packages by architectural layer—`client-common`, `sdk`, `acn`, and others. Per‑package type checking **enforces that changes stay within intended boundaries**, making API contracts explicit and catching accidental cross‑package leaks at compile time.

### Effect‑TS Compatibility

The codebase relies heavily on **Effect‑TS**, whose libraries impose strict type expectations. Isolated builds ensure the compiler respects the **exact Effect‑TS versions** declared in each package's [`package.json`](https://github.com/magnitudedev/magnitude/blob/main/package.json), avoiding subtle breakage from transitive dependency drift that a unified `tsc -b` might mask.

### Scalable Monorepo Management

Using per‑package [`tsconfig.json`](https://github.com/magnitudedev/magnitude/blob/main/tsconfig.json) files aligns with Magnitude's tooling choices: `bunx` scripts, independent CI pipelines, and package‑specific test suites. This avoids the **configuration complexity** of maintaining project references for a massive [`tsconfig.build.json`](https://github.com/magnitudedev/magnitude/blob/main/tsconfig.build.json) hierarchy.

---

## How Targeted Checks Work in Practice

### Individual Package Validation

Developers run type checks during local development or pre‑commit hooks:

```bash
bunx tsc -p packages/agent/tsconfig.json   # no emit, pure validation

bunx tsc -p packages/sdk/tsconfig.json

```

Each command exits non‑zero on type errors, enabling fast, granular feedback.

### CI Pipeline Integration

For continuous integration, Magnitude iterates over all packages:

```bash

# CI step enforcing type safety across the monorepo

for pkg in packages/*; do
  bunx tsc -p "$pkg/tsconfig.json" || exit 1
done

```

This pattern preserves isolation while guaranteeing repository‑wide type safety.

---

## Key Configuration Files

Understanding Magnitude's type checking strategy requires familiarity with these files:

| File | Purpose |
|------|---------|
| [`AGENTS.md`](https://github.com/magnitudedev/magnitude/blob/main/AGENTS.md) (line 65) | Documents the explicit policy: "Run targeted type checks per package — do not run project‑wide `tsc -b`." |
| [`tsconfig.json`](https://github.com/magnitudedev/magnitude/blob/main/tsconfig.json) (root) | Defines global compiler options and shared path aliases inherited by packages. |
| `packages/*/tsconfig.json` | Provides isolated TypeScript configuration per package; enables targeted checks. |
| `packages/*/package.json` | Holds package‑specific dependencies and scripts; supports independent build/test cycles. |

---

## Summary

- **Magnitude's type checking strategy** uses targeted `tsc -p` invocations per package, not `tsc -b`.
- **Isolation** prevents dependency graph pollution and spurious errors.
- **Speed** delivers incremental feedback in seconds, not minutes.
- **Boundaries** enforce architectural layers and explicit API contracts.
- **Effect‑TS compatibility** requires strict, version‑isolated compilation.
- **Scalability** matches Magnitude's `bunx`‑based tooling and CI design.

---

## Frequently Asked Questions

### How does per‑package type checking improve build performance?

Per‑package checks compile only the files that changed within a single package. In the Magnitude monorepo, this reduces feedback time from minutes to seconds compared with a full `tsc -b` traversal of all project references.

### Can `tsc -b` be used safely in large TypeScript monorepos?

While `tsc -b` works for smaller codebases, Magnitude explicitly avoids it. The architectural overhead of maintaining project references, combined with risks of cross‑package type leakage and slower incremental builds, makes targeted checks preferable at scale.

### Why is Effect‑TS compatibility important for Magnitude's type strategy?

Effect‑TS imposes strict type‑level constraints. Isolated builds ensure each package resolves the exact Effect‑TS versions it declares, preventing subtle runtime failures from transitive dependency mismatches that a unified build might obscure.

### Where is the per‑package type checking policy documented?

The policy appears in [`AGENTS.md`](https://github.com/magnitudedev/magnitude/blob/main/AGENTS.md) at line 65: "Run targeted type checks per package — do not run project‑wide `tsc -b`."