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

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 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, and the project's 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:

# 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, avoiding subtle breakage from transitive dependency drift that a unified tsc -b might mask.

Scalable Monorepo Management

Using per‑package 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 hierarchy.

---

How Targeted Checks Work in Practice

Individual Package Validation

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

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:

# 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 (line 65)	Documents the explicit policy: "Run targeted type checks per package — do not run project‑wide tsc -b."
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 at line 65: "Run targeted type checks per package — do not run project‑wide tsc -b."

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}