@espcom/esbuild-plugin-replace

A plugin for esbuild that allows for customizable string replacement in files during the build process. One of the challenges with esbuild is that multiple plugins modifying file contents can not work with each other, as esbuild doesn't natively support piping content between plugins. This plugin solves that problem by facilitating the combination of multiple transformations, offering predefined and custom modifiers that can be used to manipulate file contents based on regular expressions.

Features

• Customizable Replacements: Easily define patterns and replacement logic using regular expressions.
• Predefined Modifiers: Pre-included modifiers for common use cases.
• TypeScript Support: Fully typed to ensure smooth integration with TypeScript projects.
• Pipeline Compatibility: Enables multiple file transformations to work together without conflict.

Table of Contents

• Features
• Installation
• Usage
  • Example
  • Plugin Options
  • Example Modifier
• Predefined Modifiers
  • modifierDirname
  • modifierFilename
  • modifierMobxObserverFC
  • modifierLodash

Installation

Install the plugin using npm:

npm install @espcom/esbuild-plugin-replace

Usage

To use the plugin, simply add it to your esbuild configuration and pass an array of replacement options. Each option consists of a filter, replace pattern, and a replacer function.

Example

import { pluginReplace } from '@espcom/esbuild-plugin-replace';
import esbuild, { OnLoadArgs } from 'esbuild';

esbuild.build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  outfile: 'dist/bundle.js',
  plugins: [
    pluginReplace([
      {
        filter: /\.js$/,    // Only apply to specific files
        replace: 'someString' || /some-regexp/g,
        includeNodeModules: true, // default is false
        replacer: (onLoadArgs: OnLoadArgs, fileContent: string) => {
          return 'otherString' || async (match, group) => ''
        },
      }
    ]),
  ],
});

Plugin Options

The plugin accepts an array of options, where each option contains:

• filter (RegExp): A regular expression to match file paths that should be processed.
• replace (string | RegExp): A string or regular expression to search for within the matched files.
• replacer (function): A function that takes onLoadArgs and fileContent and returns the replacement string or a function for advanced replacements (this function can be asynchronous).
• includeNodeModules (boolean): Set to true if this modifier should be applied to the files in node_modules folder

Example Modifier

Here's an example of a custom modifier to replace __dirname in files:

{
  filter: /src\/.*\.js$/,    // Match all .js files in the src directory
  replace: /__dirname/g,      // Replace all occurrences of __dirname
  replacer: (onLoadArgs) => `"${path.relative(process.cwd(), path.dirname(onLoadArgs.path))}"`,
}

Predefined Modifiers

modifierDirname

Replaces all instances of __dirname with the relative path to the file’s directory.

import { modifierDirname } from '@espcom/esbuild-plugin-replace';

pluginReplace([modifierDirname({ filter: /\.ts$/ })]);

Example input:

// src/components/test.ts
export const test = __dirname;

Example output:

export const test = "src/components";

modifierFilename

Replaces all instances of __filename with the relative path to the current file.

import { modifierFilename } from '@espcom/esbuild-plugin-replace';

pluginReplace([modifierFilename({ filter: /\.ts$/ })]);

Example input:

// src/components/test.ts
export const test = __filename;

Example output:

export const test = "src/components/test.ts";

modifierMobxObserverFC

Automatically wraps React function components with observer from mobx-react-lite. You have to install mobx-react-lite before usage.

import { modifierMobxObserverFC } from '@espcom/esbuild-plugin-replace';

pluginReplace([modifierMobxObserverFC({ filter: /\.tsx$/ })]);

Example input:

function ComponentProps(props: Record<string, string>) {
  return null;
}

export function ComponentExport() {
  return null;
}
export default function ComponentDefault() {
  return null;
}

function ComponentTypes<TTest extends Record<string, string>>(props: Record<string, TTest>) {
  return null;
}

Example output:

import { observer } from "mobx-react-lite";

const ComponentProps = observer(function ComponentProps() {
  return null;
});
export const ComponentExport = observer(function ComponentExport() {
  return null;
});
export default observer(function ComponentDefault() {
  return null;
});
const ComponentTypes = observer(function ComponentTypes(props) {
  return null;
});

modifierLodash

Optimizes lodash imports by replacing grouped imports with individual imports for each function. Be aware that this modifier does not replace default imports like import _ from 'lodash' yet.

import { modifierLodash } from '@espcom/esbuild-plugin-replace';

pluginReplace([modifierLodash({ filter: /src\/.*\.js$/ })]);

Example input:

import { chunk, last } from 'lodash';
import { get as _get } from 'lodash';
import noop from 'lodash/noop';
import _ from 'lodash';

Example output:

import chunk from "lodash/chunk";
import last from "lodash/last";
import _get from "lodash/get";
import noop from "lodash/noop";
import _ from "lodash";