or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-rollup-plugin-copy

Copy files and folders using Rollup with glob support and advanced transformation features

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/rollup-plugin-copy@3.5.x

To install, run

npx @tessl/cli install tessl/npm-rollup-plugin-copy@3.5.0

index.mddocs/

Rollup Plugin Copy

Rollup Plugin Copy provides comprehensive file and folder copying functionality during the build process, supporting glob patterns, multiple targets, and advanced features like file transformation and renaming. It offers flexible configuration options including synchronous/asynchronous copying, directory structure flattening, verbose output, and various Rollup hooks for different build phases.

Package Information

  • Package Name: rollup-plugin-copy
  • Package Type: npm (Rollup plugin)
  • Language: JavaScript (ES modules)
  • Installation: npm install rollup-plugin-copy -D

Core Imports

import copy from 'rollup-plugin-copy';

For CommonJS:

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

Basic Usage

// 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/fonts/arial.woff', 'assets/fonts/arial.woff2'], dest: 'dist/public/fonts' },
        { src: 'assets/images/**/*', dest: 'dist/public/images' }
      ]
    })
  ]
};

Capabilities

Copy Plugin Factory

Creates a Rollup plugin that copies files and folders based on configuration.

/**
 * Creates a Rollup plugin for copying files and folders
 * @param options - Configuration options for the copy plugin
 * @returns Rollup plugin object with name and hook handlers
 */
function copy(options?: CopyOptions): RollupPlugin;

interface RollupPlugin {
  name: string;
  [hook: string]: any;
}

interface CopyOptions {
  /**
   * Copy items once. Useful in watch mode.
   * @default false
   */
  readonly copyOnce?: boolean;

  /**
   * Copy items synchronous.
   * @default false
   */
  readonly copySync?: boolean;

  /**
   * Remove the directory structure of copied files.
   * @default true
   */
  readonly flatten?: boolean;

  /**
   * Rollup hook the plugin should use.
   * @default 'buildEnd'
   */
  readonly hook?: string;

  /**
   * Array of targets to copy.
   * @default []
   */
  readonly targets?: readonly Target[];

  /**
   * Output copied items to console.
   * @default false
   */
  readonly verbose?: boolean;

  /**
   * Global glob pattern matching options (inherited by all targets)
   */
  readonly dot?: boolean;
  readonly expandDirectories?: boolean;
  readonly ignore?: string | readonly string[];
  readonly gitignore?: boolean;
  readonly absolute?: boolean;
  readonly onlyFiles?: boolean;
  readonly onlyDirectories?: boolean;

  /**
   * File system copy options
   */
  readonly overwrite?: boolean;
  readonly errorOnExist?: boolean;
  readonly dereference?: boolean;
  readonly preserveTimestamps?: boolean;

  /**
   * File writing options (for transformed files)
   */
  readonly encoding?: string;
  readonly mode?: number;
  readonly flag?: string;
}

interface Target {
  /**
   * Path or glob of what to copy.
   */
  readonly src: string | readonly string[];

  /**
   * One or more destinations where to copy.
   */
  readonly dest: string | readonly string[];

  /**
   * Change destination file or folder name.
   */
  readonly rename?: string | ((name: string, extension: string, fullPath: string) => string);

  /**
   * Modify file contents.
   */
  readonly transform?: (contents: Buffer, name: string) => any;

  /**
   * Glob pattern matching options
   */
  readonly dot?: boolean;
  readonly expandDirectories?: boolean;
  readonly ignore?: string | readonly string[];
  readonly gitignore?: boolean;
  readonly absolute?: boolean;
  readonly onlyFiles?: boolean;
  readonly onlyDirectories?: boolean;
}

Usage Examples:

// Single file copy
copy({
  targets: [{ src: 'src/index.html', dest: 'dist/public' }]
});

// Multiple files with glob patterns
copy({
  targets: [
    { src: 'assets/*', dest: 'dist/public' },
    { src: ['src/index.html', 'src/styles.css'], dest: 'dist/public' }
  ]
});

// Multiple destinations
copy({
  targets: [{ src: 'src/index.html', dest: ['dist/public', 'build/public'] }]
});

// File renaming with string
copy({
  targets: [{ src: 'src/app.html', dest: 'dist/public', rename: 'index.html' }]
});

// File renaming with function
copy({
  targets: [{
    src: 'assets/docs/*',
    dest: 'dist/public/docs',
    rename: (name, extension, fullPath) => `${name}-v1.${extension}`
  }]
});

// File content transformation
copy({
  targets: [{
    src: 'src/index.html',
    dest: 'dist/public',
    transform: (contents, filename) => contents.toString().replace('__SCRIPT__', 'app.js')
  }]
});

// Advanced configuration
copy({
  targets: [
    { src: 'assets/images/**/*', dest: 'dist/public/images' }
  ],
  verbose: true,
  copyOnce: true,
  flatten: false,
  hook: 'writeBundle'
});

Configuration Options

targets

Array of copy target objects. Each target specifies what to copy (src) and where to copy it (dest), with optional renaming and transformation.

  • src: Can be a single path/glob string or array of paths/globs
  • dest: Can be a single destination path or array of destination paths
  • rename: Optional string or function for renaming files
  • transform: Optional function for modifying file contents (only works on files, not directories)

verbose

When true, outputs detailed information about copied files to the console, including transformation and renaming flags.

hook

Specifies which Rollup build hook to use for the copy operation. Default is 'buildEnd'. Other common options include 'writeBundle', 'generateBundle', etc.

copyOnce

When true, files are only copied once, which is useful in watch mode to prevent redundant copying on every rebuild.

copySync

When true, uses synchronous file operations instead of asynchronous ones.

flatten

When true (default), removes the directory structure of source files when copying. When false, preserves the original directory structure relative to the source root.

Global Options

Glob Pattern Options (applied to all targets unless overridden):

  • dot: Include files starting with a dot (hidden files)
  • expandDirectories: Expand directories to their contents
  • ignore: Patterns to exclude from matching
  • gitignore: Respect .gitignore files
  • absolute: Return absolute paths
  • onlyFiles: Only match files (not directories)
  • onlyDirectories: Only match directories (not files)

File System Copy Options:

  • overwrite: Replace existing files (default: true)
  • errorOnExist: Throw error if destination exists
  • dereference: Follow symbolic links
  • preserveTimestamps: Preserve file timestamps

File Writing Options (for transformed files):

  • encoding: Text encoding for file writes
  • mode: File permissions mode
  • flag: File system flag for write operations

Error Handling

The plugin validates configuration and throws errors for:

  • Invalid target objects (must be plain objects)
  • Missing required src or dest properties in targets
  • Invalid rename property type (must be string or function)
  • Using transform option on non-file sources (directories)

Glob Pattern Support

Uses globby for pattern matching, supporting:

  • Standard glob patterns (*, **, ?)
  • Negated patterns (!**/*.test.js)
  • Array of patterns with mixed inclusion/exclusion
  • Advanced globby options for fine-grained control