TypeScript Tooling Showdown: API Extractor, TSD, TypeDoc, and the Legacy Generator

When building and maintaining TypeScript libraries, developers often face a confusing array of tools for handling declaration files (.d.ts) and documentation. While the TypeScript compiler (tsc) handles the basics, professional workflows often require specialized tools to bundle declarations, test type safety, or generate rich documentation. Let's break down @microsoft/api-extractor, dts-generator, tsd, and typedoc to see where each fits in a modern architecture.

📦 Bundling Declarations: Rolling Up vs. Concatenating

One of the most common pain points in library development is managing multiple internal .d.ts files. Consumers usually prefer a single entry point. This is where @microsoft/api-extractor and the legacy dts-generator differ significantly.

@microsoft/api-extractor analyzes your compiled output and rolls up all declarations into a single .d.ts file. It also trims unused exports based on your configuration, ensuring a clean public API.

// api-extractor.json configuration
{
  "mainEntryPointFilePath": "<projectFolder>/lib/index.d.ts",
  "bundledPackages": [],
  "compiler": {
    "tsconfigFilePath": "<projectFolder>/tsconfig.json"
  },
  "apiReport": {
    "enabled": true
  },
  "dtsRollup": {
    "enabled": true,
    "untrimmedFilePath": "<projectFolder>/dist/my-lib.d.ts"
  }
}

dts-generator was an early solution that simply concatenated files in a specific order. It lacks the semantic understanding of the code that api-extractor has and does not handle trimming or API validation.

# dts-generator: CLI usage (Legacy)
# Concatenates all .d.ts files from src into dist/index.d.ts
dts-generator --out dist/index.d.ts --name my-lib --src src/**/*.d.ts

tsd does not bundle files. It focuses purely on testing the resulting types.

// tsd: No bundling capability
// This tool is used in a test file to assert types, not to create output files
import { expectType } from 'tsd';
// ... assertions here

typedoc also does not bundle declaration files for distribution. It reads them to generate documentation but leaves the build artifacts untouched.

# typedoc: Generates HTML, not .d.ts bundles
typedoc --out docs ./src/index.ts

🧪 Testing Types: The Role of TSD

While other tools focus on building or documenting, tsd fills a critical gap: verifying that your types actually work as intended for the end user.

tsd allows you to write tests that assert types without running any JavaScript. If the types change in a breaking way, the test fails.

// __tests__/index.test-d.ts
import { expectType, expectError } from 'tsd';
import { MyFunction } from '../dist';

// Asserts that MyFunction returns a string
expectType<string>(MyFunction('input'));

// Asserts that passing a number causes a type error
expectError(MyFunction(123));

@microsoft/api-extractor performs a different kind of validation. It checks your API surface against a stored "signature" file to ensure you haven't accidentally changed public contracts.

# api-extractor: Validates API surface against a baseline
npx api-extractor run --local

# If you changed a public method signature, this command fails
# and prompts you to update the .api.md report file.

dts-generator has no testing capabilities. It is purely a file manipulation tool.

# dts-generator: No test command exists
# Usage is limited to file generation only

typedoc does not test types. However, if your types are invalid, TypeDoc may fail to parse the source files, acting as a passive sanity check.

# typedoc: Fails if source has syntax errors, but doesn't assert logic
typedoc --skipErrorChecking false ./src

📚 Documentation Generation: Static Sites vs. API Reports

Documentation needs vary by project. Some teams need a full website; others need a strict changelog of API changes.

typedoc excels at creating beautiful, navigable HTML documentation sites from JSDoc comments and TypeScript types.

# typedoc: Generate a full HTML site
typedoc --out ./docs --entryPointStrategy expand ./src

// Result: A folder of HTML files with search, hierarchy, and code highlighting

@microsoft/api-extractor generates a Markdown API report (.api.md). This isn't a website for users, but a precise contract for maintainers to review changes.

// Output: temp/my-lib.api.md (Generated by api-extractor)
## Functions

### myFunction

> Signature: `myFunction(input: string): string`
>
> Remarks:
> Performs a specific operation on the input string.

dts-generator does not generate documentation. It only produces a combined .d.ts file which serves as raw data for IDEs, not human-readable docs.

// dts-generator output: A raw .d.ts file
// Not suitable for direct human reading as documentation
declare module 'my-lib' {
  export function myFunction(input: string): string;
}

tsd does not generate documentation. Its output is strictly pass/fail test results in the terminal.

# tsd output: Terminal test results
# ✔  index.test-d.ts
# ✖  index.test-d.ts (if types mismatch)

⚠️ Deprecation Warning: The Case Against dts-generator

It is crucial to note that dts-generator is effectively deprecated for modern workflows. Before TypeScript 2.0, developers needed external tools to combine declaration files. Today, the TypeScript compiler supports declarationMap and modern bundlers (like Rollup or Vite) can handle .d.ts files natively. More importantly, @microsoft/api-extractor provides a superior, semantically aware alternative for rolling up types.

// Modern Alternative: Using TypeScript native features + api-extractor
// tsconfig.json
{
  "compilerOptions": {
    "declaration": true,
    "declarationMap": true // Native source mapping for .d.ts
  }
}

// Then use api-extractor for the final rollup, avoiding dts-generator entirely.

Using dts-generator in a new project introduces technical debt and removes the safety checks provided by newer tools.

🌐 Real-World Scenarios

Scenario 1: Publishing a New UI Library to NPM

You are building a component library and want to ensure consumers get a single type definition file and that you don't break APIs accidentally.

• ✅ Best choice: @microsoft/api-extractor
• Why? It bundles your types, trims internal APIs, and enforces a strict API contract via the .api.md report.

// package.json script
"scripts": {
  "build": "tsc && api-extractor run --local"
}

Scenario 2: Verifying Types for a Utility Package

You maintain a low-level utility package and need to guarantee that your types support both string and number inputs without writing runtime tests.

• ✅ Best choice: tsd
• Why? It allows you to codify type expectations as test cases that run in CI.

// __tests__/utils.test-d.ts
import { expectType } from 'tsd';
expectType<number | string>(myUtil(1));
expectType<number | string>(myUtil('a'));

Scenario 3: Creating Developer Documentation for an Internal Tool

Your team needs a searchable website to understand how to use the internal design system.

• ✅ Best choice: typedoc
• Why? It generates a static site with navigation, search, and examples directly from code comments.

# Command to generate docs for the team wiki
typedoc --out ./wiki-src --theme default ./src/components

Scenario 4: Legacy Migration

You are maintaining an old library that uses dts-generator to merge files.

• ✅ Best choice: Migrate to @microsoft/api-extractor
• Why? dts-generator is obsolete. Moving to api-extractor improves reliability and adds API validation.

// Migration step: Replace dts-generator call in build script
// OLD: dts-generator --out dist/index.d.ts ...
// NEW: api-extractor run

📌 Summary Table

💡 Final Recommendation

For professional TypeScript development, your toolkit should look like this:

1. Use @microsoft/api-extractor for your build pipeline. It is the only robust solution for bundling declarations and enforcing API stability in published packages.
2. Use tsd in your test suite. It ensures your types remain correct and backward-compatible without bloating your runtime code.
3. Use typedoc if you need a public-facing documentation website. It complements api-extractor by providing the human-readable layer on top of your strict API definitions.
4. Avoid dts-generator. It solves a problem that modern TypeScript and api-extractor have already solved better. Removing it simplifies your dependency tree and reduces risk.

By combining these tools, you create a workflow that not only builds code but also guarantees the quality and usability of your types for every consumer.