or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

tessl/npm-rollup-plugin-replace

Replace strings in files while bundling them with Rollup

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:npm/rollup-plugin-replace@1.2.x

To install, run

npx @tessl/cli install tessl/npm-rollup-plugin-replace@1.2.0

Rollup Plugin Replace

Rollup Plugin Replace is a Rollup plugin that performs string replacement during the bundling process. It allows developers to replace specific strings or patterns in their code at build time, making it ideal for environment variable injection, build-time configuration, and conditional compilation scenarios.

Package Information

Package Name: rollup-plugin-replace
Package Type: npm
Language: JavaScript (ES modules)
Installation: npm install --save-dev rollup-plugin-replace

Core Imports

import replace from 'rollup-plugin-replace';

For CommonJS:

const replace = require('rollup-plugin-replace');

Basic Usage

// rollup.config.js
import replace from 'rollup-plugin-replace';

export default {
  input: 'src/main.js',
  output: {
    file: 'dist/bundle.js',
    format: 'iife'
  },
  plugins: [
    replace({
      ENVIRONMENT: JSON.stringify('production'),
      VERSION: JSON.stringify('1.0.0')
    })
  ]
};

Important: The replace plugin should be placed before other plugins (like rollup-plugin-commonjs) in your plugins array to allow those plugins to apply optimizations such as dead code removal.

Architecture

The plugin operates through a simple but effective architecture:

Filter System: Uses rollup-pluginutils to create include/exclude filters for file processing
Pattern Matching: Builds optimized regex patterns from replacement keys, sorted by length for longest-first matching
Magic String Integration: Leverages magic-string library for precise source transformations with source map support
Lazy Evaluation: Converts all replacement values to functions for consistent handling and dynamic evaluation
Transform Pipeline: Processes files during Rollup's transform phase, returning null for unchanged files to optimize performance

The plugin's core algorithm escapes special characters in both delimiters and replacement keys, ensuring reliable pattern matching even with complex replacement scenarios.

Capabilities

Plugin Factory Function

Creates a Rollup plugin instance configured for string replacement.

/**
 * Creates a Rollup plugin for string replacement during bundling
 * @param options - Configuration object for replacement settings
 * @returns Rollup plugin object with name and transform methods
 */
function replace(options = {}): RollupPlugin;

interface RollupPlugin {
  /** Plugin identifier */
  name: string;
  /** Transform function that processes file contents */
  transform(code: string, id: string): TransformResult | null;
}

interface TransformResult {
  /** Transformed code */
  code: string;
  /** Source map (if sourceMap option is not false) */
  map?: object;
}

Configuration Options

The options object supports the following properties:

interface ReplaceOptions {
  /** Minimatch pattern or array of patterns for files to include */
  include?: string | string[];
  /** Minimatch pattern or array of patterns for files to exclude */
  exclude?: string | string[];
  /** Custom delimiters for replacement patterns [prefix, suffix] */
  delimiters?: [string, string];
  /** Whether to generate source maps (default: true) */
  sourceMap?: boolean;
  /** Object containing replacement key-value pairs */
  values?: { [key: string]: string | ReplacementFunction };
  /** Direct replacement properties (when values is not specified) */
  [key: string]: string | ReplacementFunction | any;
}

type ReplacementFunction = (id: string) => string;

Usage Examples:

// Basic string replacements
replace({
  ENVIRONMENT: JSON.stringify('production'),
  API_URL: JSON.stringify('https://api.example.com')
})

// File filtering
replace({
  include: 'src/**/*.js',
  exclude: 'node_modules/**',
  DEBUG: 'false'
})

// Custom delimiters
replace({
  delimiters: ['<@', '@>'],
  VERSION: '1.0.0'
  // Replaces <@VERSION@> instead of VERSION
})

// Function-based replacements
replace({
  __dirname: (id) => `'${path.dirname(id)}'`,
  __filename: (id) => `'${id}'`
})

// Using values object
replace({
  include: '**/*.js',
  sourceMap: false,
  values: {
    ENVIRONMENT: JSON.stringify('development'),
    DEBUG: 'true'
  }
})

