450 lines
9.9 KiB
Markdown
450 lines
9.9 KiB
Markdown
[![npm][npm]][npm-url]
|
||
[![node][node]][node-url]
|
||
[![deps][deps]][deps-url]
|
||
[![test][test]][test-url]
|
||
[![coverage][cover]][cover-url]
|
||
[![chat][chat]][chat-url]
|
||
|
||
<div align="center">
|
||
<a href="https://github.com/webpack/webpack">
|
||
<img width="200" height="200"
|
||
src="https://webpack.js.org/assets/icon-square-big.svg">
|
||
</a>
|
||
<h1>Copy Webpack Plugin</h1>
|
||
<p>Copies individual files or entire directories to the build directory</p>
|
||
</div>
|
||
|
||
<h2 align="center">Install</h2>
|
||
|
||
```bash
|
||
npm i -D copy-webpack-plugin
|
||
```
|
||
|
||
<h2 align="center">Usage</h2>
|
||
|
||
**webpack.config.js**
|
||
```js
|
||
const CopyWebpackPlugin = require('copy-webpack-plugin')
|
||
|
||
const config = {
|
||
plugins: [
|
||
new CopyWebpackPlugin([ ...patterns ], options)
|
||
]
|
||
}
|
||
```
|
||
|
||
> ℹ️ If you want `webpack-dev-server` to write files to the output directory during development, you can force it with the [`write-file-webpack-plugin`](https://github.com/gajus/write-file-webpack-plugin).
|
||
|
||
### `Patterns`
|
||
|
||
A simple pattern looks like this
|
||
|
||
```js
|
||
{ from: 'source', to: 'dest' }
|
||
```
|
||
|
||
Or, in case of just a `from` with the default destination, you can also use a `{String}` as shorthand instead of an `{Object}`
|
||
|
||
```js
|
||
'source'
|
||
```
|
||
|
||
|Name|Type|Default|Description|
|
||
|:--:|:--:|:-----:|:----------|
|
||
|[`from`](#from)|`{String\|Object}`|`undefined`|Globs accept [minimatch options](https://github.com/isaacs/minimatch)|
|
||
|[`fromArgs`](#fromArgs)|`{Object}`|`{ cwd: context }`|See the [`node-glob` options](https://github.com/isaacs/node-glob#options) in addition to the ones below|
|
||
|[`to`](#to)|`{String\|Object}`|`undefined`|Output root if `from` is file or dir, resolved glob path if `from` is glob|
|
||
|[`toType`](#toType)|`{String}`|``|[toType Options](#totype)|
|
||
|[`test`](#test)|`{RegExp}`|``|Pattern for extracting elements to be used in `to` templates|
|
||
|[`force`](#force)|`{Boolean}`|`false`|Overwrites files already in `compilation.assets` (usually added by other plugins/loaders)|
|
||
|[`ignore`](#ignore)|`{Array}`|`[]`|Globs to ignore for this pattern|
|
||
|`flatten`|`{Boolean}`|`false`|Removes all directory references and only copies file names.⚠️ If files have the same name, the result is non-deterministic|
|
||
|[`transform`](#transform)|`{Function\|Promise}`|`(content, path) => content`|Function or Promise that modifies file contents before copying|
|
||
|[`transformPath`](#transformPath)|`{Function\|Promise}`|`(targetPath, sourcePath) => path`|Function or Promise that modifies file writing path|
|
||
|[`cache`](#cache)|`{Boolean\|Object}`|`false`|Enable `transform` caching. You can use `{ cache: { key: 'my-cache-key' } }` to invalidate the cache|
|
||
|[`context`](#context)|`{String}`|`options.context \|\| compiler.options.context`|A path that determines how to interpret the `from` path|
|
||
|
||
### `from`
|
||
|
||
**webpack.config.js**
|
||
```js
|
||
[
|
||
new CopyWebpackPlugin([
|
||
'relative/path/to/file.ext',
|
||
'/absolute/path/to/file.ext',
|
||
'relative/path/to/dir',
|
||
'/absolute/path/to/dir',
|
||
'**/*',
|
||
{ glob: '\*\*/\*', dot: true }
|
||
], options)
|
||
]
|
||
```
|
||
|
||
### `to`
|
||
|
||
**webpack.config.js**
|
||
```js
|
||
[
|
||
new CopyWebpackPlugin([
|
||
{ from: '**/*', to: 'relative/path/to/dest/' },
|
||
{ from: '**/*', to: '/absolute/path/to/dest/' }
|
||
], options)
|
||
]
|
||
```
|
||
|
||
### `toType`
|
||
|
||
|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](https://github.com/webpack-contrib/file-loader#placeholders)|
|
||
|
||
#### `'dir'`
|
||
|
||
**webpack.config.js**
|
||
```js
|
||
[
|
||
new CopyWebpackPlugin([
|
||
{
|
||
from: 'path/to/file.txt',
|
||
to: 'directory/with/extension.ext',
|
||
toType: 'dir'
|
||
}
|
||
], options)
|
||
]
|
||
```
|
||
|
||
#### `'file'`
|
||
|
||
**webpack.config.js**
|
||
```js
|
||
[
|
||
new CopyWebpackPlugin([
|
||
{
|
||
from: 'path/to/file.txt',
|
||
to: 'file/without/extension',
|
||
toType: 'file'
|
||
},
|
||
], options)
|
||
]
|
||
```
|
||
|
||
#### `'template'`
|
||
|
||
**webpack.config.js**
|
||
```js
|
||
[
|
||
new CopyWebpackPlugin([
|
||
{
|
||
from: 'src/',
|
||
to: 'dest/[name].[hash].[ext]',
|
||
toType: 'template'
|
||
}
|
||
], options)
|
||
]
|
||
```
|
||
|
||
### `test`
|
||
|
||
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**
|
||
```js
|
||
[
|
||
new CopyWebpackPlugin([
|
||
{
|
||
from: '*/*',
|
||
to: '[1]-[2].[hash].[ext]',
|
||
test: /([^/]+)\/(.+)\.png$/
|
||
}
|
||
], options)
|
||
]
|
||
```
|
||
|
||
### `force`
|
||
|
||
**webpack.config.js**
|
||
```js
|
||
[
|
||
new CopyWebpackPlugin([
|
||
{ from: 'src/**/*', to: 'dest/', force: true }
|
||
], options)
|
||
]
|
||
```
|
||
|
||
### `ignore`
|
||
|
||
**webpack.config.js**
|
||
```js
|
||
[
|
||
new CopyWebpackPlugin([
|
||
{ from: 'src/**/*', to: 'dest/', ignore: [ '*.js' ] }
|
||
], options)
|
||
]
|
||
```
|
||
|
||
### `flatten`
|
||
|
||
**webpack.config.js**
|
||
```js
|
||
[
|
||
new CopyWebpackPlugin([
|
||
{ from: 'src/**/*', to: 'dest/', flatten: true }
|
||
], options)
|
||
]
|
||
```
|
||
|
||
### `transform`
|
||
|
||
#### `{Function}`
|
||
|
||
**webpack.config.js**
|
||
```js
|
||
[
|
||
new CopyWebpackPlugin([
|
||
{
|
||
from: 'src/*.png',
|
||
to: 'dest/',
|
||
transform (content, path) {
|
||
return optimize(content)
|
||
}
|
||
}
|
||
], options)
|
||
]
|
||
```
|
||
|
||
#### `{Promise}`
|
||
|
||
**webpack.config.js**
|
||
```js
|
||
[
|
||
new CopyWebpackPlugin([
|
||
{
|
||
from: 'src/*.png',
|
||
to: 'dest/',
|
||
transform (content, path) {
|
||
return Promise.resolve(optimize(content))
|
||
}
|
||
}
|
||
], options)
|
||
]
|
||
```
|
||
|
||
### `transformPath`
|
||
|
||
#### `{Function}`
|
||
|
||
**webpack.config.js**
|
||
```js
|
||
[
|
||
new CopyWebpackPlugin([
|
||
{
|
||
from: 'src/*.png',
|
||
to: 'dest/',
|
||
transformPath (targetPath, absolutePath) {
|
||
return 'newPath';
|
||
}
|
||
}
|
||
], options)
|
||
]
|
||
```
|
||
|
||
#### `{Promise}`
|
||
|
||
**webpack.config.js**
|
||
```js
|
||
[
|
||
new CopyWebpackPlugin([
|
||
{
|
||
from: 'src/*.png',
|
||
to: 'dest/',
|
||
transform (targePath, absolutePath) {
|
||
return Promise.resolve('newPath')
|
||
}
|
||
}
|
||
], options)
|
||
]
|
||
```
|
||
|
||
|
||
### `cache`
|
||
|
||
**webpack.config.js**
|
||
```js
|
||
[
|
||
new CopyWebpackPlugin([
|
||
{
|
||
from: 'src/*.png',
|
||
to: 'dest/',
|
||
transform (content, path) {
|
||
return optimize(content)
|
||
},
|
||
cache: true
|
||
}
|
||
], options)
|
||
]
|
||
```
|
||
|
||
### `context`
|
||
|
||
**webpack.config.js**
|
||
```js
|
||
[
|
||
new CopyWebpackPlugin([
|
||
{ from: 'src/*.txt', to: 'dest/', context: 'app/' }
|
||
], options)
|
||
]
|
||
```
|
||
|
||
<h2 align="center">Options</h2>
|
||
|
||
|Name|Type|Default|Description|
|
||
|:--:|:--:|:-----:|:----------|
|
||
|[`debug`](#debug)|`{String}`|**`'warning'`**|[Debug Options](#debug)|
|
||
|[`ignore`](#ignore)|`{Array}`|`[]`|Array of globs to ignore (applied to `from`)|
|
||
|[`context`](#context)|`{String}`|`compiler.options.context`|A path that determines how to interpret the `from` path, shared for all patterns|
|
||
|[`copyUnmodified`](#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|
|
||
|
||
### `debug`
|
||
|
||
|Name|Type|Default|Description|
|
||
|:--:|:--:|:-----:|:----------|
|
||
|**`'info'`**|`{String\|Boolean}`|`false`|File location and read info|
|
||
|**`'debug'`**|`{String}`|`false`|Very detailed debugging info|
|
||
|**`'warning'`**|`{String}`|`true`|Only warnings|
|
||
|
||
#### `'info'`
|
||
|
||
**webpack.config.js**
|
||
```js
|
||
[
|
||
new CopyWebpackPlugin(
|
||
[ ...patterns ],
|
||
{ debug: 'info' }
|
||
)
|
||
]
|
||
```
|
||
|
||
#### `'debug'`
|
||
|
||
**webpack.config.js**
|
||
```js
|
||
[
|
||
new CopyWebpackPlugin(
|
||
[ ...patterns ],
|
||
{ debug: 'debug' }
|
||
)
|
||
]
|
||
```
|
||
|
||
#### `'warning' (default)`
|
||
|
||
**webpack.config.js**
|
||
```js
|
||
[
|
||
new CopyWebpackPlugin(
|
||
[ ...patterns ],
|
||
{ debug: true }
|
||
)
|
||
]
|
||
```
|
||
|
||
### `ignore`
|
||
|
||
**webpack.config.js**
|
||
```js
|
||
[
|
||
new CopyWebpackPlugin(
|
||
[ ...patterns ],
|
||
{ ignore: [ '*.js', '*.css' ] }
|
||
)
|
||
]
|
||
```
|
||
|
||
### `context`
|
||
|
||
**webpack.config.js**
|
||
```js
|
||
[
|
||
new CopyWebpackPlugin(
|
||
[ ...patterns ],
|
||
{ context: '/app' }
|
||
)
|
||
]
|
||
```
|
||
|
||
### `copyUnmodified`
|
||
|
||
> ℹ️ 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**
|
||
```js
|
||
[
|
||
new CopyWebpackPlugin(
|
||
[ ...patterns ],
|
||
{ copyUnmodified: true }
|
||
)
|
||
]
|
||
```
|
||
|
||
<h2 align="center">Maintainers</h2>
|
||
|
||
<table>
|
||
<tbody>
|
||
<tr>
|
||
<td align="center">
|
||
<a href="https://github.com/bebraw">
|
||
<img width="150" height="150" src="https://github.com/bebraw.png?v=3&s=150">
|
||
</br>
|
||
Juho Vepsäläinen
|
||
</a>
|
||
</td>
|
||
<td align="center">
|
||
<a href="https://github.com/d3viant0ne">
|
||
<img width="150" height="150" src="https://github.com/d3viant0ne.png?v=3&s=150">
|
||
</br>
|
||
Joshua Wiens
|
||
</a>
|
||
</td>
|
||
<td align="center">
|
||
<a href="https://github.com/michael-ciniawsky">
|
||
<img width="150" height="150" src="https://github.com/michael-ciniawsky.png?v=3&s=150">
|
||
</br>
|
||
Michael Ciniawsky
|
||
</a>
|
||
</td>
|
||
<td align="center">
|
||
<a href="https://github.com/evilebottnawi">
|
||
<img width="150" height="150" src="https://github.com/evilebottnawi.png?v=3&s=150">
|
||
</br>
|
||
Alexander Krasnoyarov
|
||
</a>
|
||
</td>
|
||
</tr>
|
||
<tbody>
|
||
</table>
|
||
|
||
|
||
[npm]: https://img.shields.io/npm/v/copy-webpack-plugin.svg
|
||
[npm-url]: https://npmjs.com/package/copy-webpack-plugin
|
||
|
||
[node]: https://img.shields.io/node/v/copy-webpack-plugin.svg
|
||
[node-url]: https://nodejs.org
|
||
|
||
[deps]: https://david-dm.org/webpack-contrib/copy-webpack-plugin.svg
|
||
[deps-url]: https://david-dm.org/webpack-contrib/copy-webpack-plugin
|
||
|
||
[test]: https://secure.travis-ci.org/webpack-contrib/copy-webpack-plugin.svg
|
||
[test-url]: http://travis-ci.org/webpack-contrib/copy-webpack-plugin
|
||
|
||
[cover]: https://codecov.io/gh/webpack-contrib/copy-webpack-plugin/branch/master/graph/badge.svg
|
||
[cover-url]: https://codecov.io/gh/webpack-contrib/copy-webpack-plugin
|
||
|
||
[chat]: https://img.shields.io/badge/gitter-webpack%2Fwebpack-brightgreen.svg
|
||
[chat-url]: https://gitter.im/webpack/webpack
|