Registry / devops / esbuild-plugin-file-path-extensions

esbuild-plugin-file-path-extensions

library2.1.4jsnpmunverified

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.

devops web-framework

npm install esbuild-plugin-file-path-extensions

github ↗package ↗

INSTALL

IMPORT

SIG · ESBUILD-PLUGIN-FIL

esbuild-plugin-file-path-extensions

devopsjavascriptv2.1.4

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–223 runs

build_error

glibc

node 18–223 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default (the plugin function)

✓ import filePathExtensions from 'esbuild-plugin-file-path-extensions'

✗ const filePathExtensions = require('esbuild-plugin-file-path-extensions')

This package is ESM-only (no CJS export). Use dynamic import or top-level await if needed in CommonJS projects.

Plugin type (TypeScript)

✓ import type { Plugin } from 'esbuild' import filePathExtensions from 'esbuild-plugin-file-path-extensions'

✗ import { filePathExtensions } from 'esbuild-plugin-file-path-extensions'

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.

Calling the function

✓ filePathExtensions({ inFileExtension: '.ts', outFileExtension: '.mjs' })

✗ new filePathExtensions()

The default export is a factory function, not a class. It must be called with options.

Demonstrates using the plugin with esbuild to convert .ts imports to .mjs extensions for Node ESM output.

import * as esbuild from 'esbuild'; import filePathExtensions from 'esbuild-plugin-file-path-extensions'; await esbuild.build({ entryPoints: ['src/index.ts'], outdir: 'dist', bundle: true, format: 'esm', platform: 'node', target: 'node14', plugins: [ filePathExtensions({ inFileExtension: '.ts', outFileExtension: '.mjs' }) ] }); console.log('Build complete with .mjs extensions added to imports/outputs.');

Debug

Known issues

gotchaThe plugin only processes files that are part of the esbuild build; it does not transform external dependencies unless they are bundled.

fix

Ensure all files requiring extension rewriting are included in the build via entryPoints or resolve extensions.

affects: >=1.0.0

gotchaIf 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.

fix

Use distinct extensions like .ts -> .mjs or .ts -> .js for actual effect.

affects: >=1.0.0

breakingVersion 2.0.0 changed the default export from a named export to a default export. Old imports using named import will break.

fix

Change `import { filePathExtensions } from 'esbuild-plugin-file-path-extensions'` to `import filePathExtensions from 'esbuild-plugin-file-path-extensions'`.

affects: >=2.0.0 <3.0.0

gotchaThe plugin does not handle bare specifiers (e.g., 'lodash') – only relative/absolute imports with explicit extensions.

fix

Use esbuild's `alias` or `external` settings for bare specifiers.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: filePathExtensions is not a function

Using a named import instead of default import (common mistake after v2 breaking change).

fix

Change to: `import filePathExtensions from 'esbuild-plugin-file-path-extensions'`

Error: Cannot find module 'esbuild-plugin-file-path-extensions'

Project is in a CommonJS module scope and tries to require() the package, which is ESM-only.

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;`

No matching files found: ... The plugin worked but no import paths were rewritten

The inFileExtension does not match the actual extension used in import statements, or the outFileExtension matches the original extension.

fix

Set inFileExtension to match the file extensions in your source (e.g., '.ts') and outFileExtension to the desired output extension (e.g., '.mjs').

Upgrade

Version history

2.1.4latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/favware/esbuild-plugin-file-path-extensions ↗

packagehttps://www.npmjs.com/package/esbuild-plugin-file-path-extensions ↗