close
Guide
Config
Plugin
API
Blog
About
Contribute
Guide
Config
Plugin
API
Blog
About
Contribute
CC 4.0 License

The content of this section is derived from the content of the following links and is subject to the CC BY 4.0 license.

The following contents can be assumed to be the result of modifications and deletions based on the original contents if not specifically stated.

CopyRspackPlugin

Rspack only

Copies individual files or entire directories, which already exist, to the build directory.

new rspack.CopyRspackPlugin(options);

Examples

  • Copy a single file. If the file does not exist, the plugin will throw an error.
rspack.config.js
const rspack = require('@rspack/core');

module.exports = {
  entry: './src/index.js',
  plugins: [
    new rspack.CopyRspackPlugin({
      // `./src/file.txt` -> `./dist/file.txt`
      patterns: [{ from: 'src/file.txt' }],
    }),
  ],
};
  • patterns can be a string, or an array of objects.
rspack.config.js
const rspack = require('@rspack/core');

module.exports = {
  entry: './src/index.js',
  plugins: [
    new rspack.CopyRspackPlugin({
      // This is equivalent to `patterns: [{ from: 'src/file.txt' }]`
      patterns: 'src/file.txt',
    }),
  ],
};
  • Copy a directory. If there are no files in the directory, the plugin will throw an error.
rspack.config.js
const rspack = require('@rspack/core');

module.exports = {
  entry: './src/index.js',
  plugins: [
    new rspack.CopyRspackPlugin({
      // `./dir/**/*` -> `./dist`
      // For example, `./dir/foo.txt` -> `./dist/foo.txt`
      patterns: [{ from: 'dir' }],
    }),
  ],
};
  • Use glob pattern to match and copy files.
rspack.config.js
const rspack = require('@rspack/core');
const path = require('node:path');

module.exports = {
  entry: './src/index.js',
  plugins: [
    new rspack.CopyRspackPlugin({
      // `./src/*.json` -> `./dist/*.json`
      // 例如 `./src/foo.json` -> `./dist/foo.json`
      patterns: [
        {
          from: '*.json',
          context: path.join(__dirname, 'src'),
        },
      ],
    }),
  ],
};
  • Use to to specify the destination path.
rspack.config.js
const rspack = require('@rspack/core');

module.exports = {
  entry: './src/index.js',
  plugins: [
    new rspack.CopyRspackPlugin({
      // `./dir/**/*` -> `./dist/other-dir`
      // For example, `./dir/foo.txt` -> `./dist/other-dir/foo.txt`
      patterns: [{ from: 'dir', to: 'other-dir' }],
    }),
  ],
};

Options

from

  • Type: string
  • Default: undefined

The source path of the copy operation, which can be an absolute path, a relative path, or a glob pattern. It can refer to a file or a directory. If a relative path is passed, it is relative to the context option.

rspack.config.js
const path = require('node:path');

module.exports = {
  plugins: [
    new rspack.CopyRspackPlugin({
      patterns: [
        // relative path
        { from: 'relative/path/to/file.js' },
        { from: 'relative/path/to/dir' },
        // absolute path
        { from: path.resolve(__dirname, 'src', 'file.js') },
        { from: path.resolve(__dirname, 'src', 'dir') },
        // glob
        { from: 'dir/**/*' },
        // If absolute path is a `glob` we replace backslashes with forward slashes,
        // because only forward slashes can be used in the `glob`
        {
          from: path.posix.join(
            path.resolve(__dirname, 'src').replace(/\\/g, '/'),
            '*.txt',
          ),
        },
      ],
    }),
  ],
};

to

  • Type:
type To =
  | string
  | ((pathData: { context: string; absoluteFilename?: string }) => string);

The destination path of the copy operation, which can be an absolute path, a relative path, or a template string. If not specified, it is equal to Rspack's output.path.

rspack.config.js
module.exports = {
  plugins: [
    new rspack.CopyRspackPlugin({
      patterns: [
        {
          from: 'dir',
          to: 'relative/path/to/dest/',
        },
        {
          from: 'dir',
          to: '/absolute/path/to/dest/',
        },
        {
          from: 'dir',
          to: '[path][name].[contenthash][ext]',
        },
      ],
    }),
  ],
};

context

context is a path to be prepended to from and removed from the start of the result paths.

const path = require('node:path');

module.exports = {
  plugins: [
    new rspack.CopyRspackPlugin({
      // `./src/*.json` -> `./dist/*.json`
      patterns: [{ from: '*.json', context: path.join(__dirname, 'src') }],
    }),
  ],
};

