rollup-plugin-copy

3.5.0 verified Mon Apr 27 auth: no javascript

Rollup plugin to copy files and folders during the build process, with glob support. Current stable version is 3.5.0. The plugin runs on the buildEnd hook by default, supports rename and transform of file contents, and can copy once in watch mode. It is actively maintained with regular releases. Key differentiators include synchronous copy option, flatten option to preserve directory structure, and TypeScript type definitions.

Common errors

error Error: The 'targets' option must be an array of objects with 'src' and 'dest' properties ↓

cause Using old string-based targets or missing dest property.

fix

Ensure targets is an array of objects: [{ src: 'path', dest: 'path' }].

error TypeError: copy is not a function ↓

cause Attempting to use default import with CommonJS require() in ESM context or vice versa.

fix

Use import copy from 'rollup-plugin-copy' (ESM) or const { default: copy } = require('rollup-plugin-copy') (CommonJS).

error Error: Cannot find module 'rollup-plugin-copy' ↓

cause Package not installed or installed as dev dependency but not resolved.

fix

Run npm install rollup-plugin-copy --save-dev or yarn add rollup-plugin-copy --dev.

Warnings

breaking v3.0.0: The targets option is now an array of objects with src/dest properties. The old outputFolder option and string-based targets are removed. ↓

fix Upgrade target format: use targets: [{ src: 'file', dest: 'folder' }] instead of targets: ['file'] + outputFolder.

breaking v2.0.0: The outputFolder option became required when targets is an array. The hook changed from generateBundle to buildEnd. ↓

fix If using an array of targets, provide an outputFolder option. If using generateBundle, set hook: 'generateBundle' explicitly.

deprecated CommonJS require() is deprecated; package is ESM-only from v3. Use import instead. ↓

fix Replace const copy = require('rollup-plugin-copy') with import copy from 'rollup-plugin-copy'.

gotcha By default, flatten is true, which removes directory structure. Files are copied flat into dest. ↓

fix Set flatten: false in options to preserve folder structure.

gotcha The copyOnce option only works in watch mode; if not in watch mode, files are always copied. ↓

fix Use copyOnce only when rolling with --watch to avoid duplicate copies.

Install

npm install rollup-plugin-copy

yarn add rollup-plugin-copy

pnpm add rollup-plugin-copy

Imports

copy
wrong
```
const copy = require('rollup-plugin-copy')
```
correct
```
import copy from 'rollup-plugin-copy'
```
Default export; the function returns a plugin object. CommonJS require works but this package is ESM-first.
CopyOptions
```
import type { CopyOptions } from 'rollup-plugin-copy'
```
TypeScript type for plugin options. Only available in TypeScript projects.
Target
wrong
```
import { Target } from 'rollup-plugin-copy'
```
correct
```
import type { Target } from 'rollup-plugin-copy'
```
TypeScript type for target objects. Using a value import will fail as it's only a type.

Quickstart

Minimal rollup config to copy an HTML file and images using glob patterns with verbosity.

// rollup.config.js
import copy from 'rollup-plugin-copy'

export default {
  input: 'src/index.js',
  output: {
    file: 'dist/app.js',
    format: 'cjs'
  },
  plugins: [
    copy({
      targets: [
        { src: 'src/index.html', dest: 'dist/public' },
        { src: 'assets/images/**/*', dest: 'dist/public/images' }
      ],
      verbose: true
    })
  ]
}