vite-plugin-cp

6.0.3 verified Mon Apr 27 auth: no javascript

Vite plugin for copying files/directories during builds with advanced transformation and renaming. Supports glob patterns, flattening, rename functions, and transform buffers. Integrates with Vite's build pipeline. v6.0.3 requires Vite >=3.1.0 and Node >=14.18.0. Ships TypeScript types. Alternative to rollup-plugin-copy with Vite-native hooks and simpler API.

Common errors

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

cause Package not installed or missing from devDependencies.

fix

Run 'npm install vite-plugin-cp --save-dev'.

error TypeError: cp is not a function ↓

cause Using named import 'cp' instead of default import.

fix

Change to 'import cp from 'vite-plugin-cp''

error Error: "src" must be provided for each target ↓

cause Missing 'src' property in a targets entry.

fix

Ensure each target object has both 'src' and 'dest' properties.

error Error: [vite-plugin-cp] ENOENT: no such file or directory, lstat '...' ↓

cause The source file or directory does not exist.

fix

Verify that the source path is correct and exists relative to project root.

error Error: [vite-plugin-cp] Transform must return a Buffer or string ↓

cause Transform function returned undefined or null.

fix

Ensure transform returns a Buffer or string, e.g., return Buffer.from('...').

Warnings

breaking v6.0.0 dropped support for the 'copyDir' and 'copyFile' options; use 'targets' array instead. ↓

fix Migrate to targets array with src/dest pairs.

breaking v5.0.0 changed the export from named to default. Code using 'import { cp } from 'vite-plugin-cp'' will break. ↓

fix Use default import: import cp from 'vite-plugin-cp'.

deprecated The 'watch' option is deprecated and will be removed in v7. Use Vite's built-in watch mode. ↓

fix Remove the 'watch' option from plugin config.

gotcha Transform function must return a Buffer or string; returning null or undefined will cause silent failure. ↓

fix Ensure transform function always returns a Buffer or string.

gotcha Glob patterns are relative to project root, not the src file location. Use absolute paths or './' for clarity. ↓

fix Prefix globs with './' and ensure they match from project root.

gotcha When using 'flatten: true', if multiple source files have the same name, only the last one copied wins (overwrites). ↓

fix Use 'rename' to avoid conflicts or avoid flattening.

Install

npm install vite-plugin-cp

yarn add vite-plugin-cp

pnpm add vite-plugin-cp

Imports

default
wrong
```
import { cp } from 'vite-plugin-cp'
```
correct
```
import cp from 'vite-plugin-cp'
```
The plugin is exported as default. Named export 'cp' does not exist.

PluginOptions

wrong

import { PluginOptions } from 'vite-plugin-cp'

correct

import type { PluginOptions } from 'vite-plugin-cp'

Type import only. PluginOptions is a TypeScript interface.

require
wrong
```
const { cp } = require('vite-plugin-cp')
```
correct
```
const cp = require('vite-plugin-cp')
```
CommonJS require returns the default export, not an object with cp property.

Quickstart

Configures vite-plugin-cp with three copy targets: a glob flatten copy, a single file rename, and a JSON transform that adds a build date.

import { defineConfig } from 'vite';
import cp from 'vite-plugin-cp';

export default defineConfig({
  plugins: [
    cp({
      targets: [
        { src: './node_modules/vite/dist/**/*', dest: 'dist/cp', flatten: true },
        { src: './README.md', dest: 'dist/', rename: 'README_COPY.md' },
        {
          src: './manifest.json',
          dest: 'dist/',
          transform(buf) {
            const manifest = JSON.parse(buf.toString());
            manifest.buildDate = new Date().toISOString();
            return JSON.stringify(manifest, null, 2);
          }
        }
      ]
    })
  ]
});