Skip to content
This repository was archived by the owner on Sep 7, 2026. It is now read-only.

Commit eaddf25

Browse files
feat: deprecate in favor of webpack's output.copy (#839)
* feat: deprecate in favor of webpack's 'output.copy' webpack copies files itself since 5.111.0. Warns once per process when the compiler running the plugin has 'webpack.CopyPlugin', so a webpack with nothing to migrate to stays quiet, and documents what each option becomes. * chore(deps): bump fast-uri to 3.1.7 Clears four high-severity advisories covering 3.0.0-3.1.5, which turned the lint job's 'npm audit --production' red on every branch once they were published. Transitive through ajv, so only the lockfile moves.
1 parent 08b3a64 commit eaddf25

4 files changed

Lines changed: 184 additions & 3 deletions

File tree

‎README.md‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,72 @@
1616

1717
Copies existing individual files or entire directories to the build directory.
1818

19+
## Deprecated
20+
21+
> [!WARNING]
22+
>
23+
> This plugin is deprecated. webpack copies files itself since **5.111.0**, through the [`output.copy`](https://webpack.js.org/configuration/output/#outputcopy) option and the `webpack.CopyPlugin` behind it, so this package is no longer needed there. It stays published and keeps working, and it remains the answer for webpack 5 releases older than 5.111.0, but new options land in webpack rather than here.
24+
25+
Using a webpack that has it, this is the whole migration:
26+
27+
```diff
28+
- const CopyPlugin = require("copy-webpack-plugin");
29+
-
30+
module.exports = {
31+
- plugins: [
32+
- new CopyPlugin({
33+
- patterns: [{ from: "static", to: "public" }],
34+
- }),
35+
- ],
36+
+ output: {
37+
+ copy: [{ from: "static", to: "public" }],
38+
+ },
39+
};
40+
```
41+
42+
`output.copy` takes the patterns directly — a single string is one of them, so `copy: "static"` is a whole configuration. `concurrency` and the `processAssets` `stage` live on the plugin instead, for the builds that set them:
43+
44+
```js
45+
const { Compilation, CopyPlugin } = require("webpack");
46+
47+
module.exports = {
48+
plugins: [
49+
new CopyPlugin({
50+
patterns: ["static"],
51+
concurrency: 50,
52+
stage: Compilation.PROCESS_ASSETS_STAGE_ADDITIONS,
53+
}),
54+
],
55+
};
56+
```
57+
58+
`stage` decides which asset-processing taps see the copied files. It is not how a file is kept out of the minimizer — that one re-runs for assets added at any later stage, so `info: { minimized: true }` is still the way, exactly as it is here.
59+
60+
A [worked example](https://github.com/webpack/webpack/tree/main/examples/output-copy) covers both forms, the pattern options and that second pass.
61+
62+
### What each option becomes
63+
64+
| This plugin | `output.copy` |
65+
| --------------------- | ---------------------------------------------------------------------------------- |
66+
| `patterns` | `output.copy` itself |
67+
| `from` | `from` |
68+
| `to` | `to`, which may be a function of the copied file |
69+
| `context` | `context` |
70+
| `globOptions` | `globOptions` — `caseSensitive`, `deep`, `dot`, `followSymlinks`, `ignore` |
71+
| `info` | `info` |
72+
| `transform` | `transform` |
73+
| `toType` | read from `to`; use `filename` for a template |
74+
| `filter` | `globOptions.ignore` |
75+
| `noErrorOnMissing` | the default — a pattern matching nothing warns rather than fails |
76+
| `options.concurrency` | `new CopyPlugin({ concurrency })` |
77+
| `priority` | patterns are applied in order, and a later one replaces what an earlier one copied |
78+
| `force` | no equivalent: copying onto an asset the compilation emits is an error |
79+
| `transformAll` | no equivalent — see below |
80+
81+
Three pattern options have no counterpart here, because webpack grew them rather than inheriting them: `filename` (a webpack filename template, so one pattern can rename, flatten and hash), `preservePermissions` and `preserveTimestamps`.
82+
83+
`transformAll` merged several sources into one asset, which `output.copy` deliberately does not do — one source file becomes one asset there, so merging is a second pass over what it emitted. The [example](https://github.com/webpack/webpack/tree/main/examples/output-copy) carries that second pass as a ~30-line plugin, caching included.
84+
1985
## Getting Started
2086

2187
To begin, you'll need to install `copy-webpack-plugin`:

‎package-lock.json‎

Lines changed: 3 additions & 3 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎src/index.js‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -143,6 +143,36 @@ const getTinyGlobby = memoize(() => require("tinyglobby"));
143143

144144
const PLUGIN_NAME = "CopyPlugin";
145145

146+
const DEPRECATION_MESSAGE = `copy-webpack-plugin is deprecated: webpack copies files itself since 5.111.0, through the 'output.copy' option and the 'webpack.CopyPlugin' behind it.
147+
Migration guide: https://github.com/webpack/copy-webpack-plugin#deprecated
148+
Example: https://github.com/webpack/webpack/tree/main/examples/output-copy`;
149+
150+
let deprecationWarned = false;
151+
152+
/**
153+
* Warns once per process that webpack copies files on its own. A webpack too
154+
* old to do it has nothing to migrate to, so it is left alone.
155+
* @param {Compiler} compiler the compiler
156+
* @returns {void}
157+
*/
158+
function warnDeprecated(compiler) {
159+
if (
160+
deprecationWarned ||
161+
!compiler.webpack ||
162+
!("CopyPlugin" in compiler.webpack)
163+
) {
164+
return;
165+
}
166+
167+
deprecationWarned = true;
168+
169+
process.emitWarning(
170+
DEPRECATION_MESSAGE,
171+
"DeprecationWarning",
172+
"DEP_COPY_WEBPACK_PLUGIN",
173+
);
174+
}
175+
146176
class CopyPlugin {
147177
/**
148178
* @param {PluginOptions=} options options for the plugin
@@ -819,6 +849,8 @@ class CopyPlugin {
819849
apply(compiler) {
820850
const pluginName = this.constructor.name;
821851

852+
warnDeprecated(compiler);
853+
822854
compiler.hooks.thisCompilation.tap(pluginName, (compilation) => {
823855
const logger = compilation.getLogger("copy-webpack-plugin");
824856
const cache = compilation.getCache("CopyWebpackPlugin");

‎test/deprecation.test.js‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
import { getCompiler } from "./helpers";
2+
3+
// the flag which makes the warning fire once lives in the module, so each case
4+
// needs its own copy of it
5+
const loadPlugin = () => {
6+
let CopyPlugin;
7+
8+
jest.isolateModules(() => {
9+
CopyPlugin = require("../src").default || require("../src");
10+
});
11+
12+
return CopyPlugin;
13+
};
14+
15+
// only `Compilation` and `CopyPlugin` are read from it, and building it by
16+
// hand keeps webpack's own deprecated getters out of the output
17+
const namespace = (extra) => ({
18+
Compilation: require("webpack").Compilation,
19+
...extra,
20+
});
21+
22+
const applyTo = (webpackNamespace) => {
23+
const CopyPlugin = loadPlugin();
24+
const compiler = getCompiler();
25+
26+
compiler.webpack = webpackNamespace;
27+
28+
new CopyPlugin({ patterns: ["directory"] }).apply(compiler);
29+
30+
return compiler;
31+
};
32+
33+
describe("deprecation", () => {
34+
let emitWarning;
35+
36+
beforeEach(() => {
37+
emitWarning = jest.spyOn(process, "emitWarning").mockImplementation();
38+
});
39+
40+
afterEach(() => {
41+
emitWarning.mockRestore();
42+
});
43+
44+
it("should warn when webpack copies files itself", () => {
45+
applyTo(namespace({ CopyPlugin: class {} }));
46+
47+
expect(emitWarning).toHaveBeenCalledTimes(1);
48+
49+
const [[message, type, code]] = emitWarning.mock.calls;
50+
51+
expect(message).toMatch("copy-webpack-plugin is deprecated");
52+
expect(message).toMatch("5.111.0");
53+
expect(message).toMatch("output.copy");
54+
expect(type).toBe("DeprecationWarning");
55+
expect(code).toBe("DEP_COPY_WEBPACK_PLUGIN");
56+
});
57+
58+
it("should warn once for several compilers", () => {
59+
const CopyPlugin = loadPlugin();
60+
const webpackNamespace = namespace({ CopyPlugin: class {} });
61+
62+
for (const _ of [0, 1, 2]) {
63+
const compiler = getCompiler();
64+
65+
compiler.webpack = webpackNamespace;
66+
new CopyPlugin({ patterns: ["directory"] }).apply(compiler);
67+
}
68+
69+
expect(emitWarning).toHaveBeenCalledTimes(1);
70+
});
71+
72+
it("should not warn when webpack cannot copy files itself", () => {
73+
applyTo(namespace());
74+
75+
expect(emitWarning).not.toHaveBeenCalled();
76+
});
77+
78+
it("should not warn when the compiler has no webpack namespace", () => {
79+
applyTo(undefined);
80+
81+
expect(emitWarning).not.toHaveBeenCalled();
82+
});
83+
});

0 commit comments

Comments
 (0)