[![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:

npm install copy-webpack-plugin --save-dev

or

yarn add -D copy-webpack-plugin

or

pnpm add -D copy-webpack-plugin

Then add the plugin to your webpack configuration. For example:

webpack.config.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 option or use the write-file-webpack-plugin.

[!NOTE]

You can get the original source filename from the Asset Objects in the webpack stats API.

Options

• patterns
• options

The plugin's usage:

webpack.config.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
• to
• context
• globOptions
• filter
• toType
• force
• priority
• transform
• transformAll
• noErrorOnMissing
• info

from

Type:

type from = string;

Default: undefined

Glob or path from where we copy files. Globs follow the 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

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 (\\)

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 for more details.

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.

to

Type:

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

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

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: "src/*.png",
          to({ context, absoluteFilename }) {
            return "dest/newPath/[name][ext]";
          },
        },
      ],
    }),
  ],
};

webpack.config.js

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: "src/*.png",
          to({ context, absoluteFilename }) {
            return Promise.resolve("dest/newPath/[name][ext]");
          },
        },
      ],
    }),
  ],
};

context

Type:

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

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.

globOptions

[!WARNING]

The onlyDirectories does not work because the plugin is designed to copy files, not directories alone.

Type:

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

webpack.config.js

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: "public/**/*",
          globOptions: {
            dot: true,
            gitignore: true,
            ignore: ["**/file.*", "**/ignored-directory/**"],
          },
        },
      ],
    }),
  ],
};

filter

Type:

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

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:

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'	string	undefined	Used to has no extension or ends with a '/'.
'file'	string	undefined	Used when to is a file path that is not a directory or template.
'template'	string	undefined	Used when to contains a template pattern

'dir'

webpack.config.js

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

'file'

webpack.config.js

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

'template'

webpack.config.js

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: "src/",
          to: "dest/[name].[contenthash][ext]",
          toType: "template",
        },
      ],
    }),
  ],
};

force

Type:

type force = boolean;

Default: false

Overwrites files that already exist in compilation.assets (typically added by other plugins or loaders).

webpack.config.js

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: "src/**/*",
          to: "dest/",
          force: true,
        },
      ],
    }),
  ],
};

priority

Type:

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 option must be set to true. webpack.config.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:

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

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