vite-plugin-transform

2.0.1 verified Mon Apr 27 auth: no javascript

Vite plugin for transforming resources during build, supporting regex replacement, alias resolution, and custom callback functions. Current stable version is 2.0.1, released occasionally with breaking changes from v1.x. Key differentiators: allows both simple key-value replacement and advanced path resolution using custom delimiters (e.g., %{ }%). Alternatives: @rollup/plugin-replace, vite-plugin-html. Note: v2.x changed default delimiters from #{ }% to %{ }% and alias handling.

Common errors

error Error: Cannot find module 'vite-plugin-transform' ↓

cause Package not installed or installed as devDependency but not found.

fix

Run 'npm install --save-dev vite-plugin-transform' and ensure you are in the correct directory.

error TypeError: transformPlugin is not a function ↓

cause Importing named export instead of default export.

fix

Use 'import transformPlugin from 'vite-plugin-transform'' (no curly braces).

error The 'tStart' option requires a string value ↓

cause Using array or object instead of string for tStart/tEnd.

fix

Set tStart to a string like '%{' (not an array).

Warnings

breaking Default delimiters changed from #{ }% to %{ }% in v2.0.0. Old syntax #{key}% will not work without explicit configuration. ↓

fix Set tStart: '#{' and tEnd: '}%' in options to restore v1 behavior, or update your template syntax to use %{key}%.

gotcha Alias resolution only works in non-node_modules files by default; files in node_modules are excluded unless explicitly included. ↓

fix Add 'node_modules' to the 'exclude' array (it is already excluded) or set 'exclude: []' to process node_modules.

deprecated The 'resolve' option in v1.x was deprecated; use 'alias' instead since v2.0.0. ↓

fix Replace 'resolve' with 'alias' in plugin options.

gotcha Transformer functions in 'callbackArray' receive the entire file content (string) and must return the modified content. Not per-line. ↓

fix Ensure callbacks return the full transformed content, not just a line.

gotcha The 'replace' option performs simple string replacement, not regex. For regex, use 'callbackArray'. ↓

fix Use a function in callbackArray for regex replacement: str => str.replace(/pattern/g, 'replacement').

Install

npm install vite-plugin-transform

yarn add vite-plugin-transform

pnpm add vite-plugin-transform

Imports

default
wrong
```
const transformPlugin = require('vite-plugin-transform')
```
correct
```
import transformPlugin from 'vite-plugin-transform'
```
ESM-only; CommonJS require() will fail in Vite config (ESM context). Default export is the plugin function.

transformPlugin

wrong

import { transformPlugin } from 'vite-plugin-transform'

correct

import transformPlugin from 'vite-plugin-transform'

No named export; always use default import.

PluginOptions
```
import type { PluginOptions } from 'vite-plugin-transform'
```
TypeScript users: import type for options. Not exported as a value.

Quickstart

Basic setup of vite-plugin-transform with custom delimiters (%{ }%), alias resolution, key-value replacement, and custom callback.

// vite.config.js
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import transformPlugin from 'vite-plugin-transform';

export default defineConfig({
  plugins: [
    vue(),
    transformPlugin({
      tStart: '%{',
      tEnd: '}%',
      alias: {
        '@': '/src',
      },
      replace: {
        'REPLACE_ME': 'Hello Friends!',
      },
      exclude: ['node_modules'],
      callbackArray: [
        str => str.replace(/old/gi, 'new'),
      ],
    }),
  ],
  resolve: {
    alias: {
      '@': '/src',
    },
  },
});