TypeScript Declaration Webpack Plugin

Common errors

• ModuleNotFoundError: Module not found: Error: Can't resolve 'webpack' in '...'

  cause Webpack is a peer dependency and must be installed separately in your project.
  fix Run `npm install webpack@^4.0.0` or `yarn add webpack@^4.0.0` to install the compatible Webpack version.

• TypeError: TsDeclarationWebpackPlugin is not a constructor

  cause This usually indicates an incorrect import or require statement, such as using ES module `import` syntax in a CommonJS context, or attempting to destructure a non-object export.
  fix Ensure you are using `const TsDeclarationWebpackPlugin = require('ts-declaration-webpack-plugin');` in your Webpack configuration file.

• Declaration files not generated for some TypeScript files (e.g., .mts, .cts).

  cause The plugin's default `test` option only matches `.ts` and `.tsx` files, excluding newer or custom TypeScript extensions.
  fix Update the `test` option in the plugin configuration to include your specific file extensions: `new TsDeclarationWebpackPlugin({ test: /\.(ts|tsx|mts|cts)$/ })`.

• Webpack compilation fails with errors related to plugin API (e.g., 'hooks' property missing or undefined) when using Webpack 5.

  cause The plugin is only compatible with Webpack 4, and its internal APIs are not compatible with Webpack 5+.
  fix Downgrade your Webpack version to 4.x (`npm install webpack@^4.0.0`) or seek an alternative plugin that explicitly supports Webpack 5 and beyond.

Warnings

• breaking The plugin is explicitly designed for Webpack 4, specifying `webpack: "^4.0.0"` as a peer dependency. Using it with Webpack 5 or newer versions will likely lead to build failures or unexpected behavior due to significant API changes in Webpack's plugin system.
  Fix: Ensure your project uses Webpack 4.x. For Webpack 5+, consider alternative declaration bundling solutions or check for a newer major version of this plugin (if available) that explicitly supports Webpack 5+.
• gotcha By default, the plugin only processes files matching `test: /\.(ts|tsx)$/`. If your project uses other TypeScript-related extensions (e.g., `.mts`, `.cts`, or custom extensions), you must explicitly configure the `test` option in the plugin's constructor to include these extensions, otherwise, declarations will not be generated for them.
  Fix: Configure the `test` option when instantiating the plugin: `new TsDeclarationWebpackPlugin({ test: /\.(ts|tsx|mts|cts)$/ })` to match all desired file types.
• gotcha This plugin is designed to output a *single* bundled `.d.ts` file per Webpack entry point. It does not provide options for generating multiple, separate declaration files for individual modules within a single entry, which might be desired for more granular package distribution or specific library module structures.
  Fix: If granular declaration files are required, consider using `tsc --emitDeclarationOnly` directly or explore other tools/plugins that specifically support multi-file declaration output per entry point.

Install

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

Imports

• TsDeclarationWebpackPlugin
  wrong:

  import TsDeclarationWebpackPlugin from 'ts-declaration-webpack-plugin';

  correct:

  const TsDeclarationWebpackPlugin = require('ts-declaration-webpack-plugin');

  As of v1.x, the plugin's main export is designed for CommonJS environments. Using ES module `import` syntax directly for the main class may lead to runtime errors.

Quickstart

This Webpack configuration demonstrates how to integrate `ts-declaration-webpack-plugin` to generate bundled `.d.ts` files for 'app' and 'component' entries, alongside their compiled JavaScript.

const path = require('path');
const TsDeclarationWebpackPlugin = require('ts-declaration-webpack-plugin');

module.exports = {
    mode: 'production',
    entry: {
        app: './src/main.ts',
        component: './src/component.tsx',
    },
    output: {
        path: path.resolve(__dirname, 'dist'),
        filename: '[name].js',
        libraryTarget: 'umd'
    },
    module: {
        rules: [
            {
                test: /\.tsx?$/,
                use: 'ts-loader',
                exclude: /node_modules/,
            },
        ],
    },
    resolve: {
        extensions: ['.tsx', '.ts', '.js'],
    },
    plugins: [
        new TsDeclarationWebpackPlugin({
            name: '[name].d.ts', // Optional: customize declaration file name
            test: /\.(ts|tsx)$/, // Optional: customize file types to process
        }),
    ]
};