copy-webpack-plugin

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([
      { 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

module.exports = {
  plugins: [new CopyPlugin(patterns, options)],
};

Patterns

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

`from`

Type: String|Object Default: undefined

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

You can define from as Object and use the node-glob 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([
      'relative/path/to/file.ext',
      '/absolute/path/to/file.ext',
      'relative/path/to/dir',
      '/absolute/path/to/dir',
      '**/*',
      {
        from: '**/*',
        globOptions: {
          dot: false,
        },
      },
    ]),
  ],
};

`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([
      {
        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([
      {
        from: 'src/*.txt',
        to: 'dest/',
        context: 'app/',
      },
    ]),
  ],
};

`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
`'dir'`	`{String}`	`undefined`	If `from` is directory, `to` has no extension or ends in `'/'`
`'file'`	`{String}`	`undefined`	If `to` has extension or `from` is file
`'template'`	`{String}`	`undefined`	If `to` contains a template pattern

`'dir'`

webpack.config.js

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

`'file'`

webpack.config.js

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

`'template'`

webpack.config.js

module.exports = {
  plugins: [
    new CopyPlugin([
      {
        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([
      {
        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([
      {
        from: 'src/**/*',
        to: 'dest/',
        force: true,
      },
    ]),
  ],
};

`ignore`

Type: Array Default: []

Globs to ignore files.

webpack.config.js

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

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

webpack.config.js

module.exports = {
  plugins: [
    new CopyPlugin([
      {
        from: 'src/assets',
        to: 'dest/',
        ignore: ['subfolder/ingorefile.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([
      {
        from: 'src/**/*',
        to: 'dest/',
        flatten: true,
      },
    ]),
  ],
};

`cache`

Type: Boolean|Object Default: false

Enable/disable transform caching. You can use { cache: { 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([
      {
        from: 'src/*.png',
        to: 'dest/',
        transform(content, path) {
          return optimize(content);
        },
        cache: true,
      },
    ]),
  ],
};

`transform`

Type: Function Default: undefined

Allows to modify the file contents.

webpack.config.js

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

webpack.config.js

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

`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([
      {
        from: 'src/*.png',
        to: 'dest/',
        transformPath(targetPath, absolutePath) {
          return 'newPath';
        },
      },
    ]),
  ],
};

webpack.config.js

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

Options

Name	Type	Default	Description
`logLevel`	`{String}`	`'warn'`	Level of messages that the module will log
`ignore`	`{Array}`	`[]`	Array of globs to ignore (applied to `from`)
`context`	`{String}`	`compiler.options.context`	A path that determines how to interpret the `from` path, shared for all patterns
`copyUnmodified`	`{Boolean}`	`false`	Copies files, regardless of modification when using watch or `webpack-dev-server`. All files are copied on first build, regardless of this option

`logLevel`

This property defines the level of messages that the module will log. Valid levels include:

trace
debug
info
warn (default)
error
silent

Setting a log level means that all other levels below it will be visible in the console. Setting logLevel: 'silent' will hide all console output. The module leverages webpack-log for logging management, and more information can be found on its page.

webpack.config.js

module.exports = {
  plugins: [new CopyPlugin([...patterns], { logLevel: 'debug' })],
};

`ignore`

Array of globs to ignore (applied to from).

webpack.config.js

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

`context`

A path that determines how to interpret the from path, shared for all patterns.

webpack.config.js

module.exports = {
  plugins: [new CopyPlugin([...patterns], { context: '/app' })],
};

`copyUnmodified`

Copies files, regardless of modification when using watch or webpack-dev-server. All files are copied on first build, regardless of this option.

ℹ️ By default, we only copy modified files during a webpack --watch or webpack-dev-server build. Setting this option to true will copy all files.

webpack.config.js

module.exports = {
  plugins: [new CopyPlugin([...patterns], { copyUnmodified: true })],
};

Contributing

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

CONTRIBUTING

License

MIT

Current Tags

12.0.2 ... latest (a year ago)
5.1.2 ... version-5 (4 years ago)
6.4.1 ... version-6 (4 years ago)

copy-webpack-plugin

Getting Started

Options

Patterns

from

to

context

toType

'dir'

'file'

'template'

test

force

ignore

flatten

cache

transform

transformPath

Options

logLevel

ignore

context

copyUnmodified

Contributing

License

Current Tags

80 Versions

`from`

`to`

`context`

`toType`

`'dir'`

`'file'`

`'template'`

`test`

`force`

`ignore`

`flatten`

`cache`

`transform`

`transformPath`

`logLevel`

`ignore`

`context`

`copyUnmodified`