CopyWebpackPlugin

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

Getting Started

To begin, you'll need to install copy-webpack-plugin:

$ npm install copy-webpack-plugin --save-dev

Then add the plugin to your webpack config. For example:

webpack.config.js

const CopyPlugin = require('copy-webpack-plugin');

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        { from: 'source', to: 'dest' },
        { from: 'other', to: 'public' },
      ],
    }),
  ],
};

ℹ️ webpack-copy-plugin is not designed to copy files generated from the build process; rather, it is to copy files that already exist in the source tree, as part of the build process.

ℹ️ If you want webpack-dev-server to write files to the output directory during development, you can force it with the writeToDisk option or the write-file-webpack-plugin.

Options

The plugin's signature:

webpack.config.js

const CopyPlugin = require('copy-webpack-plugin');

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        { from: 'source', to: 'dest' },
        { from: 'other', to: 'public' },
      ],
      options: {
        ignore: ['*.bin'],
      },
    }),
  ],
};

Patterns

Name	Type	Default	Description
Name Type Default Description from {String}	{String}	undefined	Glob or path from where we сopy files.
Name Type Default Description to {String}	{String}	compiler.options.output	Output path.
Name Type Default Description context {String}	{String}	options.context \|\| compiler.options.context	A path that determines how to interpret the from path.
Name Type Default Description globOptions {Object}	{Object}	undefined	Options passed to the glob pattern matching library
Name Type Default Description toType {String}	{String}	undefined	Determinate what is to option - directory, file or template.
Name Type Default Description test {String\|RegExp}	{String\|RegExp}	undefined	Pattern for extracting elements to be used in to templates.
Name Type Default Description force {Boolean}	{Boolean}	false	Overwrites files already in compilation.assets (usually added by other plugins/loaders).
Name Type Default Description ignore {Array}	{Array}	[]	Globs to ignore files.
Name Type Default Description flatten {Boolean}	{Boolean}	false	Removes all directory references and only copies file names.
Name Type Default Description transform {Function}	{Function}	undefined	Allows to modify the file contents.
Name Type Default Description cacheTransform {Boolean\|Object}	{Boolean\|Object}	false	Enable transform caching. You can use { cache: { key: 'my-cache-key' } } to invalidate the cache.
Name Type Default Description transformPath {Function}	{Function}	undefined	Allows to modify the writing path.

from

Type: String Default: undefined

Glob or path from where we сopy files. Globs accept micromatch options.

⚠️ Don't use directly \\ in from (i.e path\to\file.ext) option because on UNIX the backslash is a valid character inside a path component, i.e., it's not a separator. On Windows, the forward slash and the backward slash are both separators. Instead please use / or path methods.

webpack.config.js

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        'relative/path/to/file.ext',
        '/absolute/path/to/file.ext',
        'relative/path/to/dir',
        '/absolute/path/to/dir',
        '**/*',
        {
          from: '**/*',
        },
      ],
    }),
  ],
};

For windows

If you define from as file path or folder path on Windows, you can use windows path segment (\\)

...
from: path.resolve('__dirname', 'file.txt'),
...

But you should always use forward-slashes in glob expressions See fast-glob manual.

...
const FIXTURES_DIR_NORMALIZED = path.resolve(__dirname, 'fixtures').replace(/\\/g, '/');

from: path.posix.join(FIXTURES_DIR_NORMALIZED, 'file.txt'),
...

to

Type: String Default: compiler.options.output

Output path.

⚠️ Don't use directly \\ in to (i.e path\to\dest) option because on UNIX the backslash is a valid character inside a path component, i.e., it's not a separator. On Windows, the forward slash and the backward slash are both separators. Instead please use / or path methods.

webpack.config.js

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: '**/*',
          to: 'relative/path/to/dest/',
        },
        {
          from: '**/*',
          to: '/absolute/path/to/dest/',
        },
        {
          from: '**/*',
          to: '[path][name].[contenthash].[ext]',
        },
      ],
    }),
  ],
};

context

Type: String Default: options.context|compiler.options.context

A path that determines how to interpret the from path.

⚠️ Don't use directly \\ in context (i.e path\to\context) option because on UNIX the backslash is a valid character inside a path component, i.e., it's not a separator. On Windows, the forward slash and the backward slash are both separators. Instead please use / or path methods.

webpack.config.js

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: 'src/*.txt',
          to: 'dest/',
          context: 'app/',
        },
      ],
    }),
  ],
};

globOptions

Type: Object Default: undefined

Allows to configute the glob pattern matching library used by the plugin. See the list of supported options

webpack.config.js

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: 'public/**/*',
          globOptions: {
            dot: true,
            gitignore: true,
          },
        },
      ],
    }),
  ],
};

