esbuild-dynamic-import-plugin

0.0.12 verified Fri May 01 auth: no javascript

An esbuild plugin that transforms named imports from a library (e.g., antd, lodash) into modular 'import on demand' requires, converting import { Button } from 'antd' to require('antd/lib/button/index'). Supports style injection (CSS/LESS files), custom library directory, camel-to-dash conversion, and custom name functions. Version 0.0.12, no regular release cadence. Key differentiator: brings babel-plugin-import-like functionality to esbuild, enabling tree-shaking of large component libraries. Peer dependency on lodash.

Common errors

error Error: Cannot find module 'antd/lib/button/index' ↓

cause The plugin transforms 'antd' imports to paths like 'antd/lib/button/index', but the actual file may differ (e.g., 'antd/es/button/index').

fix

Set the 'libraryDirectory' option to match the library's actual subdirectory (e.g., 'es' for antd ES modules).

error TypeError: importPlugin is not a function ↓

cause Using a named import (import { importPlugin } from ...) instead of default import.

fix

Use 'const importPlugin = require("esbuild-dynamic-import-plugin")' or 'import importPlugin from "esbuild-dynamic-import-plugin"'.

error Module not found: Can't resolve 'antd/lib/button/style/css' ↓

cause The style option 'css' is set, but the library uses a different path (e.g., 'antd/es/button/style/css').

fix

Set 'libraryDirectory' to 'es' or configure 'styleLibraryDirectory' to match the actual path.

Warnings

gotcha The plugin modifies import paths to point to library internals (e.g., antd/lib/button/index). This relies on the library's internal structure and may break with library updates if they change their build output. ↓

fix Pin library versions (e.g., antd@4.x) and test after upgrades. Use semver ranges cautiously.

gotcha Style injection with style: true imports raw LESS/Sass source files. This requires a CSS loader/plugin in esbuild (e.g., esbuild-sass-plugin) or a separate build step to process those files. ↓

fix Ensure your esbuild configuration includes a CSS plugin (e.g., 'esbuild-sass-plugin' for Sass) or compile styles separately.

deprecated The plugin uses __toModule wrapper which may not align with esbuild's default module handling in newer versions. Test with esbuild 0.14+. ↓

fix If you encounter issues with __toModule, consider using the plugin's customName function to adjust imports, or test compatibility with your esbuild version.

Install

npm install esbuild-dynamic-import-plugin

yarn add esbuild-dynamic-import-plugin

pnpm add esbuild-dynamic-import-plugin

Imports

importPlugin
wrong
```
import importPlugin from 'esbuild-dynamic-import-plugin'
```
correct
```
const importPlugin = require('esbuild-dynamic-import-plugin')
```
The plugin exports a single function via CommonJS; ESM import is not supported as it uses module.exports.

default

wrong

import { importPlugin } from 'esbuild-dynamic-import-plugin'

correct

import importPlugin from 'esbuild-dynamic-import-plugin'

The module exports a default function, not a named export. Use default import in ESM or require in CJS.

require style
```
const importPlugin = require('esbuild-dynamic-import-plugin')
```
CommonJS require is the standard pattern; ensure esbuild config uses a .js or .cjs file.

Quickstart

Demonstrates esbuild configuration with the plugin to transform antd imports on demand, including style injection.

const esbuild = require('esbuild');
const importPlugin = require('esbuild-dynamic-import-plugin');
esbuild.build({
  entryPoints: ['app.js'],
  bundle: true,
  outfile: 'out.js',
  plugins: [
    importPlugin({
      options: [
        {
          libraryName: 'antd',
          libraryDirectory: 'lib',
          style: true
        }
      ]
    })
  ]
}).catch(() => process.exit(1));