Combining with Composite Projects
What you'll learn: How to use emitDeclarationOnly with project references to build type definitions incrementally across packages in a monorepo.
The Core Problem
When working with composite projects (a monorepo with multiple TypeScript packages), you often want to separate concerns: let a fast bundler handle JavaScript output, but still maintain incremental, type-safe builds for your .d.ts declaration files. This is where emitDeclarationOnly becomes powerful.
How It Works Together
Composite projects with composite: true enable incremental builds and project references. When you add emitDeclarationOnly: true to a composite project, TypeScript will:
- Only generate
.d.tsfiles (no JavaScript) - Track dependencies through
.tsbuildinfo - Rebuild incrementally when source types change
- Preserve type information across package boundaries
This lets downstream packages import types from upstream packages correctly, even when your actual JavaScript is built by a bundler like esbuild or Rollup.
The Workflow Pattern
Think of it like an assembly line: your bundler handles the fast manufacturing (JavaScript output), while TypeScript's composite build handles the precise blueprints (type definitions) that ensure all the parts fit together correctly. Each package only rebuilds its type definitions when its sources or dependencies change.
In a typical monorepo setup, packages/core generates declarations that packages/app references. With emitDeclarationOnly + composite, TypeScript knows exactly which declarations need regenerating when you change core types, without wasting time on JavaScript transpilation your bundler already handles.
Key Takeaway: Combining emitDeclarationOnly with composite projects gives you incremental type definition builds in monorepos while letting specialized bundlers handle JavaScript output — the best of both worlds for speed and type safety.