context can be an absolute path or a relative path. If it is a relative path, then it will be converted to an absolute path based on Rspack's context.

context should be explicitly set only when from contains a glob. Otherwise, context is automatically set based on whether from is a file or a directory:

  • If from is a file, then context is its directory. The result path will be the filename alone.
  • If from is a directory, then context equals from. The result paths will be the paths of the directory's contents (including nested contents), relative to the directory.

toType

  • Type: 'dir' | 'file' | 'template'
  • Default: undefined

Specify the type of to, which can be a directory, a file, or a template name in Rspack. If not specified, it will be automatically inferred.

The automatic inference rules are as follows:

  • dir: If to has no extension, or ends on /.
  • file: If to is not a directory and is not a template.
  • template: If to contains a template pattern.

Examples:

  • dir:
rspack.config.js
module.exports = {
  plugins: [
    new rspack.CopyRspackPlugin({
      patterns: [
        {
          from: 'path/to/file.txt',
          to: 'directory/with/extension.ext',
          toType: 'dir',
        },
      ],
    }),
  ],
};
  • file:
rspack.config.js
module.exports = {
  plugins: [
    new rspack.CopyRspackPlugin({
      patterns: [
        {
          from: 'path/to/file.txt',
          to: 'file/without/extension',
          toType: 'file',
        },
      ],
    }),
  ],
};
  • template:
rspack.config.js
module.exports = {
  plugins: [
    new rspack.CopyRspackPlugin({
      patterns: [
        {
          from: 'src/',
          to: 'dest/[name].[contenthash][ext]',
          toType: 'template',
        },
      ],
    }),
  ],
};

noErrorOnMissing

  • Type: boolean
  • Default: false

Whether to ignore the error if there are missing files or directories.

rspack.config.js
module.exports = {
  plugins: [
    new rspack.CopyRspackPlugin({
      patterns: [
        {
          from: path.resolve(__dirname, 'missing-file.txt'),
          noErrorOnMissing: true,
        },
      ],
    }),
  ],
};

force

  • Type: boolean
  • Default: false

Whether to overwrite the asset if it already exists.

rspack.config.js
module.exports = {
  plugins: [
    new rspack.CopyRspackPlugin({
      patterns: [{ from: 'file.txt', force: true }],
    }),
  ],
};

priority

  • Type: number
  • Default: 0

Allows to specify the priority of copying files with the same destination name.

When force is set to true, if a matching file is found, the one with higher priority will overwrite the one with lower priority.

rspack.config.js
module.exports = {
  plugins: [
    new rspack.CopyRspackPlugin({
      patterns: [
        // Copied first
        {
          from: 'dir-1/file.txt',
          to: 'newfile.txt',
          priority: 5,
        },
        // Copied second and will overwrite "dir-1/file.txt"
        {
          from: 'dir-2/file.txt',
          to: 'newfile.txt',
          force: true,
          priority: 10,
        },
      ],
    }),
  ],
};

globOptions

  • Type:
type GlobOptions = {
  // Whether the match is case sensitive
  // Default to true
  caseSensitiveMatch?: boolean;
  // Whether to match files starting with `.`
  // Default to true
  dot?: boolean;
  // Ignore specific paths
  // An array of strings in glob format, which can be used to ignore specific paths
  ignore?: string[];
};
  • Default: undefined

Glob options.

rspack.config.js
module.exports = {
  plugins: [
    new rspack.CopyRspackPlugin({
      patterns: [
        {
          from: 'public/**/*',
          globOptions: {
            dot: false,
            caseSensitiveMatch: false,
            ignore: ['**/file.*', '**/ignored-directory/**'],
          },
        },
      ],
    }),
  ],
};

transform

  • Type:
type Transform = (
  input: Buffer,
  absoluteFilename: string,
) => string | Buffer | Promise<string> | Promise<Buffer>;
  • Default: undefined

Allows to modify the file contents.

rspack.config.js
module.exports = {
  plugins: [
    new rspack.CopyRspackPlugin({
      patterns: [
        {
          from: 'src/*.png',
          // The `content` argument is a [`Buffer`](https://nodejs.org/api/buffer.html) object,
          // it could be converted to a string to be processed using `content.toString()`.
          // The `absoluteFrom` argument is a string, it is absolute path from where the file is being copied.
          transform(content, absoluteFrom) {
            return optimize(content);
          },
        },
      ],
    }),
  ],
};