Declaration File Generation and Type Stripping

For library maintainers and platform engineers, reliable TypeScript declaration file generation is a non-negotiable requirement for cross-environment compatibility. As modern runtimes and bundlers evolve, the process of separating type annotations from executable JavaScript demands precise compiler orchestration. This guide details the mechanics of type stripping, declaration emission, and validation workflows that underpin the broader TypeScript Configuration & Build Tooling ecosystem.

Core Mechanics of Type Stripping and Declaration Emission

TypeScript’s compiler (tsc) and modern JavaScript runtimes handle type information through two distinct paradigms: experimental type stripping and standard declaration emission. Type stripping (enabled via --strip-types or verbatimModuleSyntax in newer runtimes) removes annotations at runtime but produces zero .d.ts artifacts. This approach is fundamentally insufficient for library distribution because consumers rely on explicit type contracts for IDE autocompletion, static analysis, and cross-package resolution.

Standard declaration emission (declaration: true) generates .d.ts files that preserve type boundaries without runtime overhead. When targeting dual ESM/CJS packages, explicit generation is mandatory to prevent resolution mismatches across different module systems. The isolatedModules flag significantly impacts extraction performance by forcing single-file compilation boundaries, which aligns with modern bundler expectations but requires strict adherence to import/export rules.

For teams evaluating compiler upgrades, understanding the behavioral shifts in Generating Accurate .d.ts Files with TypeScript 5.4 is critical for maintaining stricter type boundaries and avoiding legacy emission quirks.

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "verbatimModuleSyntax": true,
    "isolatedModules": true,
    "declaration": true,
    "declarationMap": true,
    "noEmit": false
  }
}

️ Hazard Prevention: Enabling verbatimModuleSyntax without declaration: true will strip types at compile time but fail to emit .d.ts files, breaking downstream consumers. Always pair verbatimModuleSyntax with explicit declaration generation for public APIs. Additionally, missing declarationMap will cause broken IDE navigation; enable declarationMap: true alongside declaration so IDEs can map generated types back to original source files during debugging.

Compiler Configuration for Reliable .d.ts Output

Generating resolution-ready declaration files requires a tightly scoped tsconfig.json that aligns with your package’s distribution strategy. The baseline configuration must prioritize declaration and declarationMap to enable seamless IDE navigation and source mapping during debugging. When integrating with external bundlers (e.g., Vite, esbuild, Rollup), emitDeclarationOnly: true prevents redundant JavaScript emission, delegating runtime bundling to specialized tools while tsc handles type extraction exclusively.

Internal path aliases (baseUrl, paths) are a frequent source of consumer resolution failures. If aliases are emitted directly into .d.ts files, downstream projects will fail to resolve imports unless they replicate your exact tsconfig setup. To prevent this, aliases must be flattened to relative paths before publication. This aligns with the principles outlined in Optimizing tsconfig.json for Library Distribution, where compiler flags are explicitly mapped to package.json exports.

{
  "compilerOptions": {
    "declaration": true,
    "declarationMap": true,
    "emitDeclarationOnly": true,
    "outDir": "./dist/types",
    "rootDir": "./src",
    "baseUrl": ".",
    "paths": {
      "@internal/*": ["src/internal/*"]
    }
  },
  "include": ["src/**/*.ts"],
  "exclude": ["node_modules", "**/*.test.ts"]
}

️ Hazard Prevention: Path aliases leaking into published .d.ts files will break consumer resolution. Use tsc-alias or bundler plugins to rewrite paths to relative imports before declaration emission, ensuring consumers can resolve types without matching your internal paths config. Refer to Path Mapping and Module Resolution Strategies for flattening workflows that guarantee consumer compatibility.

Bundler-Driven Type Extraction Workflows

Native tsc compilation guarantees type accuracy but introduces latency in large monorepos. Modern toolchains parallelize JavaScript bundling and type extraction, though each requires specific configuration to avoid type loss.

tsup leverages dts: true to invoke tsc under the hood while bundling JS with esbuild. It’s highly performant but requires explicit entry mapping to prevent missing exports. Rollup with rollup-plugin-dts performs tree-shaking on declaration files, merging and pruning unused types. This is ideal for libraries with large internal type graphs. esbuild natively supports drop: ["type"] for fast type stripping, but it does not generate .d.ts files. It must be paired with a separate tsc or rollup-plugin-dts step for distribution.

// tsup.config.ts
import { defineConfig } from 'tsup';

export default defineConfig({
 entry: ['src/index.ts'],
 format: ['esm', 'cjs'],
 dts: true,
 clean: true,
 external: ['react', 'react-dom'],
 sourcemap: true,
});

️ Hazard Prevention: tsup’s dts: true runs a separate tsc process. If your tsconfig.json contains noEmit: true, declaration generation will silently fail. Ensure noEmit is disabled in the typescript config used by tsup, or pass --dts-resolve for external type bundling.

// rollup.config.mjs
import dts from 'rollup-plugin-dts';
import { defineConfig } from 'rollup';

export default defineConfig([
  {
    input: 'src/index.ts',
    output: { file: 'dist/index.d.ts', format: 'es' },
    plugins: [dts()],
    external: [/node_modules/],
  },
]);

️ Hazard Prevention: Bundler type stripping removing necessary ambient declarations will break global augmentations. Configure verbatimModuleSyntax and explicitly import ambient types, or use rollup-plugin-dts to preserve global augmentations and namespace exports during tree-shaking.

Cross-Environment Validation and CI Integration

Publishing unvalidated .d.ts files is a primary cause of downstream build failures. Automated validation must run in CI to verify type resolution across target environments before npm publish.

The most reliable validation step is running tsc --noEmit against the generated declaration directory. This catches broken imports, missing ambient declarations, and resolution mismatches without emitting artifacts.

#!/usr/bin/env bash
set -euo pipefail

echo "🔍 Validating generated declarations..."
tsc --noEmit --project tsconfig.types.json --skipLibCheck false

echo "📦 Checking package exports and types..."
npx publint
npx attw --pack .

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "noEmit": true,
    "declaration": false,
    "skipLibCheck": false,
    "types": ["node", "jest"]
  },
  "include": ["dist/types/**/*.d.ts"]
}

️ Hazard Prevention: Setting skipLibCheck: true in validation configs masks resolution errors in third-party types. Always disable it during CI validation. CI pipelines skipping declaration validation lead to broken consumer experiences. Add a dedicated tsc --noEmit --project tsconfig.types.json step in CI that targets only the generated .d.ts output directory to catch resolution failures before npm publish.

# .github/workflows/validate-declarations.yml
name: Validate Declarations
on: [push, pull_request]
jobs:
  type-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - run: npm run build:types
      - run: npm run validate:types

️ Hazard Prevention: Always run publint and attw (Are The Types Wrong?) in CI to verify dual exports and type resolution accuracy across Node.js and browser environments. These tools catch mismatched exports fields and missing type declarations before they reach consumers.