esbuild-plugin-text-replace

1.3.0 verified Fri May 01 auth: no javascript maintenance

An esbuild plugin for replacing text or regex patterns in files before bundling. Current stable version is 1.3.0. It supports file filtering via regex, namespace targeting, and the standard String.prototype.replaceAll pattern syntax (including replacer functions). Key differentiators: lightweight (no heavy dependencies), supports esbuild pipe mode for integration with other plugins, and requires Node >=10.1.0. Use it for build-time substitutions like version strings, transforming imports, or injecting constants. Not actively maintained (last release 2021).

Common errors

error Error: The plugin esbuild-plugin-text-replace requires Node >=10.1.0 ↓

cause Node version below 10.1.0 does not support fs.promises.

fix

Upgrade Node to >=10.1.0 or use a polyfill for fs.promises.

error TypeError: textReplace is not a function ↓

cause Using CommonJS require() in an ESM-only package, or incorrect import.

fix

Use ESM import: import textReplace from 'esbuild-plugin-text-replace'

error Build failed: Replace callback must return a string ↓

cause Replacer function returned a non-string value (e.g., undefined).

fix

Ensure the replacer function always returns a string.

error Error: Pattern array must contain tuples of [pattern, replacement] ↓

cause Passing pattern as an object or array of non-tuples.

fix

Provide pattern as an array of tuples: [[/regex/g, 'replacement'], ['text', 'replacement']]

Warnings

gotcha include regex default is /.*/ which matches all files, causing significant build slowdown. Always specify a narrow include filter. ↓

fix Set include to a specific regex, e.g., include: /\.js$/.

gotcha Patterns without the global flag (/g) will only replace the first occurrence. This is a common mistake since the plugin uses String.replaceAll semantics internally. ↓

fix Always use /g flag in regex patterns, e.g., /foo/g.

gotcha The plugin requires Node >=10.1.0 due to use of fs.promises. Older Node versions will throw errors. ↓

fix Upgrade Node to >=10.1.0 or use a polyfill.

gotcha When used in pipe mode, the namespace option must be set to empty string '', otherwise the plugin may not work as expected. ↓

fix Set namespace: '' in the pipe plugin configuration.

deprecated The package is no longer actively maintained; last release was in 2021. Issues may remain unresolved. ↓

fix Consider alternatives like @chialab/esbuild-plugin-replace or esbuild-plugin-replace for active support.

Install

npm install esbuild-plugin-text-replace

yarn add esbuild-plugin-text-replace

pnpm add esbuild-plugin-text-replace

Imports

default

wrong

const textReplace = require('esbuild-plugin-text-replace')

correct

import textReplace from 'esbuild-plugin-text-replace'

ESM-only; requires ESM context. Default export is a function.

Quickstart

Shows basic usage: replacing __VERSION__ with a string and changing const to let in all .js files.

import esbuild from 'esbuild';
import textReplace from 'esbuild-plugin-text-replace';

await esbuild.build({
  entryPoints: ['./src/index.js'],
  outfile: 'dist/bundle.js',
  bundle: true,
  plugins: [
    textReplace({
      include: /\.js$/,
      pattern: [
        ['__VERSION__', '"1.0.0"'],
        [/(\s*)const\s+/g, '$1let ']
      ]
    })
  ]
});