@pizca/esbuild-inline-or-path

An esbuild plugin that exports static assets either as inline data URLs or as relative paths based on custom mappings.

Installation

npm i -D @pizca/esbuild-inline-or-path

Usage

Import the plugin and add it to your esbuild build configuration:

import esbuild from 'esbuild';
import inlineOrPathPlugin from '@pizca/esbuild-inline-or-path';

esbuild.build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  outdir: 'dist',
  plugins: [
    inlineOrPathPlugin({
      inline: false, // true to inline as data URL, false to export relative paths
      filter: /\.(png|webp)$/, // files to process
      paths: { 'public/images': '/images' } // required if inline is false
    }),
  ],
}).catch(() => process.exit(1));

Example in a TypeScript file:

import myImage from '../public/images/my_image.webp';

const image = new Image();
image.src = myImage;

To avoid TypeScript type errors, create a res.d.ts or another file with a .d.ts extension file with the following declarations in your rootdir src:

declare module '*.webp' {
  const content: string;
  export default content;
}

declare module '*.png' {
  const content: string;
  export default content;
}

What it does

• When inline is true, this plugin reads the matched files and exports them as data URLs, embedding the content directly in your bundle.
• When inline is false, it exports the file paths relative to custom base paths defined in the paths option, allowing you to control how asset URLs are generated.
• Throws an error if a file is outside of the configured paths when inline is false.

This lets you easily switch between embedding assets inline or referencing them by relative paths, depending on your build needs.