Registry / devops / esbuild-plugin-import-transform

esbuild-plugin-import-transform

library1.1.1jsnpmunverified

An esbuild plugin for transforming import paths and module specifiers during the build process. Current version is 1.1.1, actively maintained. It supports conditional renaming based on platform (browser/node), inline text replacements, and simple path overrides. Differentiates from generic esbuild plugins by focusing specifically on import transformation with platform-aware rules, runtime-free operation, and TypeScript type definitions included.

devops

npm install esbuild-plugin-import-transform

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · ESBUILD-PLUGIN-IMP

esbuild-plugin-import-transform

devopsjavascriptv1.1.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

default

✓ import importTransform from 'esbuild-plugin-import-transform'

✗ const importTransform = require('esbuild-plugin-import-transform')

ESM-only; package is type: module, require() will throw ERR_REQUIRE_ESM.

importTransform

✓ import importTransform from 'esbuild-plugin-import-transform'

✗ import { importTransform } from 'esbuild-plugin-import-transform'

Only default export exists; named export will be undefined.

type imports

✓ import type { ImportTransformOptions } from 'esbuild-plugin-import-transform'

✗ import { ImportTransformOptions } from 'esbuild-plugin-import-transform'

Options type is not exported as value; use import type for TypeScript types.

Demonstrates using esbuild-plugin-import-transform to replace lodash with lodash-es, inline text for ./utils, and conditionally map node:fs to memfs when platform is browser.

import { build } from 'esbuild'; import importTransform from 'esbuild-plugin-import-transform'; await build({ entryPoints: ['src/index.js'], bundle: true, outfile: 'dist/out.js', plugins: [ importTransform({ 'lodash': 'lodash-es', './utils': { text: 'export function helper() { return 42; }' }, 'node:fs': { platform: 'browser', to: 'memfs' } }) ] });

Debug

Known issues

breakingThe plugin is ESM-only and requires Node >=18 because it uses import.meta and top-level await. CommonJS require() will fail.

fix

Use import statement in an ES module context (type: 'module' in package.json or .mjs file).

affects: >=1.0.0

breakingThe package only provides a default export. Named exports like { importTransform } do not exist.

fix

Use default import: import importTransform from 'esbuild-plugin-import-transform'.

affects: >=1.0.0

deprecatedNo breaking changes have been declared; however, the plugin is early stage and future versions may introduce breaking changes.

fix

Pin version or follow release notes.

affects: <2.0.0

gotchaTransform options for platform-specific mappings only apply when the esbuild 'platform' build option matches exactly. If not set, default mapping applies.

fix

Ensure esbuild platform is set (e.g., 'browser' or 'node') and that the platform key in the option matches exactly.

affects: *

gotchaWhen providing 'text' in transform options, the replacement is plain text and not a full module; it must be valid JavaScript/TypeScript export statements.

fix

Use proper export syntax in the text string to avoid runtime errors.

affects: *

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/esbuild-plugin-import-transform/index.js not supported.

Using require() on an ESM-only package.

fix

Switch to import statement and ensure your project is configured for ES modules (type: 'module' in package.json, or use .mjs extension).

TypeError: importTransform is not a function

Named import instead of default import.

fix

Use default import: import importTransform from 'esbuild-plugin-import-transform'.

Unknown plugin option: ...

Invalid shape in the transform options object; key must be a string and value a string or object with to/text/platform.

fix

Ensure each key is a string module specifier and each value is either a string (target) or an object with 'to', 'text', or 'platform' keys.

Upgrade

Version history

1.1.1latest on npm

Audit

Dependencies

esbuildrequiredPeer dependency; the plugin works as an esbuild plugin and requires esbuild to be installed.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/luxass/esbuild-import-transform ↗

packageesbuild-plugin-import-transform ↗

homepagehttps://github.com/luxass/esbuild-import-transform ↗