TypeScript Declaration Webpack Plugin

Common errors

• Error: Plugin 'TypescriptDeclarationPlugin' not found

  cause The package `typescript-declaration-webpack-plugin` was not installed or is not correctly resolved in your project.
  fix Run `npm install --save-dev typescript-declaration-webpack-plugin` or `yarn add --dev typescript-declaration-webpack-plugin`.

• TS2307: Cannot find module '...' or its corresponding type declarations.

  cause TypeScript is unable to locate declaration files for an imported module, often because `declaration: true` is missing in `tsconfig.json` or the build process didn't generate them correctly before the plugin runs.
  fix Verify `"declaration": true` is present in `compilerOptions` of your `tsconfig.json`. Also, ensure `ts-loader` or similar is correctly configured in your Webpack rules to process TypeScript files and produce declarations.

• Webpack compilation fails, but no specific error from typescript-declaration-webpack-plugin is shown.

  cause The plugin might not be receiving any declaration files from the upstream TypeScript compilation, leading to an empty or non-functional output without explicit errors from the plugin itself.
  fix Check your `tsconfig.json` for `"declaration": true`. Ensure your `ts-loader` setup is generating `.d.ts` files in your build output before the plugin attempts to process them. You might temporarily disable `removeMergedDeclarations: true` to inspect intermediate `.d.ts` files.

Warnings

• gotcha The plugin relies on TypeScript generating declaration files. Ensure `compilerOptions.declaration` is set to `true` in your `tsconfig.json` file. Without this, the plugin will have no `.d.ts` files to merge.
  Fix: Add `"declaration": true` to your `compilerOptions` in `tsconfig.json`.
• breaking Versions `0.2.0` and `0.2.2` included fixes for "two serious issues." While specific breaking changes are not detailed, users upgrading from `v0.1.x` or earlier may encounter different behaviors or require adjustments due to these critical bug fixes and plugin reworks.
  Fix: Review your Webpack configuration and `tsconfig.json` after upgrading to these versions, and test your build output thoroughly. Consult the project's GitHub issues for more context if problems arise.
• gotcha When using ESM in your project (`type: module` in `package.json`), ensure your Webpack configuration is also set up for ESM or use dynamic `import()` for the plugin. Older Webpack configs often use CommonJS `require()`, which might conflict with newer module systems.
  Fix: For ESM projects, use `import { TypescriptDeclarationPlugin } from 'typescript-declaration-webpack-plugin';` in your `webpack.config.js` (if it supports ESM). For CommonJS, stick to `const TypescriptDeclarationPlugin = require('typescript-declaration-webpack-plugin');`.
• gotcha The plugin is designed to work with declaration files generated by a TypeScript loader (e.g., `ts-loader`). If you are using a different setup for TypeScript compilation (e.g., `babel-loader` without `declaration: true` in `tsconfig.json`), the plugin might not find any declaration files to process.
  Fix: Ensure your Webpack setup includes a TypeScript loader configured to emit declaration files, and that your `tsconfig.json` specifies `"declaration": true`.

Install

• npm install typescript-declaration-webpack-plugin npm
• yarn add typescript-declaration-webpack-plugin yarn
• pnpm add typescript-declaration-webpack-plugin pnpm

Imports

• TypescriptDeclarationPlugin
  wrong:

  const TypescriptDeclarationPlugin = require('typescript-declaration-webpack-plugin').default;

  correct:

  import TypescriptDeclarationPlugin from 'typescript-declaration-webpack-plugin';

  Since v0.3.0, the plugin class is also exported as a default for ESM compatibility. For CommonJS, `require('pkg')` directly returns the plugin constructor.
• TypescriptDeclarationPlugin (named)
  wrong:

  import TypescriptDeclarationPlugin = require('typescript-declaration-webpack-plugin');

  correct:

  import { TypescriptDeclarationPlugin } from 'typescript-declaration-webpack-plugin';

  Named exports for the plugin class were introduced in v0.3.0 for better ESM interoperability. Use this for explicit named imports.
• CommonJS require
  wrong:

  import { TypescriptDeclarationPlugin } from 'typescript-declaration-webpack-plugin';

  correct:

  const TypescriptDeclarationPlugin = require('typescript-declaration-webpack-plugin');

  This is the standard CommonJS `require` pattern for Node.js environments and older Webpack configurations, as shown in the package's README. Attempts to use ESM `import` syntax in a CommonJS context will lead to errors.

Quickstart

This Webpack configuration demonstrates how to set up `typescript-declaration-webpack-plugin` to bundle a TypeScript library, using `ts-loader` for compilation and emitting a single `index.d.ts` file alongside the bundled JavaScript output.

const path = require('path');
const TypescriptDeclarationPlugin = require('typescript-declaration-webpack-plugin');

module.exports = {
  mode: 'production',
  entry: './src/index.ts',
  output: {
    filename: 'bundle.js',
    path: path.resolve(__dirname, 'dist'),
    libraryTarget: 'umd',
    library: 'MyLibrary',
  },
  module: {
    rules: [
      {
        test: /\.tsx?$/,
        use: 'ts-loader',
        exclude: /node_modules/,
      },
    ],
  },
  resolve: {
    extensions: ['.tsx', '.ts', '.js'],
  },
  plugins: [
    new TypescriptDeclarationPlugin({
      out: 'index.d.ts', // Name of the bundled declaration file
      removeMergedDeclarations: true, // Remove individual .d.ts files after merging
      removeComments: true, // Remove comments from the final .d.ts file
    }),
  ],
  externals: { // Example for common library scenarios
    react: 'React',
    'react-dom': 'ReactDOM',
  },
};