{"id":21240,"library":"esbuild-plugin-define","title":"esbuild-plugin-define","description":"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.","status":"active","version":"0.6.0","language":"javascript","source_language":"en","source_url":"https://github.com/webdeveric/esbuild-plugin-define","tags":["javascript","esbuild","plugin","define","typescript"],"install":[{"cmd":"npm install esbuild-plugin-define","lang":"bash","label":"npm"},{"cmd":"yarn add esbuild-plugin-define","lang":"bash","label":"yarn"},{"cmd":"pnpm add esbuild-plugin-define","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency; this is an esbuild plugin and cannot function without esbuild installed.","package":"esbuild","optional":false}],"imports":[{"note":"ESM-only since v0.5; CommonJS require is not supported. The package exports a named function, not a default export.","wrong":"const definePlugin = require('esbuild-plugin-define').default","symbol":"definePlugin","correct":"import { definePlugin } from 'esbuild-plugin-define'"},{"note":"For CommonJS projects that still use require(), destructure the named export. Direct require returns undefined.","wrong":"const definePlugin = require('esbuild-plugin-define')","symbol":"definePlugin","correct":"const { definePlugin } = require('esbuild-plugin-define')"},{"note":"Config is a TypeScript type only, not a runtime value. Use `import type` to avoid bundling issues.","wrong":"import { Config } from 'esbuild-plugin-define'","symbol":"type Config","correct":"import type { Config } from 'esbuild-plugin-define'"}],"quickstart":{"code":"// esbuild.config.mjs\nimport { definePlugin } from 'esbuild-plugin-define';\nimport esbuild from 'esbuild';\n\nawait esbuild.build({\n  entryPoints: ['src/index.js'],\n  bundle: true,\n  outfile: 'dist/bundle.js',\n  plugins: [\n    definePlugin({\n      process: {\n        env: {\n          BUILD_TIME: new Date().toISOString(),\n          API_URL: 'https://api.example.com/',\n        },\n      },\n      'globalThis.APP_VERSION': '1.0.0',\n    }),\n  ],\n});\nconsole.log('Build complete');","lang":"typescript","description":"Shows how to configure the plugin with nested object definitions and a string literal, then run esbuild programmatically."},"warnings":[{"fix":"Use import { definePlugin } from 'esbuild-plugin-define' or destructure require: const { definePlugin } = require('esbuild-plugin-define').","message":"ESM-only: Package dropped CommonJS support in v0.5. Using require() will fail silently if not destructured correctly.","severity":"breaking","affected_versions":">=0.5"},{"fix":"Upgrade Node.js to 20 or later.","message":"Node.js >=20 required: Package uses modern Node.js features. Older versions will cause runtime errors.","severity":"breaking","affected_versions":">=0.6"},{"fix":"Use plain nested objects: { process: { env: { KEY: 'value' } } } instead of { process: { env: { KEY: { value: 'value', scope: '...' } } } }.","message":"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.","severity":"deprecated","affected_versions":"<0.5"},{"fix":"For complex replacements, ensure the value is a valid JS expression. Use .toString() or JSON.stringify manually if needed.","message":"String escaping: Define values must be a string representation suitable for JS replacement — objects are automatically stringified via JSON.stringify.","severity":"gotcha","affected_versions":">=0"},{"fix":"List definePlugin first in the plugins array.","message":"Plugin order matters: Place definePlugin before other plugins that may rely on defined globals to avoid runtime errors.","severity":"gotcha","affected_versions":">=0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Use const { definePlugin } = require('esbuild-plugin-define');","cause":"CommonJS require returns an object but the default export is not provided due to ESM-only nature.","error":"TypeError: definePlugin is not a function"},{"fix":"Ensure the define object keys are strings starting with a letter, not numbers or symbols.","cause":"Using define plugin with a non-object top-level definition key that is not a string literal.","error":"Cannot read properties of undefined (reading 'process')"},{"fix":"Move the define object to definePlugin() or convert it to string literals for esbuild's define.","cause":"Passing an object directly to esbuild's native 'define' option instead of using this plugin.","error":"error: Invalid 'define' value: Expected a string but got object"},{"fix":"Either rename to .cjs or use dynamic import: const { definePlugin } = await import('esbuild-plugin-define');","cause":"Using require() to load an ES module file (e.g., .mjs config).","error":"ESM: Must use import to load ES Module"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}