esbuild-plugin-inline-image

0.0.9 verified Mon Apr 27 auth: no javascript

esbuild plugin that conditionally inlines images as data URLs when under a size threshold, switching loader between 'file' and 'dataurl' like Webpack's url-loader. Version 0.0.9 is the latest stable release. It supports configurable size limits via options or environment variable, custom file extensions, namespace isolation, and multiple plugin instances for per-extension rules. Smaller and simpler than full custom build setups, but has limited community adoption and ongoing maintenance uncertainty. Works only with esbuild's onLoad hook.

Common errors

error Error: Cannot find module 'esbuild-plugin-inline-image' ↓

cause Package not installed or wrong package name.

fix

Run 'npm install esbuild-plugin-inline-image' in your project root.

error TypeError: inlineImage is not a function ↓

cause CommonJS require used with named import (e.g., const { inlineImage } = require(...)).

fix

Use 'const inlineImage = require("esbuild-plugin-inline-image");' (default import).

error Error: Build failed with 1 error: error: No loader is configured for ".svg" files ↓

cause Plugin not applied or extensions not registered due to namespace or filter mismatch.

fix

Ensure plugin is included in plugins array and extensions list matches the image files. If using a custom filter, also set loader manually in esbuild build config.

Warnings

gotcha Plugin does not export an ES module; require() or default import only. ↓

fix Use CommonJS require or ESM default import. Avoid named import.

gotcha When using a function for 'limit', you must manually set esbuild loader for extensions to 'file' if filter is provided. Otherwise plugin may not handle images as expected. ↓

fix Either omit filter and let plugin auto-register loaders, or set loader manually in esbuild config.

gotcha Setting limit to 0 disables inlining but still registers loaders for extensions. This may silently change behavior. ↓

fix If you want to disable completely, remove the plugin rather than setting limit to 0.

deprecated Environment variable IMAGE_INLINE_SIZE_LIMIT may be removed or changed in future versions. ↓

fix Prefer passing limit in plugin options explicitly.

Install

npm install esbuild-plugin-inline-image

yarn add esbuild-plugin-inline-image

pnpm add esbuild-plugin-inline-image

Imports

inlineImage
```
const inlineImage = require('esbuild-plugin-inline-image');
```
Default require is the documented pattern. Package does not provide ESM exports.

inlineImage

wrong

import { inlineImage } from 'esbuild-plugin-inline-image';

correct

import inlineImage from 'esbuild-plugin-inline-image';

Named import is incorrect because the module has a default export.

inlineImage

wrong

import { default as inlineImage } from 'esbuild-plugin-inline-image';

correct

const inlineImage = require('esbuild-plugin-inline-image');

Named import with default is unnecessary and may confuse bundlers.

Quickstart

Shows how to require and use the plugin with esbuild, inlining images under 10KB.

const esbuild = require('esbuild');
const inlineImage = require('esbuild-plugin-inline-image');

esbuild.build({
  entryPoints: ['src/app.js'],
  outfile: 'dist/bundle.js',
  bundle: true,
  plugins: [
    inlineImage({
      limit: 10000,
      extensions: ['jpg', 'png', 'svg']
    })
  ]
}).catch(() => process.exit(1));