esbuild-plugin-inline-import

1.1.0 verified Mon Apr 27 auth: no javascript maintenance

An esbuild plugin that inlines the contents of static imports matching a configurable filter (default: `inline:` prefix). Current stable version is 1.1.0, with a maintenance status. It offers a simple `transform` callback to process imported file contents (e.g., run Sass, prepend headers), and supports stacking multiple instances for different import prefixes. Unlike generic esbuild plugins, this one is purpose-built for inlining with minimal configuration. Works with esbuild's bundling pipeline and ships TypeScript definitions. Release cadence is low (last release in 2022).

Common errors

error Could not resolve 'inline:./file.txt' ↓

cause The plugin is not registered or is placed after other plugins that resolve imports.

fix

Ensure inlineImportPlugin() is the first plugin in the plugins array.

error TypeError: inlineImportPlugin is not a function ↓

cause Incorrect import style: using named import for a default export.

fix

Use default import: import inlineImportPlugin from 'esbuild-plugin-inline-import' or const inlineImportPlugin = require('esbuild-plugin-inline-import').

error Cannot find module 'esbuild-plugin-inline-import' ↓

cause Package not installed or not in `node_modules`.

fix

Run npm install --save-dev esbuild-plugin-inline-import.

Warnings

gotcha Plugin must be placed before other plugins in the plugins array, otherwise resolution errors may occur. ↓

fix Ensure `inlineImportPlugin()` is the first plugin in the `plugins` array.

gotcha The `transform` function is called for every matching import; expensive operations (e.g., Sass compilation) can significantly slow down esbuild builds. ↓

fix Avoid heavy transforms or cache results if possible. Test build performance with and without the plugin.

deprecated The `namespace` option defaults to a random string per instance. Setting a custom namespace may cause conflicts if multiple instances share the same namespace. ↓

fix Only override `namespace` if you fully understand the implications; otherwise rely on the random default.

gotcha The plugin only inlines imports that are statically analyzable and bundled by esbuild. Dynamic imports (e.g., `import()`) are not supported. ↓

fix Use only static `import` statements with the configured filter prefix.

Install

npm install esbuild-plugin-inline-import

yarn add esbuild-plugin-inline-import

pnpm add esbuild-plugin-inline-import

Imports

inlineImportPlugin

wrong

const { inlineImportPlugin } = require('esbuild-plugin-inline-import');

correct

import inlineImportPlugin from 'esbuild-plugin-inline-import';

Default export; named exports are not available. CJS require yields the plugin function directly.

default export (function)

wrong

const inlineImportPlugin = require('esbuild-plugin-inline-import').default;

correct

const inlineImportPlugin = require('esbuild-plugin-inline-import');

For CJS, the module exports the function directly. No `.default` property.

InlineImportPluginOptions

wrong

import { InlineImportPluginOptions } from 'esbuild-plugin-inline-import';

correct

import type { InlineImportPluginOptions } from 'esbuild-plugin-inline-import';

Options type is exported as a type-only export. Must be imported with `type` keyword in TypeScript.

Quickstart

Shows basic usage: import plugin, configure with optional filter and transform, and include in esbuild build.

import esbuild from 'esbuild';
import inlineImportPlugin from 'esbuild-plugin-inline-import';

await esbuild.build({
  entryPoints: ['src/app.ts'],
  bundle: true,
  outfile: 'dist/out.js',
  plugins: [
    inlineImportPlugin({
      filter: /^inline:/,
      transform: async (contents, args) => {
        // Example: prepend a license comment
        return `/* License */\n${contents}`;
      }
    })
  ]
}).catch(() => process.exit(1));