Fix TypeScript CJS Default Exports Declarations

Common errors

• Cannot find name 'FixDtsDefaultCjsExportsPlugin'.

  cause Incorrect import path for the Rollup plugin.
  fix Ensure you are importing the plugin from the correct subpath: `import { FixDtsDefaultCjsExportsPlugin } from 'fix-dts-default-cjs-exports/rollup'`.

• Error: The plugin 'unbuild-fix-cjs-export-type' was already used.

  cause You might be trying to add `fix-dts-default-cjs-exports` plugin to `unbuild` which already has an internal, potentially conflicting, plugin for the same purpose (especially in older `unbuild` versions).
  fix If using an `unbuild` version older than 3.5.0, you may need to filter out `unbuild`'s internal plugin within the `rollup:dts:options` hook before pushing the `fix-dts-default-cjs-exports` plugin, as commented in the quickstart example.

• TypeScript declarations are incorrect for default exports in CommonJS output.

  cause The `fix-dts-default-cjs-exports` plugin is not correctly configured or not being applied in your build process, or your build tool is not supported.
  fix Verify that the plugin is correctly integrated as a Rollup plugin, especially within `unbuild`'s `rollup:dts:options` hook with `rollup.emitCJS` enabled. If using `tsup` or `pkgroll`, consider a post-build programmatic fix.

Warnings

• breaking Version 1.0.0 introduced breaking changes related to the inclusion of Node.js 10 types. Users upgrading from pre-1.0.0 versions should verify their build environment's Node.js compatibility.
  Fix: Ensure your project's `tsconfig.json` and build environment are compatible with the Node.js 10 type inclusions, or adjust `target` and `lib` settings as necessary.
• gotcha When using the Rollup plugin with `unbuild`, you *must* register the plugin directly when `rollup.emitCJS = true` is enabled. Failing to do so can lead to incorrect transformations or the plugin not being applied effectively.
  Fix: Ensure `rollup.emitCJS: true` is set in your `unbuild` configuration and the `FixDtsDefaultCjsExportsPlugin` is explicitly added to `options.plugins` within the `rollup:dts:options` hook, as shown in the quickstart.
• gotcha The package's Rollup plugin is intended to fix default CJS exports. It does not control file generation itself. Misconfiguration of your build tool's declaration options (e.g., `unbuild`'s `declaration` option) can still lead to unexpected output files.
  Fix: Consult the `declaration` option in your build tool's documentation (e.g., `unbuild`'s configuration) to ensure correct file output paths and types (`d.ts`, `d.cts`, `d.mts`).
• gotcha This package is not directly compatible with build tools like `tsup` or `pkgroll` as they currently do not expose hooks to replace or augment their internal Rollup configurations. Direct integration is limited to tools that allow Rollup plugin injection.
  Fix: For `tsup` or `pkgroll`, you may need to use a post-build script to apply the `fixDtsDefaultCjsExports` API programmatically, or wait for these tools to introduce plugin hooks.
• gotcha Version 1.0.1 added a `// @ts-ignore` annotation to default exports when mixed exports are present. While this fixes a specific bug, developers should be aware that `ts-ignore` masks potential TypeScript issues and should be understood in the context of the CJS/ESM interop problem this library solves.
  Fix: No direct fix needed, but be aware of the annotation. If encountering unexpected TypeScript errors after upgrading, review how mixed exports are handled in your declaration files.

Install

• npm install fix-dts-default-cjs-exports npm
• yarn add fix-dts-default-cjs-exports yarn
• pnpm add fix-dts-default-cjs-exports pnpm

Imports

• fixDtsDefaultCjsExports
  wrong:

  const { fixDtsDefaultCjsExports } = require('fix-dts-default-cjs-exports')

  correct:

  import { fixDtsDefaultCjsExports } from 'fix-dts-default-cjs-exports'

  This is the programmatic API function for direct usage.
• FixDtsDefaultCjsExportsPlugin
  wrong:

  import { FixDtsDefaultCjsExportsPlugin } from 'fix-dts-default-cjs-exports'

  correct:

  import { FixDtsDefaultCjsExportsPlugin } from 'fix-dts-default-cjs-exports/rollup'

  The Rollup plugin is exposed via a subpath import to avoid polluting the main entry point. Ensure you import from `/rollup`.
• PluginOptions

  import type { PluginOptions } from 'fix-dts-default-cjs-exports/rollup'

  Type imports should also reference the `/rollup` subpath for the plugin-specific options.

Quickstart

This quickstart demonstrates how to integrate the Rollup plugin with `unbuild` to ensure correct TypeScript declaration output for default CommonJS exports. This configuration is for `unbuild` versions prior to v3.5.0 or when needing custom plugin options.

import { FixDtsDefaultCjsExportsPlugin } from 'fix-dts-default-cjs-exports/rollup';
import { defineBuildConfig } from 'unbuild';

export default defineBuildConfig({
  entries: ['./src/index'],
  declaration: true,
  clean: true,
  rollup: { emitCJS: true },
  hooks: {
    'rollup:dts:options': (ctx, options) => {
      // Optional: Uncomment to remove unbuild's internal plugin if it conflicts or you need full control
      // options.plugins = options.plugins.filter((p) => {
      //   if (!p || typeof p === 'string' || Array.isArray(p) || !('name' in p))
      //     return true;
      //   return p.name !== 'unbuild-fix-cjs-export-type';
      // });
      options.plugins.push(FixDtsDefaultCjsExportsPlugin({
        warn: message => ctx.warnings.add(message)
      }));
    }
  }
});