// Special characters in replacement keys
replace({
  "require('config')": "require('./config-prod')",
  "process.env.NODE_ENV": JSON.stringify('production')
})

File Filtering

Control which files are processed using include/exclude patterns:

interface FileFilterOptions {
  /** Include files matching these minimatch patterns */
  include?: string | string[];
  /** Exclude files matching these minimatch patterns */
  exclude?: string | string[];
}

Uses minimatch patterns for file matching
If include is omitted, all files are processed by default
exclude patterns take precedence over include patterns
Patterns are relative to the project root

Replacement Delimiters

Customize the delimiters used for pattern matching:

interface DelimiterOptions {
  /** Custom delimiters as [prefix, suffix] array */
  delimiters?: [string, string];
}

Default delimiters: ['', ''] (matches exact strings)
Custom delimiters wrap replacement keys: delimiters: ['<@', '@>']
Useful for avoiding conflicts with existing code patterns
Delimiters are escaped for regex usage

Replacement Values

Define what strings should be replaced and their replacement values:

type ReplacementValue = string | ReplacementFunction;
type ReplacementFunction = (id: string) => string;

interface ReplacementConfig {
  /** Organized replacement values */
  values?: { [key: string]: ReplacementValue };
  /** Direct replacement properties (merged with options) */
  [key: string]: ReplacementValue | any;
}

Replacement Types:

Static strings: Direct string replacement

{ API_URL: JSON.stringify('https://api.prod.com') }

Function replacements: Dynamic replacement based on file ID
```
{ __dirname: (id) => `'${path.dirname(id)}'` }
```
Special characters: Keys can contain regex special characters
```
{ "require('dev-config')": "require('prod-config')" }
```

Source Map Generation

Control source map generation for replaced content:

interface SourceMapOptions {
  /** Whether to generate source maps (default: true) */
  sourceMap?: boolean;
}

Source maps are generated by default using magic-string
Set sourceMap: false to disable source map generation
Source maps preserve original line/column information for debugging

Advanced Usage Patterns

Environment-Based Configuration

replace({
  'process.env.NODE_ENV': JSON.stringify(process.env.NODE_ENV || 'development'),
  'process.env.API_URL': JSON.stringify(
    process.env.NODE_ENV === 'production' 
      ? 'https://api.prod.com' 
      : 'https://api.dev.com'
  )
})

Conditional Compilation

replace({
  '__DEV__': process.env.NODE_ENV !== 'production',
  '__PROD__': process.env.NODE_ENV === 'production'
})

Dynamic Path Replacement

replace({
  '__filename': (id) => `'${path.relative(process.cwd(), id)}'`,
  '__dirname': (id) => `'${path.relative(process.cwd(), path.dirname(id))}'`
})

Build Information Injection

replace({
  BUILD_VERSION: JSON.stringify(require('./package.json').version),
  BUILD_DATE: JSON.stringify(new Date().toISOString()),
  COMMIT_HASH: JSON.stringify(process.env.GIT_COMMIT || 'unknown')
})

Types

interface RollupPlugin {
  /** Plugin identifier, always 'replace' */
  name: string;
  /** 
   * Transform function that processes file contents
   * @param code - Source code of the file
   * @param id - File path/identifier  
   * @returns Transform result or null if no changes
   */
  transform(code: string, id: string): TransformResult | null;
}

interface TransformResult {
  /** Transformed source code */
  code: string;
  /** Source map object (if sourceMap is not false) */
  map?: object;
}

interface ReplaceOptions {
  /** File inclusion patterns */
  include?: string | string[];
  /** File exclusion patterns */
  exclude?: string | string[];
  /** Custom replacement delimiters */
  delimiters?: [string, string];
  /** Source map generation flag */
  sourceMap?: boolean;
  /** Replacement values object */
  values?: { [key: string]: string | ReplacementFunction };
  /** Direct replacement properties */
  [key: string]: any;
}

type ReplacementFunction = (id: string) => string;