toType

Type: String Default: undefined

Determinate what is to option - directory, file or template. Sometimes it is hard to say what is to, example path/to/dir-with.ext. If you want to copy files in directory you need use dir option. We try to automatically determine the type so you most likely do not need this option.

Name	Type	Default	Description
Name Type Default Description 'dir' {String}	{String}	undefined	If from is directory, to has no extension or ends in '/'
Name Type Default Description 'file' {String}	{String}	undefined	If to has extension or from is file
Name Type Default Description 'template' {String}	{String}	undefined	If to contains a template pattern

'dir'

webpack.config.js

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: 'path/to/file.txt',
          to: 'directory/with/extension.ext',
          toType: 'dir',
        },
      ],
    }),
  ],
};

'file'

webpack.config.js

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: 'path/to/file.txt',
          to: 'file/without/extension',
          toType: 'file',
        },
      ],
    }),
  ],
};

'template'

webpack.config.js

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: 'src/',
          to: 'dest/[name].[hash].[ext]',
          toType: 'template',
        },
      ],
    }),
  ],
};

test

Type: string|RegExp Default: undefined

Pattern for extracting elements to be used in to templates.

Defines a {RegExp} to match some parts of the file path. These capture groups can be reused in the name property using [N] placeholder. Note that [0] will be replaced by the entire path of the file, whereas [1] will contain the first capturing parenthesis of your {RegExp} and so on...

webpack.config.js

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: '*/*',
          to: '[1]-[2].[hash].[ext]',
          test: /([^/]+)\/(.+)\.png$/,
        },
      ],
    }),
  ],
};

force

Type: Boolean Default: false

Overwrites files already in compilation.assets (usually added by other plugins/loaders).

webpack.config.js

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: 'src/**/*',
          to: 'dest/',
          force: true,
        },
      ],
    }),
  ],
};

ignore

Type: Array Default: []

Globs to ignore files.

webpack.config.js

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: 'src/**/*',
          to: 'dest/',
          ignore: ['*.js'],
        },
      ],
    }),
  ],
};

⚠️ Note that only relative path should be provided to ignore option, an example to ignore src/assets/subfolder/ignorefile.js :

webpack.config.js

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: 'src/assets',
          to: 'dest/',
          ignore: ['subfolder/ignorefile.js'],
        },
      ],
    }),
  ],
};

flatten

Type: Boolean Default: false

Removes all directory references and only copies file names.

⚠️ If files have the same name, the result is non-deterministic.

webpack.config.js

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: 'src/**/*',
          to: 'dest/',
          flatten: true,
        },
      ],
    }),
  ],
};

transform

Type: Function Default: undefined

Allows to modify the file contents.

webpack.config.js

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: 'src/*.png',
          to: 'dest/',
          transform(content, path) {
            return optimize(content);
          },
        },
      ],
    }),
  ],
};

webpack.config.js

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: 'src/*.png',
          to: 'dest/',
          transform(content, path) {
            return Promise.resolve(optimize(content));
          },
        },
      ],
    }),
  ],
};

cacheTransform

Type: Boolean|Object Default: false

Enable/disable transform caching. You can use { cacheTransform: { key: 'my-cache-key' } } to invalidate the cache. Default path to cache directory: node_modules/.cache/copy-webpack-plugin.

webpack.config.js

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: 'src/*.png',
          to: 'dest/',
          transform(content, path) {
            return optimize(content);
          },
          cacheTransform: true,
        },
      ],
    }),
  ],
};

transformPath

Type: Function Default: undefined

Allows to modify the writing path.

⚠️ Don't return directly \\ in transformPath (i.e path\to\newFile) option because on UNIX the backslash is a valid character inside a path component, i.e., it's not a separator. On Windows, the forward slash and the backward slash are both separators. Instead please use / or path methods.

webpack.config.js

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: 'src/*.png',
          to: 'dest/',
          transformPath(targetPath, absolutePath) {
            return 'newPath';
          },
        },
      ],
    }),
  ],
};

webpack.config.js

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: 'src/*.png',
          to: 'dest/',
          transformPath(targetPath, absolutePath) {
            return Promise.resolve('newPath');
          },
        },
      ],
    }),
  ],
};

Options

Name	Type	Default	Description
Name Type Default Description ignore {Array}	{Array}	[]	Array of globs to ignore (applied to from )

ignore

Array of globs to ignore (applied to from).

webpack.config.js

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [...patterns],
      options: { ignore: ['*.js', '*.css'] },
    }),
  ],
};

Contributing

Please take a moment to read our contributing guidelines if you haven't yet done so.

CONTRIBUTING

License

MIT