Registry / devops / esbuild-plugin-define

esbuild-plugin-define

library0.6.0jsnpmunverified

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.

devops

npm install esbuild-plugin-define

github ↗package ↗

INSTALL

IMPORT

SIG · ESBUILD-PLUGIN-DEF

esbuild-plugin-define

devopsjavascriptv0.6.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–223 runs

build_error

glibc

node 18–223 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

definePlugin

✓ import { definePlugin } from 'esbuild-plugin-define'

✗ const definePlugin = require('esbuild-plugin-define').default

ESM-only since v0.5; CommonJS require is not supported. The package exports a named function, not a default export.

definePlugin

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

✗ const definePlugin = require('esbuild-plugin-define')

For CommonJS projects that still use require(), destructure the named export. Direct require returns undefined.

type Config

✓ import type { Config } from 'esbuild-plugin-define'

✗ import { Config } from 'esbuild-plugin-define'

Config is a TypeScript type only, not a runtime value. Use `import type` to avoid bundling issues.

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');

Debug

Known issues

breakingESM-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').

affects: >=0.5

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

fix

Upgrade Node.js to 20 or later.

affects: >=0.6

deprecatedDefine 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: '...' } } } }.

affects: <0.5

gotchaString 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.

affects: >=0

gotchaPlugin 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.

affects: >=0

Errors

Common errors & fixes

TypeError: definePlugin is not a function

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');

Cannot read properties of undefined (reading 'process')

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: Invalid 'define' value: Expected a string but got object

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.

ESM: Must use import to load ES Module

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');

Upgrade

Version history

0.6.0latest on npm

Audit

Dependencies

esbuildrequiredPeer dependency; this is an esbuild plugin and cannot function without esbuild installed.

Agent activity

7 hits · last 30 days

node

Bingbot

Resources

githubhttps://github.com/webdeveric/esbuild-plugin-define ↗

packagehttps://www.npmjs.com/package/esbuild-plugin-define ↗