CopyWebpackPlugin copies static files

CopyWebpackPlugin is a commonly used plugin in the Webpack ecosystem, designed to copy static files (such as images, fonts, JSON, etc.) from the source directory to the output directory during the build process. It is particularly useful for handling files that do not require Webpack processing, allowing them to be output as-is in the final bundle.

Why Use CopyWebpackPlugin?

In a project, apart from resources like JavaScript and CSS that need to be processed by Webpack, there are also numerous static files. For example:

• Website favicon.ico
• Font files from third-party libraries (e.g., Bootstrap's glyphicons)
• Local JSON configuration files
• Image assets (e.g., company logos)

Manually copying these files to the output directory is inefficient and error-prone. CopyWebpackPlugin automates this process through configuration rules, ensuring files are correctly synchronized during each build.

Installing the Plugin

First, install the plugin via npm or yarn:

npm install copy-webpack-plugin --save-dev
# or
yarn add copy-webpack-plugin --dev

Note: Different Webpack versions require matching plugin versions:

• Webpack 4 uses copy-webpack-plugin@6
• Webpack 5 uses copy-webpack-plugin@10+

Basic Configuration

Import and configure the plugin in webpack.config.js:

const CopyPlugin = require("copy-webpack-plugin");

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        { from: "src/assets/images", to: "images" },
        { from: "src/favicon.ico", to: "" }
      ]
    })
  ]
};

This configuration will:

1. Copy all files from src/assets/images to the images subdirectory in the output directory.
2. Copy src/favicon.ico to the root of the output directory.

Advanced Configuration Options

File Filtering

Use glob patterns to match specific files:

new CopyPlugin({
  patterns: [
    {
      from: "src/assets",
      to: "assets",
      globOptions: {
        ignore: ["**/*.txt"] // Ignore all .txt files
      }
    }
  ]
})

Modifying Filenames

Use transformPath to modify output paths:

new CopyPlugin({
  patterns: [
    {
      from: "src/version.json",
      to: "metadata/[name].[contenthash:8][ext]",
      transformPath(targetPath) {
        return targetPath.replace('version', 'build-info');
      }
    }
  ]
})

Transforming File Content

Use transform to process file content:

const fs = require('fs');

new CopyPlugin({
  patterns: [
    {
      from: "src/config.json",
      to: "config.json",
      transform(content) {
        const config = JSON.parse(content);
        config.buildTime = new Date().toISOString();
        return JSON.stringify(config, null, 2);
      }
    }
  ]
})

Practical Use Cases

Scenario 1: Multi-Environment Configuration

// webpack.prod.js
new CopyPlugin({
  patterns: [
    { 
      from: `src/config/${process.env.NODE_ENV}.json`,
      to: "config.json"
    }
  ]
})

Scenario 2: PWA Applications

new CopyPlugin({
  patterns: [
    { from: "public/manifest.json", to: "" },
    { from: "public/icons", to: "icons" },
    { from: "public/robots.txt", to: "" }
  ]
})

Scenario 3: Electron Applications

new CopyPlugin({
  patterns: [
    { 
      from: "native-modules/*.node",
      to: "node_modules/[name][ext]"
    }
  ]
})

Performance Optimization Tips

1. Narrow the Copy Scope: Precisely specify the files to copy, avoiding overly broad matching patterns.
2. Parallel Processing: Webpack 5 handles copy tasks in parallel by default.
3. Caching: Enable caching in development mode:

new CopyPlugin({
  patterns: [...],
  options: {
    concurrency: 100, // Number of parallel files
    cache: true // Enable caching in development mode
  }
})

Troubleshooting Common Issues

Files Not Copied

Check:

1. Whether the from path is correct (relative to the Webpack configuration file).
2. Whether the files are ignored by .gitignore.
3. Whether there are permission issues.

Hashed Filename Updates

To handle hashed filenames, configure:

new CopyPlugin({
  patterns: [
    {
      from: "src/assets/*.png",
      to: "images/[name].[contenthash:8][ext]"
    }
  ]
})

Conflicts with clean-webpack-plugin

Ensure clean-webpack-plugin does not delete copied files:

const { CleanWebpackPlugin } = require('clean-webpack-plugin');

module.exports = {
  plugins: [
    new CleanWebpackPlugin({
      cleanAfterEveryBuildPatterns: ['!images/**'] // Preserve the images directory
    }),
    new CopyPlugin(...)
  ]
}

Comparison with Other Tools

Webpack 5 Asset Modules Alternative

Webpack 5 introduced asset modules, which can replace the copy plugin for simple scenarios:

module.exports = {
  module: {
    rules: [
      {
        test: /\.(png|svg|txt)$/,
        type: 'asset/resource',
        generator: {
          filename: 'static/[hash][ext][query]'
        }
      }
    ]
  }
}

However, this approach only works for files referenced by JavaScript. For completely independent static files, CopyWebpackPlugin is still required.

Debugging Tips

Enable debug mode in the terminal to view detailed copy processes:

DEBUG=copy-webpack-plugin webpack --mode development

Or add logging to the configuration:

new CopyPlugin({
  patterns: [...],
  options: {
    debug: 'warning' // or 'info', 'debug'
  }
})