Course contentsShow
← TypeScript
Lesson 1252 of 1,79629. The Build PipelineFree lesson

Common Pitfalls with Declaration-Only Builds

Avoid issues like missing declaration: true or forgetting to bundle runtime code separately.

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:

  1. Run tsc with emitDeclarationOnly: true to generate .d.ts files
  2. Run your bundler (Rollup, esbuild, etc.) to generate the actual .js files
  3. Configure package.json to 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.