esbuild-plugin-modify-entrypoints

0.2.0 verified Fri May 01 auth: no javascript

esbuild plugin (v0.2.0) that allows modifying the contents of entrypoint files before they are processed by esbuild. It provides a callback function that receives the current entrypoint contents and can return modified contents along with an optional loader. Version 0.2.0 is the latest stable release, requires esbuild >=0.15 and Node.js >=18.12.0. Key differentiator: simple, focused plugin for editing entrypoint content without needing to manipulate esbuild's internal pipeline, unlike more complex alternatives.

Common errors

error Error: The plugin 'modify-entrypoints' must return an object with a `contents` property. ↓

cause The callback returned undefined or an object without the required `contents`.

fix

Ensure your callback always returns an object with a contents string at minimum.

error TypeError: Cannot destructure property 'contents' of 'undefined' or 'null'. ↓

cause The callback parameter is undefined, usually because the plugin was not added correctly.

fix

Verify the plugin is properly imported and passed in the plugins array.

error Error: esbuild: Failed to resolve entry point: Entry point 'foo' not found. ↓

cause The entryPoints array references a file that doesn't exist.

fix

Double-check the file path in entryPoints and ensure it is correct relative to the working directory.

Warnings

gotcha The callback receives an object with only `contents` and `path`. Ensure you check for all expected properties. ↓

fix Upgrade to 0.2.0 or later which provides both `contents` and `path`.

gotcha Returning an object without a `loader` property may cause esbuild to use default loader, potentially mismatched. ↓

fix Explicitly set the `loader` field in the return value to match your content's syntax (e.g., 'ts', 'js', 'tsx').

gotcha This plugin only affects entrypoints listed in the `entryPoints` option; it does not affect imported modules. ↓

fix Use the plugin on explicit entrypoints; for other files, use other esbuild plugins like svgr or CSS modules.

deprecated The `loader` option in the return value is optional; if omitted, the original loader from the entrypoint is used. However, in some versions misbehavior may occur. ↓

fix Always set the `loader` to avoid confusion; upgrade to 0.2.0+ for safer defaults.

Install

npm install esbuild-plugin-modify-entrypoints

yarn add esbuild-plugin-modify-entrypoints

pnpm add esbuild-plugin-modify-entrypoints

Imports

modifyEntrypointsPlugin

wrong

import modifyEntrypointsPlugin from 'esbuild-plugin-modify-entrypoints'

correct

import { modifyEntrypointsPlugin } from 'esbuild-plugin-modify-entrypoints'

Named export; default export is not available.

modifyEntrypointsPlugin

wrong

const modifyEntrypointsPlugin = require('esbuild-plugin-modify-entrypoints')

correct

const { modifyEntrypointsPlugin } = require('esbuild-plugin-modify-entrypoints')

CommonJS require returns an object with the named export.

ModifyEntrypointsPluginOptions
```
import type { ModifyEntrypointsPluginOptions } from 'esbuild-plugin-modify-entrypoints'
```
TypeScript users may want to import the options type for type-safe callbacks.

Quickstart

Demonstrates using the plugin with esbuild's CommonJS API to modify entrypoint contents by prepending a log statement.

const esbuild = require('esbuild');
const { modifyEntrypointsPlugin } = require('esbuild-plugin-modify-entrypoints');
esbuild.build({
  entryPoints: ['src/app.ts'],
  bundle: true,
  outfile: 'dist/bundle.js',
  plugins: [
    modifyEntrypointsPlugin(({ contents, path }) => {
      // Prepend a console log to all entrypoint files
      return {
        contents: `console.log('Entry: ${path}');\n${contents}`,
        loader: 'ts',
      };
    }),
  ],
}).catch(() => process.exit(1));