diff options
author | 2020-11-16 00:10:28 +0100 | |
---|---|---|
committer | 2020-11-16 00:10:28 +0100 | |
commit | e06ec920f7a5d784e674c4c4b4e6d1da3dc7391d (patch) | |
tree | 55713f725f77b44ebfec86e4eec3ce33e71458ca /node_modules/copy-webpack-plugin/README.md | |
download | website_creator-e06ec920f7a5d784e674c4c4b4e6d1da3dc7391d.tar.gz website_creator-e06ec920f7a5d784e674c4c4b4e6d1da3dc7391d.tar.bz2 website_creator-e06ec920f7a5d784e674c4c4b4e6d1da3dc7391d.zip |
api, login, auth
Diffstat (limited to 'node_modules/copy-webpack-plugin/README.md')
-rw-r--r-- | node_modules/copy-webpack-plugin/README.md | 970 |
1 files changed, 970 insertions, 0 deletions
diff --git a/node_modules/copy-webpack-plugin/README.md b/node_modules/copy-webpack-plugin/README.md new file mode 100644 index 0000000..e388ef8 --- /dev/null +++ b/node_modules/copy-webpack-plugin/README.md @@ -0,0 +1,970 @@ +<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> +</div> + +[![npm][npm]][npm-url] +[![node][node]][node-url] +[![deps][deps]][deps-url] +[![tests][tests]][tests-url] +[![cover][cover]][cover-url] +[![chat][chat]][chat-url] +[![size][size]][size-url] + +# 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`: + +```console +$ npm install copy-webpack-plugin --save-dev +``` + +Then add the plugin to your `webpack` config. For example: + +**webpack.config.js** + +```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`](https://github.com/webpack/webpack-dev-middleware#writetodisk) option or the [`write-file-webpack-plugin`](https://github.com/gajus/write-file-webpack-plugin). + +> ℹ️ You can get the original source filename from [Asset Objects](https://webpack.js.org/api/stats/#asset-objects). + +## Options + +The plugin's signature: + +**webpack.config.js** + +```js +const CopyPlugin = require("copy-webpack-plugin"); + +module.exports = { + plugins: [ + new CopyPlugin({ + patterns: [ + { from: "source", to: "dest" }, + { from: "other", to: "public" }, + ], + options: { + concurrency: 100, + }, + }), + ], +}; +``` + +### Patterns + +| Name | Type | Default | Description | +| :-------------------------------------: | :-------------------------: | :---------------------------------------------: | :---------------------------------------------------------------------------------------------------- | +| [`from`](#from) | `{String}` | `undefined` | Glob or path from where we сopy files. | +| [`to`](#to) | `{String}` | `compiler.options.output` | Output path. | +| [`context`](#context) | `{String}` | `options.context \|\| compiler.options.context` | A path that determines how to interpret the `from` path. | +| [`globOptions`](#globoptions) | `{Object}` | `undefined` | [Options][glob-options] passed to the glob pattern matching library including `ignore` option. | +| [`filter`](#filter) | `{Function}` | `undefined` | Allows to filter copied assets. | +| [`toType`](#totype) | `{String}` | `undefined` | Determinate what is `to` option - directory, file or template. | +| [`force`](#force) | `{Boolean}` | `false` | Overwrites files already in `compilation.assets` (usually added by other plugins/loaders). | +| [`flatten`](#flatten) | `{Boolean}` | `false` | Removes all directory references and only copies file names. | +| [`transform`](#transform) | `{Function}` | `undefined` | Allows to modify the file contents. | +| [`cacheTransform`](#cacheTransform) | `{Boolean\|String\|Object}` | `false` | Enable `transform` caching. You can use `{ cache: { key: 'my-cache-key' } }` to invalidate the cache. | +| [`transformPath`](#transformpath) | `{Function}` | `undefined` | Allows to modify the writing path. | +| [`noErrorOnMissing`](#noerroronmissing) | `{Boolean}` | `false` | Doesn't generate an error on missing file(s). | + +#### `from` + +Type: `String` +Default: `undefined` + +Glob or path from where we сopy files. +Globs accept [fast-glob pattern-syntax](https://github.com/mrmlnc/fast-glob#pattern-syntax). +Glob can only be a `string`. + +> ⚠️ Don't use directly `\\` in `from` option if it is a `glob` (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 `/`. + +**webpack.config.js** + +```js +module.exports = { + plugins: [ + new CopyPlugin({ + patterns: [ + "relative/path/to/file.ext", + "relative/path/to/dir", + path.resolve(__dirname, "src", "file.ext"), + path.resolve(__dirname, "src", "dir"), + "**/*", + { + from: "**/*", + }, + // If absolute path is a `glob` we replace backslashes with forward slashes, because only forward slashes can be used in the `glob` + path.posix.join( + path.resolve(__dirname, "src").replace(/\\/g, "/"), + "*.txt" + ), + ], + }), + ], +}; +``` + +##### `For windows` + +If you define `from` as absolute file path or absolute folder path on `Windows`, you can use windows path segment (`\\`) + +```js +module.exports = { + plugins: [ + new CopyPlugin({ + patterns: [ + { + from: path.resolve(__dirname, "file.txt"), + }, + ], + }), + ], +}; +``` + +But you should always use forward-slashes in `glob` expressions +See [fast-glob manual](https://github.com/mrmlnc/fast-glob#how-to-write-patterns-on-windows). + +```js +module.exports = { + plugins: [ + new CopyPlugin({ + patterns: [ + { + // 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, "fixtures").replace(/\\/g, "/"), + "*.txt" + ), + }, + ], + }), + ], +}; +``` + +The `context` behaves differently depending on what the `from` is (`glob`, `file` or `dir`). +More [`examples`](#examples) + +#### `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** + +```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** + +```js +module.exports = { + plugins: [ + new CopyPlugin({ + patterns: [ + { + from: "src/*.txt", + to: "dest/", + context: "app/", + }, + ], + }), + ], +}; +``` + +The `context` option can be an absolute or relative path. If `context` is a relative, then it is converted to absolute based to `compiler.options.context` + +Also, `context` indicates how to interpret the search results. Further, he is considered in this role. + +To determine the structure from which the found resources will be copied to the destination folder, the `context` option is used. + +If `from` is a file, then `context` is equal to the directory in which this file is located. Accordingly, the result will be only the file name. + +If `from` is a directory, then `context` is the same as `from` and is equal to the directory itself. In this case, the result will be a hierarchical structure of the found folders and files relative to the specified directory. + +If `from` is a glob, then regardless of the `context` option, the result will be the structure specified in the `from` option + +More [`examples`](#examples) + +#### `globOptions` + +Type: `Object` +Default: `undefined` + +Allows to configute the glob pattern matching library used by the plugin. [See the list of supported options][glob-options] +To exclude files from the selection, you should use [globOptions.ignore option](https://github.com/mrmlnc/fast-glob#ignore) + +**webpack.config.js** + +```js +module.exports = { + plugins: [ + new CopyPlugin({ + patterns: [ + { + from: "public/**/*", + globOptions: { + dot: true, + gitignore: true, + ignore: ["**/file.*", "**/ignored-directory/**"], + }, + }, + ], + }), + ], +}; +``` + +#### `filter` + +Type: `Function` +Default: `undefined` + +> ℹ️ To ignore files by path please use the [`globOptions.ignore`]((#globoptions) option. + +**webpack.config.js** + +```js +const fs = require("fs").promise; + +module.exports = { + plugins: [ + new CopyPlugin({ + patterns: [ + { + from: "public/**/*", + filter: async (resourcePath) => { + const data = await fs.promises.readFile(resourcePath); + const content = data.toString(); + + if (content === "my-custom-content") { + return false; + } + + return 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 | +| :--------------: | :--------: | :---------: | :------------------------------------------------------------------------------------------------- | +| **`'dir'`** | `{String}` | `undefined` | If `to` has no extension or ends on `'/'` | +| **`'file'`** | `{String}` | `undefined` | If `to` is not a directory and is not a template | +| **`'template'`** | `{String}` | `undefined` | If `to` contains [a template pattern](https://github.com/webpack-contrib/file-loader#placeholders) | + +##### `'dir'` + +**webpack.config.js** + +```js +module.exports = { + plugins: [ + new CopyPlugin({ + patterns: [ + { + from: "path/to/file.txt", + to: "directory/with/extension.ext", + toType: "dir", + }, + ], + }), + ], +}; +``` + +##### `'file'` + +**webpack.config.js** + +```js +module.exports = { + plugins: [ + new CopyPlugin({ + patterns: [ + { + from: "path/to/file.txt", + to: "file/without/extension", + toType: "file", + }, + ], + }), + ], +}; +``` + +##### `'template'` + +**webpack.config.js** + +```js +module.exports = { + plugins: [ + new CopyPlugin({ + patterns: [ + { + from: "src/", + to: "dest/[name].[hash].[ext]", + toType: "template", + }, + ], + }), + ], +}; +``` + +#### `force` + +Type: `Boolean` +Default: `false` + +Overwrites files already in `compilation.assets` (usually added by other plugins/loaders). + +**webpack.config.js** + +```js +module.exports = { + plugins: [ + new CopyPlugin({ + patterns: [ + { + from: "src/**/*", + to: "dest/", + force: true, + }, + ], + }), + ], +}; +``` + +#### `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** + +```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** + +```js +module.exports = { + plugins: [ + new CopyPlugin({ + patterns: [ + { + from: "src/*.png", + to: "dest/", + // 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); + }, + }, + ], + }), + ], +}; +``` + +**webpack.config.js** + +```js +module.exports = { + plugins: [ + new CopyPlugin({ + patterns: [ + { + from: "src/*.png", + to: "dest/", + transform(content, path) { + return Promise.resolve(optimize(content)); + }, + }, + ], + }), + ], +}; +``` + +#### `cacheTransform` + +Type: `Boolean|String|Object` +Default: `false` + +Enable/disable and configure caching. +Default path to cache directory: `node_modules/.cache/copy-webpack-plugin`. + +##### `Boolean` + +Enables/Disable `transform` caching. + +**webpack.config.js** + +```js +module.exports = { + plugins: [ + new CopyPlugin({ + patterns: [ + { + from: "src/*.png", + to: "dest/", + transform(content, path) { + return optimize(content); + }, + cacheTransform: true, + }, + ], + }), + ], +}; +``` + +##### `String` + +Enables `transform` caching and setup cache directory. + +**webpack.config.js** + +```js +module.exports = { + plugins: [ + new CopyPlugin({ + patterns: [ + { + from: "src/*.png", + to: "dest/", + transform(content, path) { + return optimize(content); + }, + // Should be absolute + cacheTransform: path.resolve(__dirname, "cache-directory"), + }, + ], + }), + ], +}; +``` + +##### `Object` + +Enables `transform` caching and setup cache directory and invalidation keys. + +**webpack.config.js** + +```js +module.exports = { + plugins: [ + new CopyPlugin({ + patterns: [ + { + from: "src/*.png", + to: "dest/", + transform(content, path) { + return optimize(content); + }, + cacheTransform: { + directory: path.resolve(__dirname, "cache-directory"), + keys: { + // May be useful for invalidating cache based on external values + // For example, you can invalid cache based on `process.version` - { node: process.version } + key: "value", + }, + }, + }, + ], + }), + ], +}; +``` + +You can setup invalidation keys using a function. + +Simple function: + +**webpack.config.js** + +```js +module.exports = { + plugins: [ + new CopyPlugin({ + patterns: [ + { + from: "src/*.png", + to: "dest/", + transform(content, path) { + return optimize(content); + }, + cacheTransform: { + directory: path.resolve(__dirname, "cache-directory"), + keys: (defaultCacheKeys, absoluteFrom) => { + const keys = getCustomCacheInvalidationKeysSync(); + + return { + ...defaultCacheKeys, + keys, + }; + }, + }, + }, + ], + }), + ], +}; +``` + +Async function: + +**webpack.config.js** + +```js +module.exports = { + plugins: [ + new CopyPlugin({ + patterns: [ + { + from: "src/*.png", + to: "dest/", + transform(content, path) { + return optimize(content); + }, + cacheTransform: { + directory: path.resolve(__dirname, "cache-directory"), + keys: async (defaultCacheKeys, absoluteFrom) => { + const keys = await getCustomCacheInvalidationKeysAsync(); + + return { + ...defaultCacheKeys, + keys, + }; + }, + }, + }, + ], + }), + ], +}; +``` + +#### `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** + +```js +module.exports = { + plugins: [ + new CopyPlugin({ + patterns: [ + { + from: "src/*.png", + to: "dest/", + transformPath(targetPath, absolutePath) { + return "newPath"; + }, + }, + ], + }), + ], +}; +``` + +**webpack.config.js** + +```js +module.exports = { + plugins: [ + new CopyPlugin({ + patterns: [ + { + from: "src/*.png", + to: "dest/", + transformPath(targetPath, absolutePath) { + return Promise.resolve("newPath"); + }, + }, + ], + }), + ], +}; +``` + +### `noErrorOnMissing` + +Type: `Boolean` +Default: `false` + +Doesn't generate an error on missing file(s); + +```js +module.exports = { + plugins: [ + new CopyPlugin({ + patterns: [ + { + from: path.resolve(__dirname, "missing-file.txt"), + noErrorOnMissing: true, + }, + ], + }), + ], +}; +``` + +### Options + +| Name | Type | Default | Description | +| :---------------------------: | :--------: | :-----: | :----------------------------------------------- | +| [`concurrency`](#concurrency) | `{Number}` | `100` | Limits the number of simultaneous requests to fs | + +#### `concurrency` + +limits the number of simultaneous requests to fs + +**webpack.config.js** + +```js +module.exports = { + plugins: [ + new CopyPlugin({ + patterns: [...patterns], + options: { concurrency: 50 }, + }), + ], +}; +``` + +### Examples + +#### Different variants `from` (`glob`, `file` or `dir`). + +Take for example the following file structure: + +``` +src/directory-nested/deep-nested/deepnested-file.txt +src/directory-nested/nested-file.txt +``` + +##### From is a Glob + +Everything that you specify in `from` will be included in the result: + +**webpack.config.js** + +```js +module.exports = { + plugins: [ + new CopyPlugin({ + patterns: [ + { + from: "src/directory-nested/**/*", + }, + ], + }), + ], +}; +``` + +Result: + +```txt +src/directory-nested/deep-nested/deepnested-file.txt, +src/directory-nested/nested-file.txt +``` + +If you want only content `src/directory-nested/`, you should only indicate `glob` in `from`. The path to the folder in which the search should take place, should be moved to `context`. + +**webpack.config.js** + +```js +module.exports = { + plugins: [ + new CopyPlugin({ + patterns: [ + { + from: "**/*", + context: path.resolve(__dirname, "src", "directory-nested"), + }, + ], + }), + ], +}; +``` + +Result: + +```txt +deep-nested/deepnested-file.txt, +nested-file.txt +``` + +##### From is a Dir + +**webpack.config.js** + +```js +module.exports = { + plugins: [ + new CopyPlugin({ + patterns: [ + { + from: path.resolve(__dirname, "src", "directory-nested"), + }, + ], + }), + ], +}; +``` + +Result: + +```txt +deep-nested/deepnested-file.txt, +nested-file.txt +``` + +Technically, this is `**/*` with a predefined context equal to the specified directory. + +**webpack.config.js** + +```js +module.exports = { + plugins: [ + new CopyPlugin({ + patterns: [ + { + from: "**/*", + context: path.resolve(__dirname, "src", "directory-nested"), + }, + ], + }), + ], +}; +``` + +Result: + +```txt +deep-nested/deepnested-file.txt, +nested-file.txt +``` + +##### From is a File + +```js +module.exports = { + plugins: [ + new CopyPlugin({ + patterns: [ + { + from: path.resolve( + __dirname, + "src", + "directory-nested", + "nested-file.txt" + ), + }, + ], + }), + ], +}; +``` + +Result: + +```txt +nested-file.txt +``` + +Technically, this is a filename with a predefined context equal to `path.dirname(pathToFile)`. + +**webpack.config.js** + +```js +module.exports = { + plugins: [ + new CopyPlugin({ + patterns: [ + { + from: "nested-file.txt", + context: path.resolve(__dirname, "src", "directory-nested"), + }, + ], + }), + ], +}; +``` + +Result: + +```txt +nested-file.txt +``` + +#### Ignoring files + +**webpack.config.js** + +```js +module.exports = { + plugins: [ + new CopyPlugin({ + patterns: [ + { + from: path.posix.join( + path.resolve(__dirname, "src").replace(/\\/g, "/"), + "**/*" + ), + globOptions: { + ignore: [ + // Ignore all `txt` files + "**/*.txt", + // Ignore all files in all subdirectories + "**/subdir/**", + ], + }, + }, + ], + }), + ], +}; +``` + +## Contributing + +Please take a moment to read our contributing guidelines if you haven't yet done so. + +[CONTRIBUTING](./.github/CONTRIBUTING.md) + +## License + +[MIT](./LICENSE) + +[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 +[tests]: https://github.com/webpack-contrib/copy-webpack-plugin/workflows/copy-webpack-plugin/badge.svg +[tests-url]: https://github.com/webpack-contrib/copy-webpack-plugin/actions +[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 +[size]: https://packagephobia.now.sh/badge?p=copy-webpack-plugin +[size-url]: https://packagephobia.now.sh/result?p=copy-webpack-plugin +[glob-options]: https://github.com/sindresorhus/globby#options |