{"id":25416,"library":"esbuild-plugin-transform-ext","title":"esbuild-plugin-transform-ext","description":"An esbuild plugin that transforms file extensions in bundled output, addressing esbuild's limitation of not being able to change extensions in the middle of the build process. Version 0.2.5 (current stable) is released under the MIT license. It allows defining per-pattern rules to map output extensions (e.g., .js to .cjs or .mjs) after esbuild's standard out-extension resolution, useful for dual CJS/ESM packages or mixed-format outputs. The plugin is lightweight, TypeScript-first with bundled types, and requires esbuild >=0.19.0 as a peer dependency. Compared to manual post-processing scripts, it integrates directly into esbuild's plugin pipeline without separate tooling.","status":"active","version":"0.2.5","language":"javascript","source_language":"en","source_url":"https://github.com/antongolub/misc","tags":["javascript","esbuild","plugin","extension","transform","typescript"],"install":[{"cmd":"npm install esbuild-plugin-transform-ext","lang":"bash","label":"npm"},{"cmd":"yarn add esbuild-plugin-transform-ext","lang":"bash","label":"yarn"},{"cmd":"pnpm add esbuild-plugin-transform-ext","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"peer dependency required for plugin integration; version >=0.19.0","package":"esbuild","optional":false}],"imports":[{"note":"ESM-only package; CommonJS require will fail. Use dynamic import() if needed.","wrong":"const transformExtPlugin = require('esbuild-plugin-transform-ext')","symbol":"transformExtPlugin","correct":"import { transformExtPlugin } from 'esbuild-plugin-transform-ext'"},{"note":"Type-only import; do not use value import as it is not a runtime export.","wrong":"import { TransformExtOptions } from 'esbuild-plugin-transform-ext'","symbol":"TransformExtOptions","correct":"import type { TransformExtOptions } from 'esbuild-plugin-transform-ext'"},{"note":"Package has both named and default export; default export is the same as named for convenience.","wrong":"import { default as transformExtPlugin } from 'esbuild-plugin-transform-ext'","symbol":"default export","correct":"import transformExtPlugin from 'esbuild-plugin-transform-ext'"}],"quickstart":{"code":"import { build } from 'esbuild';\nimport { transformExtPlugin } from 'esbuild-plugin-transform-ext';\n\nconst plugin = transformExtPlugin({\n  cwd: process.cwd(),\n  rules: [\n    {\n      pattern: /\\.mjs$/,\n      map: {\n        '.js': '.mjs',\n      },\n    },\n  ],\n});\n\nawait build({\n  entryPoints: ['src/index.ts'],\n  outdir: 'dist',\n  plugins: [plugin],\n  outExtension: { '.js': '.mjs' },\n  format: 'esm',\n});","lang":"typescript","description":"Shows basic usage of transformExtPlugin with a rule to rename .js to .mjs for .mjs output files."},"warnings":[{"fix":"If using esbuild >=0.19.0, set absWorkingDir in build options instead of cwd in plugin options.","message":"The 'cwd' option may be removed in future versions in favor of 'absWorkingDir' from esbuild options.","severity":"deprecated","affected_versions":">=0.2.0"},{"fix":"Test your regex against the output path (e.g., /dist/sub/file.js) not the source path.","message":"Patterns are applied to output file paths, not input paths; ensure pattern matches the final path after outdir and outExtension processing.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Always set outExtension in esbuild build options to ensure default mappings are correct.","message":"The 'map' option defaults to build.initialOptions.outExtension; if outExtension is not set, no transformation occurs.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Ensure each rule has a 'map' object with at least one key (e.g., { '.js': '.mjs' }).","cause":"Missing or invalid 'map' option in rule; the plugin tries to replace using undefined map.","error":"Error: Plugin 'transform-ext' returned an error: Cannot read properties of undefined (reading 'replace')"},{"fix":"Use import { transformExtPlugin } from 'esbuild-plugin-transform-ext' or dynamic import().","cause":"Using CommonJS require() on an ESM-only package.","error":"TypeError: (0 , plugin_transform_ext.transformExtPlugin) is not a function"},{"fix":"Use a RegExp literal: pattern: /\\.cjs$/, not pattern: '.cjs$'.","cause":"Passing a string instead of RegExp for the 'pattern' option.","error":"Error: Plugin 'transform-ext' returned an error: Pattern must be a RegExp"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}