{"id":25403,"library":"esbuild-plugin-replace","title":"esbuild-plugin-replace","description":"An esbuild plugin for replacing strings in files during bundling, inspired by @rollup/plugin-replace. Current stable version is 1.4.0. Release cadence appears sporadic with occasional bug fixes and feature additions. Key differentiators: provides include/exclude file filtering, configurable delimiters, and supports both flat replacement objects and a `values` option to separate replacements from plugin options. Delimiters default to word boundaries. Requires Node.js and esbuild. Ships TypeScript declarations.","status":"active","version":"1.4.0","language":"javascript","source_language":"en","source_url":"https://github.com/naecoo/esbuild-plugin-replace","tags":["javascript","esbuild","plugin","replace","npm","module","typescript"],"install":[{"cmd":"npm install esbuild-plugin-replace","lang":"bash","label":"npm"},{"cmd":"yarn add esbuild-plugin-replace","lang":"bash","label":"yarn"},{"cmd":"pnpm add esbuild-plugin-replace","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"peer dependency - plugin is designed for esbuild's build system","package":"esbuild","optional":true}],"imports":[{"note":"Named export, not default. CommonJS: const { replace } = require('esbuild-plugin-replace')","wrong":"import replace from 'esbuild-plugin-replace'","symbol":"replace","correct":"import { replace } from 'esbuild-plugin-replace'"}],"quickstart":{"code":"const esbuild = require('esbuild');\nconst { replace } = require('esbuild-plugin-replace');\n\nesbuild.build({\n  entryPoints: ['src/index.js'],\n  bundle: true,\n  outfile: 'dist/bundle.js',\n  plugins: [\n    replace({\n      '__version__': JSON.stringify('1.0.0'),\n      '__author__': JSON.stringify('author'),\n    }),\n  ],\n}).then(() => console.log('Build succeeded')).catch(() => process.exit(1));","lang":"javascript","description":"Demonstrates basic usage of esbuild-plugin-replace to replace __version__ and __author__ with JSON-stringified values during a bundle build."},"warnings":[{"fix":"Use JSON.stringify for objects/arrays: replace({ '__key__': JSON.stringify({foo: 'bar'}) })","message":"Values must be primitives or functions returning a string. Complex values must be JSON.stringify'd.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"If using `values` with existing flat replace keys, ensure keys are not duplicated between the top-level and values object.","message":"v1.0.8 introduced a change that may break builds using the `values` option incorrectly.","severity":"breaking","affected_versions":">=1.0.8 <1.1.0"},{"fix":"Use the `values` option: replace({ values: { ... } })","message":"Specifying replacements as top-level keys alongside plugin options is discouraged in favor of the `values` option.","severity":"deprecated","affected_versions":">=1.2.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"replace({ '__config__': JSON.stringify({ key: 'value' }) })","cause":"Passing an object directly instead of using JSON.stringify","error":"Error: The replace plugin expects replacement values to be strings or functions, got object"},{"fix":"Ensure replacement values are either strings or functions that return strings, e.g., JSON.stringify(123)","cause":"Passing a non-string value as replacement (e.g., number) without converting to string","error":"TypeError: Cannot read properties of undefined (reading 'replace')"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}