esbuild-fix-imports-plugin

1.0.23 verified Fri May 01 auth: no javascript

An ESBuild plugin (v1.0.23) that fixes import paths in bundleless ESBuild/tsup builds by resolving TypeScript path aliases, replacing directory imports with explicit index file paths, and appending correct file extensions. Released actively, it combines three sub-plugins (fixAliasPlugin, fixFolderImportsPlugin, fixExtensionsPlugin) and an optional writeFilePlugin for memory-based builds. Key differentiator: solves common issues when bundling is disabled and output files need correct relative imports for Node.js or browser consumption.

Common errors

error Error: writeFilePlugin requires write: false in esbuild options ↓

cause Using writeFilePlugin with write: true (default) causes conflict because the plugin writes files manually.

fix

Set write: false in ESBuild build options.

error Cannot find module 'esbuild-fix-imports-plugin' ↓

cause Package not installed or incorrect import path (e.g., using default import instead of named).

fix

Run npm install esbuild-fix-imports-plugin and use named import: import { fixImportsPlugin } from 'esbuild-fix-imports-plugin'.

error TypeError: fixImportsPlugin is not a function ↓

cause Importing the default export (undefined) instead of the named export.

fix

Use import { fixImportsPlugin } from 'esbuild-fix-imports-plugin' (curly braces).

Warnings

deprecated tsup is discouraged; the README states 'Consider using ESBuild directly as TSUP is deprecated.' ↓

fix Migrate to ESBuild directly with the plugin setup shown in the README.

gotcha write: false is required when using writeFilePlugin; setting write: true will cause build failures as the plugin expects to write files in memory. ↓

fix Set write: false in ESBuild options and use writeFilePlugin() to output files.

gotcha The plugin expects tsconfig.json with paths defined; missing or incorrect tsconfig can cause alias resolution to fail silently. ↓

fix Ensure tsconfig.json contains a paths mapping and the tsconfig option is properly passed to ESBuild.

Install

npm install esbuild-fix-imports-plugin

yarn add esbuild-fix-imports-plugin

pnpm add esbuild-fix-imports-plugin

Imports

fixImportsPlugin

wrong

import fixImportsPlugin from 'esbuild-fix-imports-plugin'

correct

import { fixImportsPlugin } from 'esbuild-fix-imports-plugin'

Named export, not default. Works with ESM and CJS via separate entry points.

fixAliasPlugin
wrong
```
const { fixAliasPlugin } = require('esbuild-fix-imports-plugin')
```
correct
```
import { fixAliasPlugin } from 'esbuild-fix-imports-plugin'
```
Named export, available as sub-export. CommonJS require may fail if package is ESM-only in future versions.

writeFilePlugin

wrong

import { writeFilePlugin } from 'esbuild-fix-imports-plugin'

correct

import { writeFilePlugin } from 'esbuild-fix-imports-plugin/dist/esm/writeFilePlugin.mjs'

Separate file, not exported from main entry; used in the recommended esbuild.mjs pattern.

Quickstart

Demonstrates using fixImportsPlugin with writeFilePlugin in an ESBuild script that fixes import paths in bundleless builds.

import { build } from 'esbuild';
import { fixImportsPlugin, writeFilePlugin } from 'esbuild-fix-imports-plugin';
import fg from 'fast-glob';

async function buildAll() {
  const entryPoints = await fg(['src/**/*'], { onlyFiles: true });
  await build({
    entryPoints,
    bundle: false,
    write: false,
    outdir: 'dist',
    platform: 'node',
    format: 'esm',
    plugins: [
      fixImportsPlugin(),
      writeFilePlugin(),
    ],
    tsconfig: './tsconfig.json',
  });
}
buildAll();