Setting emitDeclarationOnly in tsconfig.json
What you'll learn: How to configure TypeScript to generate only type definition files (.d.ts) without producing JavaScript output.
What Is emitDeclarationOnly?
The emitDeclarationOnly compiler option tells TypeScript to generate only declaration files (.d.ts) when you run tsc, skipping JavaScript output entirely. This is particularly useful when you're building libraries where another tool handles the JavaScript transpilation (like esbuild, Babel, or swc), but you still need TypeScript to generate type definitions for consumers.
Think of it like a restaurant that normally produces both a meal and a recipe card. With emitDeclarationOnly, you're saying "just give me the recipe card (the types), someone else will cook the meal (the JavaScript)."
The Required Companion: declaration: true
You cannot use emitDeclarationOnly by itself. You must also enable declaration: true in your tsconfig.json, since TypeScript needs to know you want declaration files in the first place.
Here's the basic configuration:
{
"compilerOptions": {
"declaration": true,
"emitDeclarationOnly": true,
"outDir": "./dist"
}
}
With this setup, when you run tsc, TypeScript will:
- ✅ Generate
.d.tsfiles in thedistfolder - ❌ NOT generate any
.jsfiles
Why Use This Pattern?
Modern build pipelines often separate two concerns:
- Type-checking and declaration generation (TypeScript's strength)
- Fast JavaScript transpilation (bundlers' strength)
By using emitDeclarationOnly, you let TypeScript do what it does best—ensuring type safety and creating accurate type definitions—while a faster tool like esbuild handles the actual JavaScript output. You'd typically run both tools: tsc for declarations and your bundler for JavaScript.
Key Takeaway: Configure emitDeclarationOnly: true alongside declaration: true to generate type definitions without JavaScript output, perfect for library builds where another tool handles transpilation.