Adapter Configuration

EsBuildAdapterConfig is the esbuild-specific extension point. You pass it as adapterConfig on runEsBuildBuilder (or directly into createEsBuildAdapter). Four fields — all optional except plugins — control extra esbuild plugins, entry-point rewriting, export compensation, and custom file loaders.

Shape

import type * as esbuild from 'esbuild';

export interface EsBuildAdapterConfig {
  plugins: esbuild.Plugin[];
  fileReplacements?: Record<string, string | { file: string }>;
  compensateExports?: RegExp[];
  loader?: { [ext: string]: esbuild.Loader };
}

plugins

Extra esbuild plugins applied to the source-code esbuild context — the one that bundles your exposed modules and their local source files. Use it for the usual esbuild extensions: Sass, CSS modules, SVGR, a GraphQL loader, etc.

import { sassPlugin } from 'esbuild-sass-plugin';

adapterConfig: {
  plugins: [sassPlugin()],
}

fileReplacements

Rewrites the entry-point path of a shared dependency before esbuild sees it. The key is a string that will be matched as a regex against the end of the path; the value is either a target path string, or a { file: string } object (the two forms are equivalent — strings are normalized to the object form internally).

adapterConfig: {
  plugins: [],
  fileReplacements: {
    'node_modules/react/index.js':
      'node_modules/react/cjs/react.production.min.js',
  },
}

Path separators are normalized to forward slashes before matching, so the same config works on Windows.

Typical uses:

• Swap a CJS wrapper for the pre-bundled variant it re-exports from — the canonical React example is on the React & CommonJS Interop page.
• Point a library at a browser-only build when its main field resolves to a Node-only file.
• Feed esbuild a shim when a dependency's entry point does something esbuild cannot bundle (dynamic require on a directory, etc.).

compensateExports

List of regexes matched against module paths. Matching dependencies go through the core's export compensation pass, which parses the CJS/ESM output with acorn and synthesises a small re-export shim so named imports resolve to the same identity as the default import. The default is:

compensateExports: [/react/]

You usually do not need to touch this. Extend the list only when you share another CJS library that exposes named exports through an exports.* pattern — typically something older in the React ecosystem. See React & CommonJS Interop for a deeper look at why React in particular needs it.

loader

Passed straight through to esbuild.context()'s loader option for the source-code bundle. Map file extensions to esbuild's built-in loaders ('file', 'dataurl', 'text', 'binary', 'json', 'copy', …):

adapterConfig: {
  plugins: [],
  loader: {
    '.svg': 'dataurl',
    '.png': 'file',
  },
}

What the Adapter Sets for You

A few esbuild options are fixed by the adapter and cannot be overridden through EsBuildAdapterConfig. They are:

Everything else flows from EsBuildAdapterConfig — extra plugins, replaced entry paths, custom loaders, and the export-compensation list.