What emitDeclarationOnly Does
What you'll learn: How the emitDeclarationOnly flag tells TypeScript to output only .d.ts declaration files without any JavaScript, making it perfect for library builds and type-only packages.
The Core Concept
When you compile TypeScript, the compiler normally produces two things: JavaScript files (.js) that run your code, and declaration files (.d.ts) that describe your types. The emitDeclarationOnly flag tells TypeScript to skip the JavaScript entirely and only generate those .d.ts files.
Think of it like a restaurant kitchen where you normally prepare both the meal and a detailed recipe card. With emitDeclarationOnly, you're saying "just write down the recipes, don't cook anything."
Why This Matters
This flag is crucial when:
- Building libraries where a faster tool (like esbuild or swc) handles the actual JavaScript compilation, but you still need TypeScript's declaration files for type safety
- Type-only packages that exist solely to provide types to other projects
- Build pipelines where type-checking and transpilation are separate steps
You configure it in tsconfig.json:
{
"compilerOptions": {
"declaration": true,
"emitDeclarationOnly": true
}
}
When you run tsc, it generates .d.ts files but no .js files. You'd pair this with a bundler or transpiler that handles the JavaScript output separately.
Key Takeaway: emitDeclarationOnly makes TypeScript focus exclusively on generating type declarations, letting faster tools handle JavaScript output while preserving full type safety for library consumers.