vite-plugin-replace-files

1.1.4 verified Mon Apr 27 auth: no javascript

Vite plugin that replaces files during build with other files, useful when simple string replacement is insufficient (e.g., swapping entire configuration or environment files). Current stable version is 1.1.4, released with support for Vite 3 through 8. It ships TypeScript types. Key differentiators: operates at file level rather than string substitution, works with Vite's build pipeline, and is lightweight with no runtime dependencies. Frequent releases to keep peer dependency compatibility with Vite versions.

Common errors

error TypeError: replaceFiles is not a function ↓

cause Named import instead of default import.

fix

Use 'import replaceFiles from 'vite-plugin-replace-files'' instead of destructuring.

error Error: Cannot find module 'vite-plugin-replace-files' ↓

cause Plugin not installed or not in node_modules.

fix

Run 'npm install -D vite-plugin-replace-files'.

error [vite] Internal server error: ENOENT: no such file or directory ↓

cause Replacement file path does not exist.

fix

Check the replacement path; ensure the file exists at build time.

Warnings

breaking Plugin order matters: must be placed before other plugins that rely on the replaced files. ↓

fix Ensure replaceFiles is the first plugin in the plugins array.

gotcha Paths are resolved relative to the project root; absolute paths or path.join usage is recommended. ↓

fix Always use path.join or absolute paths, e.g., path.join(__dirname, 'src', 'env.ts').

gotcha Replacement file must exist at build time; no error if missing, just no replacement. ↓

fix Verify the replacement path exists or add a check before the build.

deprecated Vite 3 support is being dropped; check peer dependencies for your Vite version. ↓

fix Update to Vite 4+ or stay on older plugin version if using Vite 3.

Install

npm install vite-plugin-replace-files

yarn add vite-plugin-replace-files

pnpm add vite-plugin-replace-files

Imports

default
wrong
```
import { replaceFiles } from 'vite-plugin-replace-files'
```
correct
```
import replaceFiles from 'vite-plugin-replace-files'
```
Package exports a default function, not a named export. TypeScript users can do 'import replaceFiles from ...' with esModuleInterop or use 'import replaceFiles = require(...)' for CJS.

ReplaceFilesOptions

wrong

import { ReplaceFilesOptions } from 'vite-plugin-replace-files'

correct

import type { ReplaceFilesOptions } from 'vite-plugin-replace-files'

Options type is exported as a named type. Use type-only import to avoid bundling runtime code.

ReplacementRule

wrong

import { ReplacementRule } from 'vite-plugin-replace-files'

correct

import type { ReplacementRule } from 'vite-plugin-replace-files'

Also exported as a named type for configuring individual file replacements.

Quickstart

Basic setup: replace 'src/env.ts' with 'conf/env.ts' during build.

import { defineConfig } from 'vite';
import path from 'path';
import replaceFiles from 'vite-plugin-replace-files';

export default defineConfig({
  plugins: [
    replaceFiles([
      {
        file: path.join('src', 'env.ts'),
        replacement: path.join('conf', 'env.ts'),
      },
    ]),
  ],
});