{"id":21245,"library":"esbuild-plugin-file-path-extensions","title":"esbuild-plugin-file-path-extensions","description":"This esbuild plugin automatically adds file extensions to import/export specifiers in bundled JavaScript output, addressing the common requirement for explicit extensions when targeting Node.js ESM or other environments that enforce extension inclusion. Version 2.1.4 (npm) requires Node >=14 and npm >=7. It ships with TypeScript types and has zero runtime dependencies. Unlike manual post-processing or bundler-agnostic solutions, this integrates directly as an esbuild plugin, offering fine-grained control over which extension (.js, .mjs, .cjs) to append based on the build target. The plugin handles dynamic imports, re-exports, and preserves URL imports. It sees active maintenance with regular updates aligned to esbuild API changes.","status":"active","version":"2.1.4","language":"javascript","source_language":"en","source_url":"https://github.com/favware/esbuild-plugin-file-path-extensions","tags":["javascript","esbuild","esbuild plugin","esbuild-plugin","typescript"],"install":[{"cmd":"npm install esbuild-plugin-file-path-extensions","lang":"bash","label":"npm"},{"cmd":"yarn add esbuild-plugin-file-path-extensions","lang":"bash","label":"yarn"},{"cmd":"pnpm add esbuild-plugin-file-path-extensions","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This package is ESM-only (no CJS export). Use dynamic import or top-level await if needed in CommonJS projects.","wrong":"const filePathExtensions = require('esbuild-plugin-file-path-extensions')","symbol":"default (the plugin function)","correct":"import filePathExtensions from 'esbuild-plugin-file-path-extensions'"},{"note":"The package exports a default function, not a named export. TypeScript users should import the plugin function as default and use esbuild's Plugin type separately.","wrong":"import { filePathExtensions } from 'esbuild-plugin-file-path-extensions'","symbol":"Plugin type (TypeScript)","correct":"import type { Plugin } from 'esbuild'\nimport filePathExtensions from 'esbuild-plugin-file-path-extensions'"},{"note":"The default export is a factory function, not a class. It must be called with options.","wrong":"new filePathExtensions()","symbol":"Calling the function","correct":"filePathExtensions({ inFileExtension: '.ts', outFileExtension: '.mjs' })"}],"quickstart":{"code":"import * as esbuild from 'esbuild';\nimport filePathExtensions from 'esbuild-plugin-file-path-extensions';\n\nawait esbuild.build({\n  entryPoints: ['src/index.ts'],\n  outdir: 'dist',\n  bundle: true,\n  format: 'esm',\n  platform: 'node',\n  target: 'node14',\n  plugins: [\n    filePathExtensions({\n      inFileExtension: '.ts',\n      outFileExtension: '.mjs'\n    })\n  ]\n});\n\nconsole.log('Build complete with .mjs extensions added to imports/outputs.');","lang":"typescript","description":"Demonstrates using the plugin with esbuild to convert .ts imports to .mjs extensions for Node ESM output."},"warnings":[{"fix":"Ensure all files requiring extension rewriting are included in the build via entryPoints or resolve extensions.","message":"The plugin only processes files that are part of the esbuild build; it does not transform external dependencies unless they are bundled.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use distinct extensions like .ts -> .mjs or .ts -> .js for actual effect.","message":"If you set outFileExtension to the same as the original extension (e.g., .ts --> .ts), no changes occur. This is intentional but may confuse users expecting transformation.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Change `import { filePathExtensions } from 'esbuild-plugin-file-path-extensions'` to `import filePathExtensions from 'esbuild-plugin-file-path-extensions'`.","message":"Version 2.0.0 changed the default export from a named export to a default export. Old imports using named import will break.","severity":"breaking","affected_versions":">=2.0.0 <3.0.0"},{"fix":"Use esbuild's `alias` or `external` settings for bare specifiers.","message":"The plugin does not handle bare specifiers (e.g., 'lodash') – only relative/absolute imports with explicit extensions.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Change to: `import filePathExtensions from 'esbuild-plugin-file-path-extensions'`","cause":"Using a named import instead of default import (common mistake after v2 breaking change).","error":"TypeError: filePathExtensions is not a function"},{"fix":"Switch your project to ESM (type: module in package.json) or use dynamic import: `const filePathExtensions = (await import('esbuild-plugin-file-path-extensions')).default;`","cause":"Project is in a CommonJS module scope and tries to require() the package, which is ESM-only.","error":"Error: Cannot find module 'esbuild-plugin-file-path-extensions'"},{"fix":"Set inFileExtension to match the file extensions in your source (e.g., '.ts') and outFileExtension to the desired output extension (e.g., '.mjs').","cause":"The inFileExtension does not match the actual extension used in import statements, or the outFileExtension matches the original extension.","error":"No matching files found: ... The plugin worked but no import paths were rewritten"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}