Common Pitfalls with Declaration-Only Builds
What you'll learn: How to avoid configuration mistakes and missing runtime code when building libraries with declaration files only.
The Core Problem
When you enable emitDeclarationOnly: true in your TypeScript configuration, you're telling the compiler to produce .d.ts files but no JavaScript. This is perfect for libraries where a bundler handles transpilation separately — but it creates two major traps developers fall into.
Pitfall #1: Forgetting declaration: true
The most common mistake is enabling emitDeclarationOnly without first enabling declaration. TypeScript won't magically know you want declaration files:
{
"compilerOptions": {
// ❌ This does nothing without declaration: true
"emitDeclarationOnly": true
}
}
You need both flags:
{
"compilerOptions": {
"declaration": true,
"emitDeclarationOnly": true
}
}
Pitfall #2: No Runtime Code Output
This is the bigger issue: emitDeclarationOnly produces only type definitions. Your library consumers will get perfect TypeScript support, but when they try to run their code, they'll get import errors because there's no actual JavaScript.
Think of it like publishing a blueprint without the building. The types tell developers what your library looks like, but without JavaScript, there's nothing to execute.
The Solution Pattern
Always pair declaration-only builds with a separate bundler step:
- Run
tscwithemitDeclarationOnly: trueto generate.d.tsfiles - Run your bundler (Rollup, esbuild, etc.) to generate the actual
.jsfiles - Configure
package.jsonto point to both the types and the runtime code
Key Takeaway: Declaration-only builds require explicit declaration: true and must always be paired with a separate process that produces runtime JavaScript — declarations alone won't execute.