esbuild-plugin-define

0.6.0 verified Mon Apr 27 auth: no javascript

esbuild plugin that defines global identifiers at build time, similar to esbuild's built-in `define` feature but with a more structured and discoverable API. Version 0.6.0 is the latest stable release as of early 2025, with active development and monthly updates. Unlike manual `define` objects, this plugin supports nested object definitions (e.g., `process.env.API_KEY`) and merges with esbuild's native `define`. It ships TypeScript types and is designed for modern Node.js (>=20) with native ESM support. Key differentiator: avoids tedious string escaping for complex replacement values and provides a cleaner configuration pattern.

Common errors

error TypeError: definePlugin is not a function ↓

cause CommonJS require returns an object but the default export is not provided due to ESM-only nature.

fix

Use const { definePlugin } = require('esbuild-plugin-define');

error Cannot read properties of undefined (reading 'process') ↓

cause Using define plugin with a non-object top-level definition key that is not a string literal.

fix

Ensure the define object keys are strings starting with a letter, not numbers or symbols.

error error: Invalid 'define' value: Expected a string but got object ↓

cause Passing an object directly to esbuild's native 'define' option instead of using this plugin.

fix

Move the define object to definePlugin() or convert it to string literals for esbuild's define.

error ESM: Must use import to load ES Module ↓

cause Using require() to load an ES module file (e.g., .mjs config).

fix

Either rename to .cjs or use dynamic import: const { definePlugin } = await import('esbuild-plugin-define');

Warnings

breaking ESM-only: Package dropped CommonJS support in v0.5. Using require() will fail silently if not destructured correctly. ↓

fix Use import { definePlugin } from 'esbuild-plugin-define' or destructure require: const { definePlugin } = require('esbuild-plugin-define').

breaking Node.js >=20 required: Package uses modern Node.js features. Older versions will cause runtime errors. ↓

fix Upgrade Node.js to 20 or later.

deprecated Define values with scope property: In v0.4 and earlier, definitions could use a 'scope' sub-object for nested keys; this is replaced by direct nested objects. ↓

fix Use plain nested objects: { process: { env: { KEY: 'value' } } } instead of { process: { env: { KEY: { value: 'value', scope: '...' } } } }.

gotcha String escaping: Define values must be a string representation suitable for JS replacement — objects are automatically stringified via JSON.stringify. ↓

fix For complex replacements, ensure the value is a valid JS expression. Use .toString() or JSON.stringify manually if needed.

gotcha Plugin order matters: Place definePlugin before other plugins that may rely on defined globals to avoid runtime errors. ↓

fix List definePlugin first in the plugins array.

Install

npm install esbuild-plugin-define

yarn add esbuild-plugin-define

pnpm add esbuild-plugin-define

Imports

definePlugin
wrong
```
const definePlugin = require('esbuild-plugin-define').default
```
correct
```
import { definePlugin } from 'esbuild-plugin-define'
```
ESM-only since v0.5; CommonJS require is not supported. The package exports a named function, not a default export.
definePlugin
wrong
```
const definePlugin = require('esbuild-plugin-define')
```
correct
```
const { definePlugin } = require('esbuild-plugin-define')
```
For CommonJS projects that still use require(), destructure the named export. Direct require returns undefined.
type Config
wrong
```
import { Config } from 'esbuild-plugin-define'
```
correct
```
import type { Config } from 'esbuild-plugin-define'
```
Config is a TypeScript type only, not a runtime value. Use `import type` to avoid bundling issues.

Quickstart

Shows how to configure the plugin with nested object definitions and a string literal, then run esbuild programmatically.

// esbuild.config.mjs
import { definePlugin } from 'esbuild-plugin-define';
import esbuild from 'esbuild';

await esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/bundle.js',
  plugins: [
    definePlugin({
      process: {
        env: {
          BUILD_TIME: new Date().toISOString(),
          API_URL: 'https://api.example.com/',
        },
      },
      'globalThis.APP_VERSION': '1.0.0',
    }),
  ],
});
console.log('Build complete');