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([ { 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 thewriteToDisk
option or thewrite-file-webpack-plugin
.
Options
The plugin's signature:
webpack.config.js
module.exports = { plugins: [new CopyPlugin(patterns, options)], };
Patterns
Name | Type | Default | Description |
---|---|---|---|
| {String\|Object} | undefined | Glob or path from where we сopy files. |
| {String} | undefined | Output path. |
| {String} | options.context \|\| compiler.options.context | A path that determines how to interpret the from path. |
| {String} | undefined | Determinate what is to option - directory, file or template. |
| {RegExp} | undefined | Pattern for extracting elements to be used in to templates. |
| {Boolean} | false | Overwrites files already in compilation.assets (usually added by other plugins/loaders). |
| {Array} | [] | Globs to ignore files. |
| {Boolean} | false | Removes all directory references and only copies file names. |
| {Boolean\|Object} | false | Enable transform caching. You can use { cache: { key: 'my-cache-key' } } to invalidate the cache. |
| {Function\|Promise} | undefined | Allows to modify the file contents. |
| {Function\|Promise} | 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
\\
infrom
(i.epath\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/
orpath
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', '**/*', { glob: '**/*', dot: false }, ]), ], };
to
Type: String
Default: undefined
Output path.
⚠️ Don't use directly
\\
into
(i.epath\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/
orpath
methods.
webpack.config.js
module.exports = { plugins: [ new CopyPlugin([ { from: '**/*', to: 'relative/path/to/dest/' }, { from: '**/*', to: '/absolute/path/to/dest/' }, ]), ], };
context
Type: String
Default: options.context|compiler.options.context
A path that determines how to interpret the from
path.
⚠️ Don't use directly
\\
incontext
(i.epath\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/
orpath
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 |
---|---|---|---|
| {String} | undefined | If from is directory, to has no extension or ends in '/'
|
| {String} | undefined | If to has extension or from is file |
| {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: 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'], }, ]), ], };
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|Promise
Default: undefined
Allows to modify the file contents.
{Function}
webpack.config.js
module.exports = { plugins: [ new CopyPlugin([ { from: 'src/*.png', to: 'dest/', transform(content, path) { return optimize(content); }, }, ]), ], };
{Promise}
webpack.config.js
module.exports = { plugins: [ new CopyPlugin([ { from: 'src/*.png', to: 'dest/', transform(content, path) { return Promise.resolve(optimize(content)); }, }, ]), ], };
transformPath
Type: Function|Promise
Default: undefined
Allows to modify the writing path.
⚠️ Don't return directly
\\
intransformPath
(i.epath\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/
orpath
methods.
{Function}
webpack.config.js
module.exports = { plugins: [ new CopyPlugin([ { from: 'src/*.png', to: 'dest/', transformPath(targetPath, absolutePath) { return 'newPath'; }, }, ]), ], };
{Promise}
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 |
---|---|---|---|
| {String} | 'warn' | Level of messages that the module will log |
| {Array} | [] | Array of globs to ignore (applied to from ) |
| {String} | compiler.options.context | A path that determines how to interpret the from path, shared for all patterns |
| {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
orwebpack-dev-server
build. Setting this option totrue
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.
License
© JS Foundation and other contributors
Licensed under the Creative Commons Attribution License 4.0.
https://v4.webpack.js.org/plugins/copy-webpack-plugin