{"id":10899,"library":"fix-dts-default-cjs-exports","title":"Fix TypeScript CJS Default Exports Declarations","description":"This utility addresses a common issue in TypeScript declaration generation, specifically when dealing with default exports within CommonJS modules. It provides a programmatic API and a Rollup plugin to correctly transform `d.mts` files into CommonJS-compatible `d.ts` and `d.cts` files, ensuring interoperability. The current stable version is 1.0.1, with recent releases indicating an active maintenance cadence primarily focused on bug fixes and compatibility. Key differentiators include its direct integration via a Rollup plugin, making it suitable for build tools like `unbuild` (which leverages it internally since v3.5.0), and its specific focus on the nuanced problem of default exports in CJS TypeScript declarations where other bundlers or compilers might produce incorrect outputs. It provides a targeted solution for a specific TypeScript build problem, rather than being a general-purpose bundler.","status":"active","version":"1.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/userquin/fix-dts-default-cjs-exports","tags":["javascript","rollup","cjs","typescript","default exports"],"install":[{"cmd":"npm install fix-dts-default-cjs-exports","lang":"bash","label":"npm"},{"cmd":"yarn add fix-dts-default-cjs-exports","lang":"bash","label":"yarn"},{"cmd":"pnpm add fix-dts-default-cjs-exports","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"The package provides a Rollup plugin for integration into build processes.","package":"rollup","optional":true},{"reason":"The package is designed to integrate with unbuild, providing a Rollup plugin that unbuild v3.5.0+ uses internally, or can be manually configured for older versions.","package":"unbuild","optional":true}],"imports":[{"note":"This is the programmatic API function for direct usage.","wrong":"const { fixDtsDefaultCjsExports } = require('fix-dts-default-cjs-exports')","symbol":"fixDtsDefaultCjsExports","correct":"import { fixDtsDefaultCjsExports } from 'fix-dts-default-cjs-exports'"},{"note":"The Rollup plugin is exposed via a subpath import to avoid polluting the main entry point. Ensure you import from `/rollup`.","wrong":"import { FixDtsDefaultCjsExportsPlugin } from 'fix-dts-default-cjs-exports'","symbol":"FixDtsDefaultCjsExportsPlugin","correct":"import { FixDtsDefaultCjsExportsPlugin } from 'fix-dts-default-cjs-exports/rollup'"},{"note":"Type imports should also reference the `/rollup` subpath for the plugin-specific options.","symbol":"PluginOptions","correct":"import type { PluginOptions } from 'fix-dts-default-cjs-exports/rollup'"}],"quickstart":{"code":"import { FixDtsDefaultCjsExportsPlugin } from 'fix-dts-default-cjs-exports/rollup';\nimport { defineBuildConfig } from 'unbuild';\n\nexport default defineBuildConfig({\n  entries: ['./src/index'],\n  declaration: true,\n  clean: true,\n  rollup: { emitCJS: true },\n  hooks: {\n    'rollup:dts:options': (ctx, options) => {\n      // Optional: Uncomment to remove unbuild's internal plugin if it conflicts or you need full control\n      // options.plugins = options.plugins.filter((p) => {\n      //   if (!p || typeof p === 'string' || Array.isArray(p) || !('name' in p))\n      //     return true;\n      //   return p.name !== 'unbuild-fix-cjs-export-type';\n      // });\n      options.plugins.push(FixDtsDefaultCjsExportsPlugin({\n        warn: message => ctx.warnings.add(message)\n      }));\n    }\n  }\n});","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.0.1"},{"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`).","message":"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.","severity":"gotcha","affected_versions":">=0.0.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.0.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.1"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure you are importing the plugin from the correct subpath: `import { FixDtsDefaultCjsExportsPlugin } from 'fix-dts-default-cjs-exports/rollup'`.","cause":"Incorrect import path for the Rollup plugin.","error":"Cannot find name 'FixDtsDefaultCjsExportsPlugin'."},{"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.","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).","error":"Error: The plugin 'unbuild-fix-cjs-export-type' was already used."},{"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.","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.","error":"TypeScript declarations are incorrect for default exports in CommonJS output."}],"ecosystem":"npm"}