# copy-webpack-plugin **Repository Path**: mirrors_addons/copy-webpack-plugin ## Basic Information - **Project Name**: copy-webpack-plugin - **Description**: Copy files and directories with webpack - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2020-08-27 - **Last Updated**: 2025-08-30 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README
[![npm][npm]][npm-url] [![node][node]][node-url] [![tests][tests]][tests-url] [![cover][cover]][cover-url] [![discussion][discussion]][discussion-url] [![size][size]][size-url] # copy-webpack-plugin Copies existing individual files or entire directories to the build directory. ## Getting Started To begin, you'll need to install `copy-webpack-plugin`: ```console npm install copy-webpack-plugin --save-dev ``` or ```console yarn add -D copy-webpack-plugin ``` or ```console pnpm add -D copy-webpack-plugin ``` Then add the plugin to your `webpack` configuration. 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" }, ], }), ], }; ``` > [!NOTE] > > `copy-webpack-plugin` is not designed to copy files generated during the build process. Instead, it is meant to copy files that already exist in the source tree, as part of the build process. > [!NOTE] > > If you want `webpack-dev-server` to write files to the output directory during development, you can enable the [`writeToDisk`](https://github.com/webpack/webpack-dev-middleware#writetodisk) option or use the [`write-file-webpack-plugin`](https://github.com/gajus/write-file-webpack-plugin). > [!NOTE] > > You can get the original source filename from the [Asset Objects](https://webpack.js.org/api/stats/#asset-objects) in the webpack stats API. ## Options - **[`patterns`](#patterns)** - **[`options`](#options-1)** The plugin's usage: **webpack.config.js** ```js const CopyPlugin = require("copy-webpack-plugin"); module.exports = { plugins: [ new CopyPlugin({ patterns: [ { from: "source", to: "dest" }, "path/to/source", // Absolute or relative path, can be files, directories or globs. See examples below. ], options: { concurrency: 100, }, }), ], }; ``` ### `Patterns` - [`from`](#from) - [`to`](#to) - [`context`](#context) - [`globOptions`](#globoptions) - [`filter`](#filter) - [`toType`](#totype) - [`force`](#force) - [`priority`](#priority) - [`transform`](#transform) - [`transformAll`](#transformAll) - [`noErrorOnMissing`](#noerroronmissing) - [`info`](#info) #### `from` Type: ```ts type from = string; ``` Default: `undefined` Glob or path from where we copy files. Globs follow the [fast-glob pattern-syntax](https://github.com/mrmlnc/fast-glob#pattern-syntax). Note: Globs must be a `string`. > [!WARNING] > > Don't use directly `\\` in `from` option if it is a `glob` (i.e `path\to\file.ext`) option, as backslashes are treated as regular characters on UNIX systems(not as path separators). > On Windows, both forward slashes and backslashes act as separators. > Use `/` instead, or use Node's `path` utilities to normalize paths. **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").replaceAll("\\", "/"), "*.txt", ), ], }), ], }; ``` ##### `For windows` If you're using an absolute file or folder path in the `from` option on `Windows`, you can use windows path segment (`\\`) ```js module.exports = { plugins: [ new CopyPlugin({ patterns: [ { from: path.resolve(__dirname, "file.txt"), }, ], }), ], }; ``` However, when writing `glob` expressions, always use forward slashes. See the [fast-glob manual](https://github.com/mrmlnc/fast-glob#how-to-write-patterns-on-windows) for more details. ```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").replaceAll("\\", "/"), "*.txt", ), }, ], }), ], }; ``` The behavior of the `context` option varies depending on whether the `from` value is a `glob`, `file` or `dir`. See more [`examples`](#examples). #### `to` Type: ```ts type to = | string | ((pathData: { context: string; absoluteFilename?: string }) => string); ``` Default: `compiler.options.output` ##### `string` Specifies the output path. > [!WARNING] > > Don't use directly `\\` in the `to` path (i.e `path\to\dest`) option, as backslashes are treated as regular characters on UNIX systems(not as path separators). > On Windows, both forward slashes and backslashes act as separators. > Use `/` instead, or use Node's `path` utilities to normalize paths. **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]", }, ], }), ], }; ``` ##### `function` Allows to modify the writing path. > [!WARNING] > > Don't use directly `\\` in `to` (i.e `path\to\newFile`) option, as backslashes are treated as regular characters on UNIX systems(not as path separators). > On Windows, both forward slashes and backslashes act as separators. > Use `/` instead, or use Node's `path` utilities to normalize paths. **webpack.config.js** ```js module.exports = { plugins: [ new CopyPlugin({ patterns: [ { from: "src/*.png", to({ context, absoluteFilename }) { return "dest/newPath/[name][ext]"; }, }, ], }), ], }; ``` **webpack.config.js** ```js module.exports = { plugins: [ new CopyPlugin({ patterns: [ { from: "src/*.png", to({ context, absoluteFilename }) { return Promise.resolve("dest/newPath/[name][ext]"); }, }, ], }), ], }; ``` #### `context` Type: ```ts type context = string; ``` Default: `options.context|compiler.options.context` Defines the base directory used for two purposes: 1. It is prepended to the `from` path. 2. It is removed from the beginning of the result path(s). > [!WARNING] > > Don't use directly `\\` in `to` (i.e `path\to\newFile`) option, as backslashes are treated as regular characters on UNIX systems(not as path separators). > On Windows, both forward slashes and backslashes act as separators. > Use `/` instead, or use Node's `path` utilities to normalize paths. **webpack.config.js** ```js module.exports = { plugins: [ new CopyPlugin({ patterns: [ { from: "src/*.txt", to: "dest/", context: "app/", }, ], }), ], }; ``` The `context` can be an absolute or relative path. If it's relative, then it will be converted to an absolute path based on `compiler.options.context`. You should explicitly define `context` when `from` uses a glob pattern. Otherwise, the plugin sets it automatically based on the nature of `from`: - If `from` is a file, then `context` defaults to the file’s directory. The result path will be just the filename alone. - If `from` is a directory, `context` is set to the same directory. The result paths include the directory’s contents (including subdirectories), relative to it. The use of `context` is illustrated by these [`examples`](#examples). #### `globOptions` > [!WARNING] > > The _onlyDirectories_ does not work because the plugin is designed to copy files, not directories alone. Type: ```ts type globOptions = import("tinyglobby").GlobOptions; ``` Default: `undefined` Allows you to configure the glob pattern matching library used by the plugin. [See the list of supported options][glob-options] To exclude files from being copied, use the [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: ```ts type filter = (filepath: string) => boolean; ``` Default: `undefined` > [!NOTE] > > To ignore files by path (e.g., by extension or name), prefer using the [`globOptions.ignore`] option. **webpack.config.js** ```js const fs = require("node: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: ```ts type toType = "dir" | "file" | "template"; ``` Default: `undefined` Determines the type of the `to` option — whether it's a 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 should explicitly set the type to `dir`. In most cases, the plugin will automatically determine the correct `type`, so you typically don't need to set this option manually. | Name | Type | Default | Description | | :---------------------------: | :------: | :---------: | :---------------------------------------------------------------------------------------------------------- | | **[`'dir'`](#dir)** | `string` | `undefined` | Used `to` has no extension or ends with a `'/'`. | | **[`'file'`](#file)** | `string` | `undefined` | Used when `to` is a file path that is not a directory or template. | | **[`'template'`](#template)** | `string` | `undefined` | Used when `to` contains [a template pattern](https://webpack.js.org/configuration/output/#template-strings) | ##### `'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].[contenthash][ext]", toType: "template", }, ], }), ], }; ``` #### `force` Type: ```ts type force = boolean; ``` Default: `false` Overwrites files that already exist in `compilation.assets` (typically added by other plugins or loaders). **webpack.config.js** ```js module.exports = { plugins: [ new CopyPlugin({ patterns: [ { from: "src/**/*", to: "dest/", force: true, }, ], }), ], }; ``` #### `priority` Type: ```ts type priority = number; ``` Default: `0` Allows to specify the priority of copying files with the same destination name. Files for patterns with higher priority will be copied later. To enable overwriting, the [`force`](#force) option must be set to `true`. **webpack.config.js** ```js module.exports = { plugins: [ new CopyPlugin({ patterns: [ // Copied second and will overwrite "dir_2/file.txt" { from: "dir_1/file.txt", to: "newfile.txt", force: true, priority: 10, }, // Copied first { from: "dir_2/file.txt", to: "newfile.txt", priority: 5, }, ], }), ], }; ``` #### `transform` Type: ```ts type transform = | { transformer: (input: string, absoluteFilename: string) => string | Buffer; cache?: boolean | TransformerCacheObject | undefined; } | ((input: string, absoluteFilename: string) => string | Buffer); ``` Default: `undefined` Allows you to modify the contents of a file before it is written to the output directory. ##### `function` **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); }, }, ], }), ], }; ``` ##### `object` | Name | Default | Description | | :-------------------------------: | :---------: | :----------------------------------------------------------------------------------------------------------------------------------------- | | **[`transformer`](#transformer)** | `undefined` | Allows you to modify the contents of the file. | | **[`cache`](#cache)** | `false` | Enables caching for `transform`. You can use `transform: { cache: { key: 'my-cache-key' } }` to manually invalidate the cache when needed. | ###### `transformer` Type: ```ts type transformer = (input: string, absoluteFilename: string) => string; ``` Default: `undefined` **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: { transformer(content, absoluteFrom) { return optimize(content); }, }, }, ], }), ], }; ``` **webpack.config.js** ```js module.exports = { plugins: [ new CopyPlugin({ patterns: [ { from: "src/*.png", to: "dest/", transform: { transformer(content, path) { return Promise.resolve(optimize(content)); }, }, }, ], }), ], }; ``` ###### `cache` Type: ```ts type cache = | boolean | { keys: Record