├── .github
    └── FUNDING.yml
├── LICENSE
├── MIGRATION GUIDE.md
├── README.md
└── guides
    ├── module-federation.md
    └── persistent-caching.md


/.github/FUNDING.yml:
--------------------------------------------------------------------------------
1 | # These are supported funding model platforms
2 | 
3 | github: sokra
4 | open_collective: webpack
5 | 


--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
 1 | MIT License
 2 | 
 3 | Copyright (c) 2018 webpack
 4 | 
 5 | Permission is hereby granted, free of charge, to any person obtaining a copy
 6 | of this software and associated documentation files (the "Software"), to deal
 7 | in the Software without restriction, including without limitation the rights
 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 | 
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 | 
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 | 


--------------------------------------------------------------------------------
/MIGRATION GUIDE.md:
--------------------------------------------------------------------------------
  1 | [Help by editing this file](https://github.com/webpack/changelog-v5/edit/master/MIGRATION%20GUIDE.md).
  2 | 
  3 | This guide should help you migrating to webpack 5 when **using webpack directly**. If you are using some higher-level tool to run webpack, please refer to the guide on migrating to webpack 5 for the tool you are using.
  4 | 
  5 | # Preparations
  6 | 
  7 | ## Upgrade your Node.js version
  8 | 
  9 | webpack requires at least 10.13.0, but using Node.js 12 or 14 is recommended.
 10 | 
 11 | Newer Node.js version will improve build performance a lot.
 12 | 
 13 | ## Upgrade to latest webpack 4 version
 14 | 
 15 | When using webpack < 4 consult the webpack 4 migration guide.
 16 | 
 17 | When using webpack >= 4, this should be possible without problems.
 18 | 
 19 | ## Upgrade to latest webpack-cli version (when used)
 20 | 
 21 | ## Upgrade all plugins and loaders to the latest version
 22 | 
 23 | Some plugins have a beta version that needs to be used for webpack 5 compatibility. Use them.
 24 | 
 25 | Check migration guide when upgrading plugins across the major version.
 26 | 
 27 | ## Make sure your build has no errors or warnings
 28 | 
 29 | There might be new errors or warnings because of the upgraded versions of webpack, cli, plugins and loaders.
 30 | 
 31 | ## Check for deprecation warnings during build
 32 | 
 33 | You can invoke webpack this way
 34 | 
 35 | ``` sh
 36 | node --trace-deprecation node_modules/webpack/bin/webpack.js ...
 37 | ```
 38 | 
 39 | to get stack traces for deprecation warnings to figure out which plugins are responsible.
 40 | 
 41 | webpack 5 removes all deprecated features. You must have no webpack deprecation warning to be able to upgrade.
 42 | 
 43 | ## Make sure you are using entrypoint information from stats
 44 | 
 45 | When using html-webpack-plugin you are fine.
 46 | 
 47 | When using static html or creating HTML in some other way, make sure you use `entrypoints` from stats json to generate `<script>`, `<style>` and `<link>` tags.
 48 | 
 49 | If this is not possible avoid setting `splitChunks.chunks: "all"` and `splitChunks.maxSize` later in this guide. Note that this is sub-optimal.
 50 | 
 51 | ## Make sure to use `mode`
 52 | 
 53 | Set `mode` correctly to either `mode: "production"` or `mode: "development"`.
 54 | 
 55 | This will make sure you get the correct defaults.
 56 | 
 57 | ## Update outdated options
 58 | 
 59 | Update the following options to their new version:
 60 | 
 61 | * `optimization.hashedModuleIds: true` -> `optimization.moduleIds: "hashed"`
 62 | * `optimization.namedChunks: true` -> `optimization.chunkIds: "named"`
 63 | * `optimization.namedModules: true` -> `optimization.moduleIds: "named"`
 64 | * `NamedModulesPlugin` -> `optimization.moduleIds: "named"`
 65 | * `NamedChunksPlugin` -> `optimization.chunkIds: "named"`
 66 | * `HashedModulesPlugin` -> `optimization.moduleIds: "hashed"`
 67 | * `optimization.occurrenceOrder: true` -> `optimization: { chunkIds: "total-size", moduleIds: "size" }`
 68 | 
 69 | # Test webpack 5 compatibility
 70 | 
 71 | Try to set the following options in your webpack 4 builds and check if it still works correctly.
 72 | 
 73 | * `node.Buffer: false`
 74 | * `node.process: false`
 75 | 
 76 | Note: webpack 5 removes these options and will always use `false`.
 77 | You have to remove these options again when upgrading to webpack 5.
 78 | 
 79 | # Upgrade webpack version
 80 | 
 81 | Run `yarn add webpack@next -D` resp. `npm install webpack@next --dev`.
 82 | 
 83 | # Cleanup configuration
 84 | 
 85 | * Consider removing `optimization.moduleIds` and `optimization.chunkIds`. The defaults are probably perfect. They support Long Term Caching (in production) and debugging (in development)
 86 | * Reconsider `optimization.splitChunks`.
 87 |   * It's recommended to use either the defaults or `optimization.splitChunks: { chunks: "all" }`
 88 |   * When really using a custom configuration replace `name` with `idHint`.
 89 |   * When used to disable the defaults with `default: false, vendors: false`: Consider not doing this, but if you really want to `default: false, defaultVendors: false`.
 90 | * When using the `WatchIgnorePlugin`, use `watchOptions.ignore` instead.
 91 | * When using `[hash]`: Consider changing to `[contenthash]` (not the same, but better)
 92 | * Using WASM: Set `experiments.syncWebAssembly: true` (after migration to webpack 5, migrate to `experiments: { asyncWebAssembly: true, importAsync: true }` instead)
 93 | * Using `entry: "./src/index.js`: you can omit it, that's the default
 94 | * Using `output.path: path.resolve(__dirname, "dist")`: you can omit it, that's the default
 95 | * Using `output.filename: "[name].js"`: you can omit it, that's the default
 96 | * Using Yarn PnP and the pnp-resolver-plugin: you must omit it, that's supported by default now.
 97 | * Using `IgnorePlugin` with a regular expression as argument: It takes an options object now: `new IgnorePlugin({ resourceRegExp: /regExp/ })`.
 98 | * Need to support an older browser? Add version to `target` options
 99 |   * By default, Webpack's runtime code uses ES2015 syntax to build smaller bundles.
100 |   * If your build targets environments that don't support this syntax (like IE11), you'll need to add `"es5"` to the `target` option, e. g. `target: ["web", "es5"]`.
101 |   * For Node.js builds include the supported node.js in the `target` option and webpack automatically figure out which syntax is supported, e. g. `target: "node8.6"`.
102 | 
103 | # Cleanup code
104 | 
105 | * Using `/* webpackChunkName: "..." */`: Make sure to understand the intention.
106 |   * The name here is intended to be public visible.
107 |   * It's not a development-only name
108 |   * webpack will use it to name files in production and development mode
109 |   * webpack 5 will automatically assign useful file names in development even when not using `webpackChunkName`
110 | * Using named exports from JSON modules: This is not supported by the (new) spec and you will get a warning
111 |   * Instead of `import { version } from "./package.json"; console.log(version);` use `import package from "./package.json"; console.log(package.version);`
112 | 
113 | # Cleanup build code
114 | 
115 | * Using `const compiler = webpack(...);`: Make sure to close the compiler after use
116 |   * `compiler.close(callback)`
117 |   * This doesn't apply to the `webpack(..., callback)` form.
118 |   * This is optional if you use webpack in watching mode until the user ends the process.
119 | 
120 | # Run a single build and follow advises
121 | 
122 | Please make sure to read errors/warnings carefully.
123 | 
124 | There is no advise? Please create an issue and we will add one.
125 | 
126 | Repeat this step until you solved at least level 3. Best continue to solve level 4:
127 | 
128 | ## Level 1: Schema validation fails
129 | 
130 | Some configuration options have changed. There should be a validation error with a `BREAKING CHANGE:` note, or a hint which option should be used instead.
131 | 
132 | ## Level 2: webpack crashes with error
133 | 
134 | The error message should tell you what needs to be changed.
135 | 
136 | ## Level 3: Build Errors
137 | 
138 | The error message should have a `BREAKING CHANGE:` note.
139 | 
140 | ## Level 4: Build Warnings
141 | 
142 | The warning message should tell you what can be improved.
143 | 
144 | There might be some cases where you don't have direct control over the code, like when using packages from NPM.
145 | There the new `ignoreWarnings` configuration option might become handy to temporary hide the warnings, e. g.
146 | 
147 | ``` js
148 | ignoreWarnings: [
149 |   { module: /node_modules/, message: /only default export is available soon/ }
150 | ]
151 | ```
152 | 
153 | ## Level 5: Runtime errors
154 | 
155 | This is tricky. You probably have to debug to find the problem. A general advise is difficult here.
156 | 
157 | Here are some common things:
158 | 
159 | * `process` is not defined.
160 |   * Webpack 5 do no longer include a polyfill for this Node.js variable. Avoid using it in frontend code.
161 |   * Want to support frontend and browser usage? Use the `exports` or `imports` package.json field to use different code depending on environment.
162 |     * To support older bundlers use the `browser` field too.
163 |     * Alternative: Wrap code blocks with `typeof process` checks. Note that this is worse regarding bundle size.
164 |   * Want to use environment variables with `process.env.VARIABLE`? You need to use the `DefinePlugin` or `EnvironmentPlugin` to define these variables in the configuration.
165 |     * Consider using `VARIABLE` instead and make sure to check `typeof VARIABLE !== "undefined"` too. `process.env` is Node.js specific and should be avoided in frontend code.
166 | 
167 | ## Level 6: Deprecation warnings
168 | 
169 | You probably get a lot of deprecation warnings.
170 | This is not directly a problem.
171 | Plugins need time to catch up with core changes.
172 | Please report these deprecations to the plugins.
173 | These deprecations are only warnings and the build will still work with only minor drawbacks (like less performance).
174 | 
175 | You can hide deprecation warnings with
176 | 
177 | ``` sh
178 | node --no-deprecation node_modules/webpack/bin/webpack.js ...
179 | ```
180 | 
181 | but this should only be a temporary workaround.
182 | 
183 | Contributors to plugins can follow the advises in the deprecation messages.
184 | 
185 | ## Level 7: Performance issues
186 | 
187 | Usually performance should improve with webpack 5, but there are also a few cases where performance get worse.
188 | 
189 | * Profile where the time is spend.
190 |   * `--profile --progress` displays a very simple performance profile now
191 |   * `node --inspect-brk node_modules/webpack/bin/webpack.js` + [`chrome://inspect`](chrome://inspect) / [`edge://inspect`](edge://inspect) (see profiler tab).
192 |     * You can save these profiles to files and provide them in issues.
193 |     * Add `--no-turbo-inlining` for better stack traces in some cases
194 | * Time for building modules in incremental builds can be improved by reverting to unsafe caching like in webpack 4:
195 |   * `module.unsafeCache: true`
196 |   * But this might affect the ability to handle some of the changes to the code base
197 | * Full build
198 |   * Backward-compat layer for deprecated things usually have worse performance compared to the new thing.
199 |   * Creating many warnings can affect build performance, even if they are ignored.
200 |   * Source Maps are expensive. Check `devtool` option in documentation to see a comparison of the different options.
201 |   * Anti-Virus-Protection might affect performance of file system access.
202 |   * Persistent Caching can help to improve repeated full builds.
203 |   * Module Federation allows to split the application into multiple smaller builds.
204 | 
205 | # Everything working?
206 | 
207 | Tweet that you successfully migrated to webpack 5.
208 | 
209 | # Not working?
210 | 
211 | Create an issue and tell us about your problems.
212 | 
213 | # Something missing in this guide?
214 | 
215 | Please send a PR to help the next person using this guide:
216 | 
217 | [Click here to edit this file](https://github.com/webpack/changelog-v5/edit/master/MIGRATION%20GUIDE.md).
218 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
   1 | [Help by editing this file](https://github.com/webpack/changelog-v5/edit/master/README.md).
   2 | 
   3 | # General direction
   4 | 
   5 | This release focus on the following:
   6 | 
   7 | - We try to improve build performance with Persistent Caching.
   8 | - We try to improve Long Term Caching with better algorithms and defaults.
   9 | - We try to improve bundle size with better Tree Shaking and Code Generation.
  10 | - We try to improve compatiblity to the web platform.
  11 | - We try to clean up internal structures that were left in a weird state while implementing features in v4 without introducing any breaking changes.
  12 | - We try to prepare for future features by introducing breaking changes now, allowing us to stay on v5 for as long as possible.
  13 | 
  14 | # Migration Guide
  15 | 
  16 | => [see here for a migration guide](https://github.com/webpack/changelog-v5/blob/master/MIGRATION%20GUIDE.md) <=
  17 | 
  18 | # Major Changes: Removals
  19 | 
  20 | ## Removed Deprecated Items
  21 | 
  22 | All items deprecated in v4 were removed.
  23 | 
  24 | MIGRATION: Make sure that your webpack 4 build does not print deprecation warnings.
  25 | 
  26 | Here are a few things that were removed but did not have deprecation warnings in v4:
  27 | 
  28 | - IgnorePlugin and BannerPlugin must now be passed only one argument that can be an object, string or function.
  29 | 
  30 | ## Deprecation codes
  31 | 
  32 | New deprecations include a deprecation code so they are easier to reference.
  33 | 
  34 | ## Syntax deprecated
  35 | 
  36 | `require.include` has been deprecated and will emit a warning by default when used.
  37 | 
  38 | Behavior can be changed with `Rule.parser.requireInclude` to allowed, deprecated or disabled.
  39 | 
  40 | ## Automatic Node.js Polyfills Removed
  41 | 
  42 | In the early days, webpack's aim was to allow running most node.js modules in the browser, but the module landscape changed and many module uses are now written mainly for frontend purposes. webpack <= 4 ships with polyfills for many of the node.js core modules, which are automatically applied once a module uses any of the core modules (i.e. the `crypto` module).
  43 | 
  44 | While this makes using modules written for node.js easy, it adds these huge polyfills to the bundle. In many cases these polyfills are unnecessary.
  45 | 
  46 | webpack 5 stops automatically polyfilling these core modules and focus on frontend-compatible modules.
  47 | 
  48 | MIGRATION:
  49 | 
  50 | - Try to use frontend-compatible modules whenever possible.
  51 | - It's possible to manually add a polyfill for a node.js core module. An error message will give a hint on how to achieve that.
  52 | - Package authors: Use the `browser` field in `package.json` to make a package frontend-compatible. Provide alternative implementations/dependencies for the browser.
  53 | 
  54 | # Major Changes: Long Term Caching
  55 | 
  56 | ## Deterministic Chunk, Module IDs and Export names
  57 | 
  58 | New algorithms were added for long term caching. These are enabled by default in production mode.
  59 | 
  60 | `chunkIds: "deterministic", moduleIds: "deterministic", mangleExports: "deterministic"`
  61 | 
  62 | The algorithms assign short (3 or 4 characters) numeric IDs to modules and chunks and short (2 characters) names to exports in a deterministic way.
  63 | This is a trade-off between bundle size and long term caching.
  64 | 
  65 | `moduleIds/chunkIds/mangleExports: false` disables the default behavior and one can provide a custom algorithm via plugin. Note that in webpack 4 `moduleIds/chunkIds: false` without custom plugin resulted in a working build, while in webpack 5 you must provide a custom plugin.
  66 | 
  67 | MIGRATION: Best use the default values for `chunkIds`, `moduleIds` and `mangleExports`. You can also opt-in to the old defaults `chunkIds: "size", moduleIds: "size", mangleExports: "size"`, this will generate smaller bundles, but invalidate them more often for caching.
  68 | 
  69 | Note: In webpack 4 hashed module ids yielded reduced gzip performance. This was related to changed module order and has been fixed.
  70 | 
  71 | Note: In webpack 5, `deterministic` Ids are enabled by default in production mode
  72 | 
  73 | ## Real Content Hash
  74 | 
  75 | Webpack 5 will use a real hash of the file content when using `[contenthash]` now. Before it "only" used a hash of the internal structure.
  76 | This can be positive impact on long term caching when only comments are changed or variables are renamed. These changes are not visible after minimizing.
  77 | 
  78 | # Major Changes: Development Support
  79 | 
  80 | ## Named Chunk IDs
  81 | 
  82 | A new named chunk id algorithm enabled by default in development mode gives chunks (and filenames) human-readable names.
  83 | A Module ID is determined by its path, relative to the `context`.
  84 | A Chunk ID is determined by the chunk's content.
  85 | 
  86 | So you no longer need to use `import(/* webpackChunkName: "name" */ "module")` for debugging.
  87 | But it would still make sense if you want to control the filenames for production environments.
  88 | 
  89 | It's possible to use `chunkIds: "named"` in production, but make sure not to accidentally expose sensitive information about module names.
  90 | 
  91 | MIGRATION: If you dislike the filenames being changed in development, you can pass `chunkIds: "natural"` to use the old numeric mode.
  92 | 
  93 | ## Module Federation
  94 | 
  95 | Webpack 5 adds a new feature called "Module Federation", which allows multiple webpack builds to work together.
  96 | From runtime perspective modules form multiple builds will behave like a huge connected module graph.
  97 | From developer persepective modules can be imported from specified remote builds and used with minimal restrictions.
  98 | 
  99 | For more details see [this separate guide](https://github.com/webpack/changelog-v5/blob/master/guides/module-federation.md).
 100 | 
 101 | # Major Changes: New Web Platform Features
 102 | 
 103 | ## JSON modules
 104 | 
 105 | JSON modules now align with the spec and emit a warning when using a non-default export.
 106 | JSON modules no longer have named exports when importing from a strict EcmaScript module.
 107 | 
 108 | MIGRATION: Use the default export.
 109 | 
 110 | Unused properties are dropped by the `optimization.usedExports` optimization and properties are mangled by the `optimization.mangleExports` optimization.
 111 | 
 112 | It's possible to specify a custom JSON parser in `Rule.parser.parse` to import JSON-like files (e. g. for toml, yaml, json5, etc.).
 113 | 
 114 | ## Asset modules
 115 | 
 116 | Webpack 5 has now native support for modules representing assets.
 117 | These modules will either emit a file into the output folder or inject a DataUri into the javascript bundle.
 118 | Either way they give a URL to work with.
 119 | 
 120 | They can be used via multiple ways:
 121 | 
 122 | - `import url from "./image.png"` and settings `type: "asset"` in `module.rules` when matching such import.
 123 | - `new URL("./image.png", import.meta.url)`
 124 | 
 125 | The syntax is chosen to allow running code without bundler too.
 126 | 
 127 | ## import.meta
 128 | 
 129 | - `import.meta.webpackHot` is an alias for `module.hot` which is also available in strict ESM
 130 | - `import.meta.webpack` is the webpack major version as number
 131 | - `import.meta.url` is the `file:` url of the current file (similar to `__filename` but as file url)
 132 | 
 133 | ## Native Worker support
 134 | 
 135 | When combining `new URL` for assets with `new Worker`/`new SharedWorker`/`navigator.serviceWorker.register` webpack will automatically create a new entrypoint for a web worker.
 136 | 
 137 | `new Worker(new URL("./worker.js", import.meta.url))`
 138 | 
 139 | The syntax is chosen to allow running code without bundler too.
 140 | 
 141 | ## Uris
 142 | 
 143 | Webpack 5 support handling of protocols in request.
 144 | 
 145 | - `data:` is supported. Base64 or raw encoding is supported. Mimetype can be mapped to loaders and module type in `module.rules`. Example: `import x from "data:text/javascript,export default 42"`
 146 | - `file:` is supported.
 147 | - `http(s):` is supported, but requires opt-in via `new webpack.experiments.schemesHttp(s)UriPlugin()`
 148 | 
 149 | Fragments in requests are supported: Example: `./file.js#fragment`
 150 | 
 151 | ## Async modules
 152 | 
 153 | Webpack 5 supports so called "async modules".
 154 | That are modules that do not evaluate synchronously, but are async and Promise-based instead.
 155 | 
 156 | Importing them via `import` is automatically handled and no additional syntax is needed and difference is hardly notice-able.
 157 | 
 158 | Importing them via `require()` will return a Promise that resolves to the exports.
 159 | 
 160 | In webpack there are multiple ways to have async modules:
 161 | 
 162 | - async externals
 163 | - WebAssembly Modules in the new spec
 164 | - EcmaScript Modules that are using Top-Level-Await
 165 | 
 166 | ## Externals
 167 | 
 168 | Webpack 5 adds additional external types to cover more applications:
 169 | 
 170 | `promise`: An expression that evaluates to a Promise. The external module is an async module and the resolved value is used as module exports.
 171 | 
 172 | `import`: Native `import()` is used to load the specified request. The external module is an async module.
 173 | 
 174 | `script`: Loads a url via `<script>` tag and gets the exports from a global variable (and optionally properties of it). The external module is an async module.
 175 | 
 176 | # Major Changes: New Node.js Ecosystem Features
 177 | 
 178 | ## Resolving
 179 | 
 180 | The `exports` and `imports` field in package.json is now supported.
 181 | 
 182 | Yarn PnP is supported natively.
 183 | 
 184 | See more details in TODO.
 185 | 
 186 | # Major Changes: Development Experience
 187 | 
 188 | ## Improved target
 189 | 
 190 | Webpack 5 allows to pass a list of targets and also support versions of target.
 191 | 
 192 | Examples: `target: "node14"` `target: ["web", "es2020"]`
 193 | 
 194 | This is a simple way to provide webpack all the information it needs to determine:
 195 | - chunk loading mechnism, and
 196 | - supported syntax like arrow functions
 197 | 
 198 | ## Stats
 199 | 
 200 | The Stats test format has been improve regarding readablility and verbosity. The defaults has been improved to be less verbose and also suitable for large builds.
 201 | 
 202 | * Chunk relations are hidden by default now. This can be toggled with `stats.chunkRelations`.
 203 | * Stats differentiate between `files` and `auxiliaryFiles` now.
 204 | * Stats hide module and chunk ids by default now. This can be toggled with `stats.ids`.
 205 | * The list of all modules is sorted by distance to entrypoint now. This can be changed with `stats.modulesSort`.
 206 | * The list of chunk modules is sorted by module name now. This can be changed with `stats.chunkModulesSort`.
 207 | * The list of nested modules in concatenated modules is sorted topologically now. This can be changed with `stats.nestedModulesSort`.
 208 | * Chunks and Assets show chunk id hints now.
 209 | * Assets and modules will display in a tree instead of a list/table.
 210 | * General information is shown in a summary at the end now. It shows webpack version, config name and warnings/errors count.
 211 | * Hash is hidden by default now. This can be changed with `stats.hash`.
 212 | * Timestamp of build is no longer shown by default. This can be enabled with `stats.builtAt`. It will show the timestamp in the summary.
 213 | * Child compilations will no longer shown by default. They can be displayed with `stats.children`.
 214 | 
 215 | ## Progress
 216 | 
 217 | A few improvements have been done to the `ProgressPlugin` which is used for `--progress` by the CLI, but can also be used manually as plugin.
 218 | 
 219 | It used to only count the processed modules. Now it can count `entries` `dependencies` and `modules`.
 220 | All of them are shown by default now.
 221 | 
 222 | It used to display the currently processed module. This caused much stderr output and yielded a performance problem on some consoles.
 223 | This is now disabled by default (`activeModules` option). This also reduces the amount of spam on the console. 
 224 | Now writing to stderr during building modules is throttled to 500ms.
 225 | 
 226 | The profiling mode also got an upgrade and will display timings of nested progress messages.
 227 | This makes it easier to figure out while plugin is causing performance problems.
 228 | 
 229 | A newly added `percentBy`-option tells `ProgressPlugin` how to calculate progress percentage.
 230 | 
 231 | ```js
 232 | new webpack.ProgressPlugin({ percentBy: "entries" });
 233 | ```
 234 | 
 235 | To make progress percentage more accurate `ProgressPlugin` caches the last known total modules count and reuses this value on the next build. The first build will warm the cache but the following builds will use and update this value.
 236 | 
 237 | ## Automatic unique naming
 238 | 
 239 | In webpack 4 multiple webpack runtimes could conflict on the same page, because they use the same global variable for chunk loading. To fix that it was needed to provide a custom name to the `output.jsonpFunction` configuration.
 240 | 
 241 | Webpack 5 does automatically infer a unique name for the build from `package.json` `name` and uses this as default for `output.uniqueName`.
 242 | 
 243 | This value is used to make all potentical conflicting globals unique.
 244 | 
 245 | MIGRATION: Consider removing `output.jsonpFunction`.
 246 | 
 247 | ## Automatic public path
 248 | 
 249 | Webpack 5 will determine the `output.publicPath` automatically when possible.
 250 | 
 251 | ## Typescript typings
 252 | 
 253 | Webpack 5 generates typescript typings from source code and exposes them via the npm package.
 254 | 
 255 | MIGRATION: Remove `@types/webpack`. Update references when names differ.
 256 | 
 257 | # Major Changes: Optimization
 258 | 
 259 | ## Nested tree-shaking
 260 | 
 261 | webpack is now able to track access to nested properties of exports. This can improve Tree Shaking (Unused export elimination and export mangling) when reexporting namespace objects.
 262 | 
 263 | ``` js
 264 | // inner.js
 265 | export const a = 1;
 266 | export const b = 2;
 267 | 
 268 | // module.js
 269 | import * as inner from "./inner";
 270 | export { inner }
 271 | 
 272 | // user.js
 273 | import * as module from "./module";
 274 | console.log(module.inner.a);
 275 | ```
 276 | 
 277 | In this example, the export `b` can be removed in production mode.
 278 | 
 279 | ## Inner-module tree-shaking
 280 | 
 281 | webpack 4 didn't analyze dependencies between exports and imports of a module. webpack 5 has a new option `optimization.innerGraph`, which is enabled by default in production mode, that runs an analysis on symbols in a module to figure out dependencies from exports to imports.
 282 | 
 283 | In a module like this:
 284 | 
 285 | ``` js
 286 | import { something } from "./something";
 287 | 
 288 | function usingSomething() {
 289 |   return something;
 290 | }
 291 | 
 292 | export function test() {
 293 |   return usingSomething();
 294 | }
 295 | ```
 296 | 
 297 | The inner graph algorithm will figure out that `something` is only used when the `test` export is used. This allows to flag more exports as unused and to omit more code from the bundle.
 298 | 
 299 | When `"sideEffects": false` is set, this allows to omit even more modules. In this example `./something` will be omitted when the `test` export is unused.
 300 | 
 301 | To get the information about unused exports `optimization.unusedExports` is required. To remove side-effect-free modules `optimization.sideEffects` is required.
 302 | 
 303 | The following symbols can be analysed:
 304 | * function declarations
 305 | * class declarations
 306 | * `export default` with or variable declarations with
 307 |   * function expressions
 308 |   * class expressions
 309 |   * sequence expressions
 310 |   * `/*#__PURE__*/` expressions
 311 |   * local variables
 312 |   * imported bindings
 313 | 
 314 | FEEDBACK: If you find something missing in this analysis, please report an issue and we consider adding it.
 315 | 
 316 | Using `eval()` will bail-out this optimization for a module, because evaled code could reference any symbol in scope.
 317 | 
 318 | This optimization is also known as Deep Scope Analysis.
 319 | 
 320 | ## CommonJs Tree Shaking
 321 | 
 322 | webpack used to opt-out from used exports analysing for CommonJs exports and `require()` calls.
 323 | 
 324 | webpack 5 adds support for some CommonJs constructs, allows to eliminate unused CommonJs exports and track referenced export names from `require()` calls.
 325 | 
 326 | The following constructs are supported:
 327 | 
 328 | - `exports|this|module.exports.xxx = ...`
 329 | - `exports|this|module.exports = require("...")` (reexport)
 330 | - `exports|this|module.exports.xxx = require("...").xxx` (reexport)
 331 | - `Object.defineProperty(exports|this|module.exports, "xxx", ...)`
 332 | - `require("abc").xxx`
 333 | - `require("abc").xxx()`
 334 | - importing from ESM
 335 | - `require()` a ESM
 336 | - flagged exportType (special handling for non-strict ESM import):
 337 |   - `Object.defineProperty(exports|this|module.exports, "__esModule", { value: true|!0 })`
 338 |   - `exports|this|module.exports.__esModule = true|!0`
 339 | 
 340 | When detecting not analysable code, webpack bails out and doesn't track export information at all for these modules (for performance reasons).
 341 | 
 342 | ## Optimization per runtime
 343 | 
 344 | Webpack 5 is now able (and does by default) to analyse and optimize modules per runtime (A runtime is often equal to an entrypoint).
 345 | This allows to only exports in these entrypoints where they are really needed.
 346 | Entrypoints doesn't affect each other (as long as using a runtime per entrypoint)
 347 | 
 348 | ## Module Concatenation
 349 | 
 350 | Module Concatenation also works per runtime to allow different concatenation for each runtime.
 351 | 
 352 | Module Concatenation has become a first class citizen and any module and dependency is now allowed to implement it.
 353 | Initially webpack 5 already added support for ExternalModules and json modules, more will likely ship soonish.
 354 | 
 355 | ## General Tree Shaking improvements
 356 | 
 357 | `export *` has been improved to track more info and do no longer flag the `default` export as used.
 358 | 
 359 | `export *` will now show warnings when webpack is sure that there are conflicting exports.
 360 | 
 361 | `import()` allows to manually tree shake the module via `/* webpackExports: ["abc", "default"] */` magic comment.
 362 | 
 363 | ## Development Production Similarity
 364 | 
 365 | We try to find a good trade-off between build performance in development mode and avoiding production-only problems by improving the similarity between both modes.
 366 | 
 367 | Webpack 5 enables the `sideEffects` optimization by default in both modes. In webpack 4 this optimization lead to some production-only errors because of an incorrect `"sideEffects"` flag in package.json. Enabling this optimization in development allows to find these problems faster and easier.
 368 | 
 369 | In many cases development and production happen on different OS with different case-sensitivity of filesystem, so webpack 5 adds a few more warnings/errors when there is something weird casing-wise.
 370 | 
 371 | ## Improved Code Generation
 372 | 
 373 | There are now options in `output.environment` now.
 374 | They allows specifying which EcmaScript feature can be used for runtime code generated by webpack.
 375 | 
 376 | One usually do not specify this option directly, but would use the `target` option instead.
 377 | 
 378 | webpack 4 used to only emit ES5 code. 
 379 | webpack 5 can generate both ES5 and ES6/ES2015 code now. 
 380 | 
 381 | Supporting only modern browsers will generate shorter code using arrow functions and more spec-comform code using `const` declarations with TDZ for `export default`.
 382 | 
 383 | ## Improved `target` option
 384 | 
 385 | In webpack 4 the `target` was a very rough choice between `"web"` and `"node"` (and a few others).
 386 | Webpack 5 gives you more options here.
 387 | 
 388 | The `target` option now influences more things about the generated code than before:
 389 | 
 390 | * method of chunk loading
 391 | * format of chunks
 392 | * method of wasm loading
 393 | * method of chunk and wasm loading in workers
 394 | * global object used
 395 | * if publicPath should be determined automatically
 396 | * EcmaScript features/syntax used in the generated code
 397 | * `externals` enabled by default
 398 | * Behavior of some node.js compat layers (`global`, `__filename`, `__dirname`)
 399 | * Resolving of modules (`browser` field, `exports` and `imports` conditions)
 400 | * Some loaders might change behavior based on that
 401 | 
 402 | For some of these things the choice between `"web"` and `"node"` is too rough and we need more information.
 403 | Therefore we allow to specify the minimum version e. g. like `"node10.13"` and infer more properties about the target environment.
 404 | 
 405 | It's now also allowed to combined multiple targets with an array and webpack will determine the minimum properties of all targets. Using an array is also useful when using targets that doesn't give full information like `"web"` or `"node"` (without version number). E. g. `["web", "es2020"]` combines these two partial targets.
 406 | 
 407 | There is a target `"browserslist"` which will use browserslist data to determine properties of the environment.
 408 | This target is also used by default when there is a browserslist config available in the project. When none such config is available, the `"web"` target will be used by default.
 409 | 
 410 | Some combinations and features are not yet implemented and will result in errors. They are preparations for future features. Examples:
 411 | 
 412 | * `["web", "node"]` will lead to an universal chunk loading method, which is not implemented yet
 413 | * `["web", "node"]` + `output.module: true` will lead to a module chunk loading method, which is not implemented yet
 414 | * `"web"` will lead to `http(s):` imports being treated as `module` externals, which are not implemented yet (Workaround: `externalsPresets: { web: false, webAsync: true }`, which will use `import()` instead).
 415 | 
 416 | 
 417 | ## SplitChunks and Module Sizes
 418 | 
 419 | Modules now express size in a better way than displaying a single number. Also, there are now different types of sizes.
 420 | 
 421 | The SplitChunksPlugin now knows how to handle these different sizes and uses them for `minSize` and `maxSize`.
 422 | By default, only `javascript` size is handled, but you can now pass multiple values to manage them:
 423 | 
 424 | ```js
 425 | minSize: {
 426 |   javascript: 30000,
 427 |   style: 50000,
 428 | }
 429 | ```
 430 | 
 431 | MIGRATION: Check which types of sizes are used in your build and configure these in `splitChunks.minSize` and optionally in `splitChunks.maxSize`.
 432 | 
 433 | # Major Changes: Performance
 434 | 
 435 | ## Persistent Caching
 436 | 
 437 | There is now a filesystem cache. It's opt-in and can be enabled with the following configuration:
 438 | 
 439 | ``` js
 440 | cache: {
 441 |   // 1. Set cache type to filesystem
 442 |   type: "filesystem",
 443 |   
 444 |   buildDependencies: {
 445 |     // 2. Add your config as buildDependency to get cache invalidation on config change
 446 |     config: [__filename]
 447 |   
 448 |     // 3. If you have other things the build depends on you can add them here
 449 |     // Note that webpack, loaders and all modules referenced from your config are automatically added
 450 |   }
 451 | }
 452 | ```
 453 | 
 454 | Important notes:
 455 | 
 456 | By default, webpack assumes that the `node_modules` directory, which webpack is inside of, is **only** modified by a package manager. Hashing and timestamping is skipped for `node_modules`. Instead, only the package name and version is used for performance reasons. Symlinks (i. e. `npm/yarn link`) are fine. Do not edit files in `node_modules` directly unless you opt-out of this optimization with `snapshot.managedPaths: []`. When using Yarn PnP webpack assumes that the yarn cache is immutable (which it usually is). You can opt-out of this optimization with `snapshot.immutablePaths: []`
 457 | 
 458 | The cache will be stored into `node_modules/.cache/webpack` (when using node_modules) resp. `.yarn/.cache/webpack` (when using Yarn PnP) by default. You probably never have to delete it manually.
 459 | 
 460 | Many internal plugins will use the Persistent Cache too. Examples: `SourceMapDevToolPlugin` (to cache the SourceMap generation), `ProgressPlugin` (to cache the number of modules)
 461 | 
 462 | The Persistent Cache will automatically create multiple cache files depending on usage to optimize read and write access to and from the cache.
 463 | 
 464 | ### Compiler Idle and Close
 465 | 
 466 | Compilers now need to be closed after being used. Compilers now enter and leave the idle state and have hooks for these states. Plugins may use these hooks to do unimportant work. (i. e. the Persistent cache slowly stores the cache to disk). On compiler close - All remaining work should be finished as fast as possible. A callback signals the closing as done.
 467 | 
 468 | Plugins and their respective authors should expect that some users may forget to close the Compiler. So, all work should eventually be finishing while in idle too. Processes should be prevented from exiting when the work is being done.
 469 | 
 470 | The `webpack()` facade automatically calls `close` when being passed a callback.
 471 | 
 472 | MIGRATION: While using the node.js API, make sure to call `Compiler.close` when done.
 473 | 
 474 | ## File Emitting
 475 | 
 476 | webpack used to always emit all output files during the first build but skipped writing unchanged files during incremental (watch) builds.
 477 | It is assumed that nothing else changes output files while webpack is running.
 478 | 
 479 | With Persistent Caching added a watch-like experience should be given even when restarting the webpack process, but it would be a too strong assumption to think that nothing else changes the output directory even when webpack is not running.
 480 | 
 481 | So webpack will now check existing files in the output directory and compares their content with the output file in memory. It will only write the file when it has been changed.
 482 | This is only done on the first build. Any incremental build will always write the file when a new asset has been generated in the running webpack process.
 483 | 
 484 | We assume that webpack and plugins only generate new assets when content has been changed. Caching should be used to ensure that no new asset is generated when input is equal.
 485 | Not following this advice will degrade performance.
 486 | 
 487 | Files that are flagged as `immutable` (including a content hash), will never be written when a file with the same name already exists.
 488 | We assume that the content hash will change when file content changes. This is true in general, but might not be always true during webpack or plugin development.
 489 | 
 490 | # Major Changes: Long outstanding problems
 491 | 
 492 | ## Node.js target
 493 | 
 494 | In webpack 4 some features were not available e. g. for the Node.js target. Some of them are now available.
 495 | 
 496 | SplitChunks in initial chunks was not possible for node.js as multiple initial files couldn't be loaded.
 497 | It's now possible. The entry files will now load the additional files and also the runtime chunk.
 498 | 
 499 | ## SplitChunks for single-file-targets
 500 | 
 501 | Targets that only allow to startup a single file (like node, WebWorker, electron main) now supports loading the dependent pieces required for bootstrap automatically by the runtime.
 502 | 
 503 | This allows using `splitChunks` for these targets with `chunks: "all"`.
 504 | 
 505 | Note that since chunk loading is async, this makes initial evaluation async too. This can be an issue when using `output.library`, since the exported value is a Promise now. Since alpha.14 this does not apply to `target: "node"` since chunk loading is sync here.
 506 | 
 507 | ## Updated Resolver
 508 | 
 509 | `enhanced-resolve` was updated to v5. This has the following improvements:
 510 | 
 511 | - The resolve tracks more dependencies, like missing files
 512 | - aliasing may have multiple alternatives
 513 | - aliasing to `false` is possible now
 514 | - Increased performance
 515 | 
 516 | ## Chunks without JS
 517 | 
 518 | Chunks that contain no JS code, will no longer generate a JS file.
 519 | 
 520 | # Major Changes: Future
 521 | 
 522 | ## Experiments
 523 | 
 524 | Not all features are stable from the beginning. In webpack 4 we added experimental features and noted in the changelog that they are experimental, but it was not always clear from the configuration that these features are experimental.
 525 | 
 526 | In webpack 5 there is a new `experiments` config option which allows to enabled experimental features. This makes it clear which ones are enabled/used.
 527 | 
 528 | While webpack follows semantic versioning, it will make an exception for experimental features. Experimental features might contain breaking changes in minor webpack versions. When this happens we will add a clear note into the changelog. This will allow us to iterate faster for experimental features, while also allowing us to stay longer on a major version for stable features.
 529 | 
 530 | The following experiments will ship with webpack 5:
 531 | 
 532 | * Old WebAssembly support like in webpack 4 (`experiments.syncWebAssembly`)
 533 | * New WebAssembly support according to the [updated spec](https://github.com/WebAssembly/esm-integration) (`experiments.asyncWebAssembly`)
 534 |   * This makes a WebAssembly module an async module
 535 | * [Top Level Await](https://github.com/tc39/proposal-top-level-await) Stage 3 proposal (`experiments.topLevelAwait`)
 536 |   * Using `await` on top-level makes the module an async module
 537 | * Emitting bundle as module (`experiments.outputModule`)
 538 |   * This removed the wrapper IIFE from the bundle, enforces strict mode, lazy loads via `<script type="module">` and minimized in module mode
 539 | 
 540 | Note that this also means WebAssembly support is now disabled by default.
 541 | 
 542 | ## Minimum Node.js Version
 543 | 
 544 | The minimum supported node.js version has increased from 6 to 10.13.0(LTS).
 545 | 
 546 | MIGRATION: Upgrade to the latest node.js version available.
 547 | 
 548 | # Changes to the Configuration
 549 | 
 550 | ## Changes to the Structure
 551 | 
 552 | - `entry: {}` allows an empty object now (to allow to use plugins to add entries)
 553 | - `target` supports an array, versions and browserslist
 554 | - `cache: Object` removed: Setting to a memory-cache object is no longer possible
 555 | - `cache.type` added: It's now possible to choose between `"memory"` and `"filesystem"`
 556 | - New configuration options for `cache.type = "filesystem"` added:
 557 |   - `cache.cacheDirectory`
 558 |   - `cache.name`
 559 |   - `cache.version`
 560 |   - `cache.store`
 561 |   - `cache.hashAlgorithm`
 562 |   - `cache.idleTimeout`
 563 |   - `cache.idleTimeoutForIntialStore`
 564 |   - `cache.buildDependencies`
 565 | - `snapshot.resolveBuildDependencies` added
 566 | - `snapshot.resolve` added
 567 | - `snapshot.module` added
 568 | - `snapshot.managedPaths` added
 569 | - `snapshot.immutablePaths` added
 570 | - `resolve.cache` added: Allows to disable/enable the safe resolve cache
 571 | - `resolve.concord` removed
 572 | - `resolve.alias` values can be arrays or `false` now
 573 | - `resolve.restrictions` added: Allows to restrict potential resolve results
 574 | - `resolve.fallback` added: Allow to alias requests that failed to resolve
 575 | - `resolve.preferRelative` added: Allows to resolve modules requests are relative requests too
 576 | - Automatic polyfills for native node.js modules were removed
 577 |   - `node.Buffer` removed
 578 |   - `node.console` removed
 579 |   - `node.process` removed
 580 |   - `node.*` (node.js native module) removed
 581 |   - MIGRATION: `resolve.alias` and `ProvidePlugin`. Errors will give hints. (Refer to [node-libs-browser](https://github.com/webpack/node-libs-browser) for polyfills & mocks used in v4)
 582 | - `output.filename` can now be a function
 583 | - `output.assetModuleFilename` added
 584 | - `output.jsonpScriptType` renamed to `output.scriptType`
 585 | - `devtool` is more strict
 586 |   - Format: `false | eval | [inline-|hidden-|eval-][nosources-][cheap-[module-]]source-map`
 587 | - `optimization.chunkIds: "deterministic"` added
 588 | - `optimization.moduleIds: "deterministic"` added
 589 | - `optimization.moduleIds: "hashed"` deprecated
 590 | - `optimization.moduleIds: "total-size"` removed
 591 | - Deprecated flags for module and chunk ids were removed
 592 |   - `optimization.hashedModuleIds` removed
 593 |   - `optimization.namedChunks` removed (`NamedChunksPlugin` too)
 594 |   - `optimization.namedModules` removed (`NamedModulesPlugin` too)
 595 |   - `optimization.occurrenceOrder` removed
 596 |   - MIGRATION: Use `chunkIds` and `moduleIds`
 597 | - `optimization.splitChunks` `test` no longer matches chunk name
 598 |   - MIGRATION: Use a test function
 599 |     `(module, { chunkGraph }) => chunkGraph.getModuleChunks(module).some(chunk => chunk.name === "name")`
 600 | - `optimization.splitChunks` `minRemainingSize` was added
 601 | - `optimization.splitChunks` `filename` can now be a function
 602 | - `optimization.splitChunks` sizes can now be objects with a size per source type
 603 |   - `minSize`
 604 |   - `minRemainingSize`
 605 |   - `maxSize`
 606 |   - `maxAsyncSize`
 607 |   - `maxInitialSize`
 608 | - `optimization.splitChunks` `maxAsyncSize` and `maxInitialSize` added next to `maxSize`: allows to specify different max sizes for initial and async chunks
 609 | - `optimization.splitChunks` `name: true` removed: Automatic names are no longer supported
 610 |   - MIGRATION: Use the default. `chunkIds: "named"` will give your files useful names for debugging
 611 | - `optimization.splitChunks.cacheGroups[].idHint` added: Gives a hint how the named chunk id should be chosen
 612 | - `optimization.splitChunks` `automaticNamePrefix` removed
 613 |   - MIGRATION: Use `idHint` instead
 614 | - `optimization.splitChunks` `filename` is no longer restricted to initial chunks
 615 | - `optimization.splitChunks` `usedExports` added to include used exports when comparing modules
 616 | - `optimization.splitChunks.defaultSizeTypes` added: Specified the size types when using numbers for sizes
 617 | - `optimization.mangleExports` added
 618 | - `optimization.minimizer` `"..."` can be used to reference the defaults
 619 | - `optimization.usedExports` `"global"` value added to allow to disable the analysis per runtime and instead do it globally (better performance)
 620 | - `optimization.noEmitOnErrors` renamed to `optimization.emitOnErrors` and logic inverted
 621 | - `optimization.realContentHash` added
 622 | - `output.devtoolLineToLine` removed
 623 |   - MIGRATION: No replacement
 624 | - `output.chunkFilename: Function` is now allowed
 625 | - `output.hotUpdateChunkFilename: Function` is now forbidden: It never worked anyway.
 626 | - `output.hotUpdateMainFilename: Function` is now forbidden: It never worked anyway.
 627 | - `output.importFunctionName: string` specifies the name used as replacement for `import()` to allow polyfilling for non-suppored environments
 628 | - `output.charset` added: setting it to false omit the `charset` property on script tags
 629 | - `output.hotUpdateFunction` renamed to `output.hotUpdateGlobal`
 630 | - `output.jsonpFunction` renamed to `output.chunkLoadingGlobal`
 631 | - `output.chunkCallbackFunction` renamed to `output.chunkLoadingGlobal`
 632 | - `output.chunkLoading` added
 633 | - `output.enabledChunkLoadingTypes` added
 634 | - `output.chunkFormat` added
 635 | - `module.rules` `resolve` and `parser` will merge in a different way (objects are deeply merged, array may include `"..."` to reference to prev value)
 636 | - `module.rules` `parser.worker` added: Allows to configure the worker supported
 637 | - `module.rules` `query` and `loaders` were removed
 638 | - `module.rules` `options` passing a string is deprecated
 639 |   - MIGRATION: Pass an options object instead, open an issue on the loader when this is not supported
 640 | - `module.rules` `mimetype` added: allows to match a mimetype of a DataUri
 641 | - `module.rules` `descriptionData` added: allows to match a data from package.json
 642 | - `module.defaultRules` `"..."` can be used to reference the defaults
 643 | - `stats.chunkRootModules` added: Show root modules for chunks
 644 | - `stats.orphanModules` added: Show modules which are not emitted
 645 | - `stats.runtime` added: Show runtime modules
 646 | - `stats.chunkRelations` added: Show parent/children/sibling chunks
 647 | - `stats.errorStack` added: Show webpack-internal stack trace of errors
 648 | - `stats.preset` added: select a preset
 649 | - `stats.relatedAssets` added: show assets that are related to other assets (e. g. SourceMaps)
 650 | - `stats.warningsFilter` deprecated in favor of `ignoreWarnings`
 651 | - `BannerPlugin.banner` signature changed
 652 |   - `data.basename` removed
 653 |   - `data.query` removed
 654 |   - MIGRATION: extract from `filename`
 655 | - `SourceMapDevToolPlugin` `lineToLine` removed
 656 |   - MIGRATION: No replacement
 657 | - `[hash]` as hash for the full compilation is now deprecated
 658 |   - MIGRATION: Use `[fullhash]` instead or better use another hash option
 659 | - `[modulehash]` is deprecated
 660 |   - MIGRATION: Use `[hash]` instead
 661 | - `[moduleid]` is deprecated
 662 |   - MIGRATION: Use `[id]` instead
 663 | - `[filebase]` removed
 664 |   - MIGRATION: Use `[base]` instead
 665 | - New placeholders for file-based templates (i. e. SourceMapDevToolPlugin)
 666 |   - `[name]`
 667 |   - `[base]`
 668 |   - `[path]`
 669 |   - `[ext]`
 670 | - `externals` when passing a function, it has now a different signature `({ context, request }, callback)`
 671 |   - MIGRATION: Change signature
 672 | - `externalsPresets` added
 673 | - `experiments` added (see Experiments section above)
 674 | - `watchOptions.followSymlinks` added
 675 | - `watchOptions.ignored` can now be a RegExp
 676 | - `webpack.util.serialization` is now exposed.
 677 | 
 678 | ## Changes to the Defaults
 679 | 
 680 | - `target` is now `"browserslist"` by default when a browserslist config is available
 681 | - `module.unsafeCache` is now only enabled for `node_modules` by default
 682 | - `optimization.moduleIds` defaults to `deterministic` in production mode, instead of `size`
 683 | - `optimization.chunkIds` defaults to `deterministic` in production mode, instead of `total-size`
 684 | - `optimization.nodeEnv` defaults to `false` in `none` mode
 685 | - `optimization.splitChunks.minSize` defaults to `20k` in production
 686 | - `optimization.splitChunks.enforceSizeThreshold` defaults to `50k` in production
 687 | - `optimization.splitChunks` `minRemainingSize` defaults to `minSize`
 688 |   - This will lead to less splitted chunks created in cases where the remaining part would be too small
 689 | - `optimization.splitChunks` `maxAsyncRequests` and `maxInitialRequests` defaults was been increased to 30
 690 | - `optimization.splitChunks.cacheGroups.vendors` has be renamed to `optimization.splitChunks.cacheGroups.defaultVendors`
 691 | - `optimization.splitChunks.cacheGroups.defaultVendors.reuseExistingChunk` now defaults to `true`
 692 | - `resolve(Loader).cache` defaults to `true` when `cache` is used
 693 | - `resolve(Loader).cacheWithContext` defaults to `false`
 694 | - `resolveLoader.extensions` remove `.json`
 695 | - `node.global` `node.__filename` and `node.__dirname` defaults to `false` in node-`target`s
 696 | - `stats.errorStack` defaults to `false`
 697 | 
 698 | # Loader related Changes
 699 | 
 700 | ## `this.getOptions`
 701 | 
 702 | This new API should simplity the usage for options in loaders.
 703 | It allows to pass an JSON schema for validation.
 704 | See https://github.com/webpack/webpack/pull/10017 for details
 705 | 
 706 | # Major Internal Changes
 707 | 
 708 | The following changes are only relevant for plugin authors:
 709 | 
 710 | ## New plugin order
 711 | 
 712 | Plugins in webpack 5 are now applies **before** the configuration defaults has been applied.
 713 | This allows plugins to apply their own defaults, or act as configuration presets.
 714 | 
 715 | But this is also a breaking change as plugins can't rely on configuration values to be set when they are applied.
 716 | 
 717 | MIGRATION: Access configuration only in plugin hooks. Or best avoid accessing configuration at all and take options via constructor.
 718 | 
 719 | ## Runtime Modules
 720 | 
 721 | A large part of the runtime code was moved into the so-called "runtime modules". These special modules are in-charge of adding runtime code. They can be added into any chunk, but are currently always added to the runtime chunk. "Runtime Requirements" control which runtime modules (or core runtime parts) are added to the bundle. This ensures that only runtime code that is used is added to the bundle. In the future, runtime modules could also be added to an on-demand-loaded chunk, to load runtime code when needed.
 722 | 
 723 | In most cases, the core runtime allows to inline the entry module instead of calling it with `__webpack_require__`. If there is no other module in the bundle, no `__webpack_require__` is needed at all. This combines well with Module Concatenation where multiple modules are concatenated into a single module.
 724 | 
 725 | In the best case, no runtime code is needed at all.
 726 | 
 727 | MIGRATION: If you are injecting runtime code into the webpack runtime in a plugin, consider using RuntimeModules instead.
 728 | 
 729 | ## Serialization
 730 | 
 731 | A serialization mechanism was added to allow serialization of complex objects in webpack. It has an opt-in semantic, so classes that should be serialized need to be explicitly flagged (and their serialization implemented). This has been done for most Modules, all Dependencies and some Errors.
 732 | 
 733 | MIGRATION: When using custom Modules or Dependencies, it is recommended to make them serializable to benefit from persistent caching.
 734 | 
 735 | ## Extensible Caching
 736 | 
 737 | A `Cache` class with a plugin interface has been added. This class can be used to write and read to the cache. Depending on the configuration, different plugins can add functionality to the cache. The `MemoryCachePlugin` adds in-memory caching. The `FileCachePlugin` adds persistent (file-system) caching.
 738 | 
 739 | The `FileCachePlugin` uses the serialization mechanism to persist and restore cached items to/from the disk.
 740 | 
 741 | ## Hook Object Frozen
 742 | 
 743 | Classes with `hooks` have their `hooks` object frozen, so adding custom hooks is no longer possible this way.
 744 | 
 745 | MIGRATION: The recommended way to add custom hooks is using a WeakMap and a static `getXXXHooks(XXX)` (i. e. `getCompilationHook(compilation)`) method. Internal classes use the same mechanism used for custom hooks.
 746 | 
 747 | ## Tapable Upgrade
 748 | 
 749 | The compat layer for webpack 3 plugins has been removed. It had already been deprecated for webpack 4.
 750 | 
 751 | Some less used tapable APIs were removed or deprecated.
 752 | 
 753 | MIGRATION: Use the new tapable API.
 754 | 
 755 | ## Staged Hooks
 756 | 
 757 | For several steps in the sealing process, there had been multiple hooks for different stages. i. e. `optimizeDependenciesBasic` `optimizeDependencies` and `optimizeDependenciesAdvanced`. These have been removed in favor of a single hook which can be used with a `stage` option. See `OptimizationStages` for possible stage values.
 758 | 
 759 | MIGRATION: Hook into the remaining hook instead. You may add a `stage` option.
 760 | 
 761 | ## Main/Chunk/ModuleTemplate deprecation
 762 | 
 763 | Bundle templating has been refactored. MainTemplate/ChunkTemplate/ModuleTemplate were deprecated and the JavascriptModulesPlugin takes care of JS templating now.
 764 | 
 765 | Before that refactoring, JS output was handled by Main/ChunkTemplate while another output (i. e. WASM, CSS) was handled by plugins. This looks like JS is first class, while another output is second class. The refactoring changes that and all output is handled by their plugins.
 766 | 
 767 | It's still possible to hook into parts of the templating. The hooks are in JavascriptModulesPlugin instead of Main/ChunkTemplate now. (Yes plugins can have hooks too. I call them attached hooks.)
 768 | 
 769 | There is a compat-layer, so Main/Chunk/ModuleTemplate still exist, but only delegate tap calls to the new hook locations.
 770 | 
 771 | MIGRATION: Follow the advice in the deprecation messages. Mostly pointing to hooks at different locations.
 772 | 
 773 | ## Entry point descriptor
 774 | 
 775 | If an object is passed as entry point the value might be a string, array of strings or a descriptor:
 776 | 
 777 | ```js
 778 | module.exports = {
 779 |   entry: {
 780 |     catalog: { 
 781 |       import: './catalog.js',
 782 |     }
 783 |   }
 784 | };
 785 | ```
 786 | 
 787 | Descriptor syntax might be used to pass additional options to an entry point.
 788 | 
 789 | ### Entry point output filename
 790 | 
 791 | By default, the output filename for the entry chunk is extracted from `output.filename` but you can specify a custom output filename for a specific entry:
 792 | 
 793 | ```js
 794 | module.exports = {
 795 |   entry: {
 796 |     about: { import: './about.js', filename: 'pages/[name][ext]' }
 797 |   }
 798 | };
 799 | ```
 800 | 
 801 | ### Entry point dependency
 802 | 
 803 | By default, every entry chunk stores all the modules that it uses. With `dependOn`-option you can share the modules from one entry chunk to another:
 804 | 
 805 | ```js
 806 | module.exports = {
 807 |   entry: {
 808 |     app: { import: './app.js', dependOn: 'react-vendors' },
 809 |     'react-vendors': ['react', 'react-dom', 'prop-types']
 810 |   }
 811 | };
 812 | ```
 813 | 
 814 | The app chunk will not contain the modules that `react-vendors` has.
 815 | 
 816 | ### Entry point library
 817 | 
 818 | The entry descriptor allows to pass a different `library` option for each entrypoint.
 819 | 
 820 | ```js
 821 | module.exports = {
 822 |   entry: {
 823 |     commonjs: {
 824 |       import: './lib.js',
 825 |       library: {
 826 |         type: "commonjs-module"
 827 |       }
 828 |     },
 829 |     amd: {
 830 |       import: './lib.js',
 831 |       library: {
 832 |         type: "amd"
 833 |       }
 834 |     }
 835 |   }
 836 | };
 837 | ```
 838 | 
 839 | ### Entry point runtime
 840 | 
 841 | The entry descriptor allows to specify a `runtime` per entry.
 842 | When specified a chunk with this name is created which contains only the runtime code for the entry.
 843 | When multiple entries specify the same `runtime`, that chunk will contain a common runtime for all these entry.
 844 | This means they could be used together on the same HTML page.
 845 | 
 846 | ```js
 847 | module.exports = {
 848 |   entry: {
 849 |     app: {
 850 |       import: './app.js',
 851 |       runtime: "app-runtime"
 852 |     }
 853 |   }
 854 | };
 855 | ```
 856 | 
 857 | ### Entry point chunk loading
 858 | 
 859 | The entry descriptor allows to specify a `chunkLoading` per entry.
 860 | The runtime for this entry will use this to load chunks.
 861 | 
 862 | ```js
 863 | module.exports = {
 864 |   entry: {
 865 |     app: {
 866 |       import: './app.js'
 867 |     },
 868 |     worker: {
 869 |       import: './worker.js',
 870 |       chunkLoading: "importScripts"
 871 |     }
 872 |   }
 873 | };
 874 | ```
 875 | 
 876 | ## Order and IDs
 877 | 
 878 | webpack used to order modules and chunks in the Compilation phase, in a specific way, to assign IDs in incremental order. This is no longer the case. The order will no longer be used for id generation, instead, the full control of ID generation is in the plugin.
 879 | 
 880 | Hooks to optimize the order of module and chunks have been removed.
 881 | 
 882 | MIGRATION: You cannot rely on the order of modules and chunks in the compilation phase no more.
 883 | 
 884 | ## Arrays to Sets
 885 | 
 886 | - Compilation.modules is now a Set
 887 | - Compilation.chunks is now a Set
 888 | - Chunk.files is now a Set
 889 | 
 890 | There is a compat-layer which prints deprecation warnings.
 891 | 
 892 | MIGRATION: Use Set methods instead of Array methods.
 893 | 
 894 | ## Compilation.fileSystemInfo
 895 | 
 896 | This new class can be used to access information about the filesystem in a cached way. Currently, it allows asking for both file and directory timestamps. Information about timestamps is transferred from the watcher if possible, otherwise determined by filesystem access.
 897 | 
 898 | In the future, asking for file content hashes will be added and modules will be able to check validity with file contents instead of file hashes.
 899 | 
 900 | MIGRATION: Instead of using `file/contextTimestamps` use the `compilation.fileSystemInfo` API instead.
 901 | 
 902 | Timestamping for directories is possible now, which allows serialization of ContextModules.
 903 | 
 904 | `Compiler.modifiedFiles` has been added (next to `Compiler.removedFiles`) to make it easier to reference the changed files.
 905 | 
 906 | ## Filesystems
 907 | 
 908 | Next to `compiler.inputFileSystem` and `compiler.outputFileSystem` there is a new `compiler.intermediateFileSystem` for all fs actions that are not considered as input or output, like writing records, cache or profiling output.
 909 | 
 910 | The filesystems have now the `fs` interface and do no longer demand additional methods like `join` or `mkdirp`. But if they have methods like `join` or `dirname` they are used.
 911 | 
 912 | ## Hot Module Replacement
 913 | 
 914 | HMR runtime has been refactored to Runtime Modules. `HotUpdateChunkTemplate` has been merged into `ChunkTemplate`. ChunkTemplates and plugins should also handle `HotUpdateChunk`s now.
 915 | 
 916 | The javascript part of HMR runtime has been separated from the core HMR runtime. Other module types can now also handle HMR in their own way. In the future, this will allow i. e. HMR for the mini-css-extract-plugin or for WASM modules.
 917 | 
 918 | MIGRATION: As this is a newly introduced functionality, there is nothing to migrate.
 919 | 
 920 | `import.meta.webpackHot` exposes the same API as `module.hot`. This is also usable from strict ESM modules (.mjs, type: "module" in package.json) which do not have access to `module`.
 921 | 
 922 | ## Work Queues
 923 | 
 924 | webpack used to handle module processing by functions calling functions, and a `semaphore` which limits parallelism. The `Compilation.semaphore` has been removed and async queues now handle work queuing and processing. Each step has a separate queue:
 925 | 
 926 | - `Compilation.factorizeQueue`: calling the module factory for a group of dependencies.
 927 | - `Compilation.addModuleQueue`: adding the module to the compilation queue (may restore module from cache).
 928 | - `Compilation.buildQueue`: building the module if necessary (may stores module to cache).
 929 | - `Compilation.rebuildQueue`: building a module again if manually triggered.
 930 | - `Compilation.processDependenciesQueue`: processing dependencies of a module.
 931 | 
 932 | These queues have some hooks to watch and intercept job processing.
 933 | 
 934 | In the future, multiple compilers may work together and job orchestration can be done by intercepting these queues.
 935 | 
 936 | MIGRATION: As this is a newly introduced functionality, there is nothing to migrate.
 937 | 
 938 | ## Logging
 939 | 
 940 | webpack internals includes some logging now.
 941 | `stats.logging` and `infrastructureLogging` options can be used to enabled these messages.
 942 | 
 943 | ## Module and Chunk Graph
 944 | 
 945 | webpack used to store a resolved module in the dependency, and store the contained modules in the chunk. This is no longer the case. All information about how modules are connected in the module graph are now stored in a ModuleGraph class. All information about how modules are connected with chunks are now stored in the ChunkGraph class. The information which depends on i. e. the chunk graph, is also stored in the related class.
 946 | 
 947 | That means the following information about modules has been moved:
 948 | 
 949 | - Module connections -> ModuleGraph
 950 | - Module issuer -> ModuleGraph
 951 | - Module optimization bailout -> ModuleGraph (TODO: check if it should ChunkGraph instead)
 952 | - Module usedExports -> ModuleGraph
 953 | - Module providedExports -> ModuleGraph
 954 | - Module pre order index -> ModuleGraph
 955 | - Module post order index -> ModuleGraph
 956 | - Module depth -> ModuleGraph
 957 | - Module profile -> ModuleGraph
 958 | - Module id -> ChunkGraph
 959 | - Module hash -> ChunkGraph
 960 | - Module runtime requirements -> ChunkGraph
 961 | - Module is in chunk -> ChunkGraph
 962 | - Module is entry in chunk -> ChunkGraph
 963 | - Module is runtime module in chunk -> ChunkGraph
 964 | - Chunk runtime requirements -> ChunkGraph
 965 | 
 966 | webpack used to disconnect modules from the graph when restored from the cache. This is no longer necessary. A Module stores no info about the graph and can technically be used in multiple graphs. This makes caching easier.
 967 | 
 968 | There is a compat-layer for most of these changes, which prints a deprecation warning when used.
 969 | 
 970 | MIGRATION: Use the new APIs on ModuleGraph and ChunkGraph
 971 | 
 972 | ## Init Fragments
 973 | 
 974 | `DependenciesBlockVariables` has been removed in favor of InitFragments. `DependencyTemplates` can now add `InitFragments` to inject code to the top of the module's source. `InitFragments` allows deduplication.
 975 | 
 976 | MIGRATION: Use `InitFragments` instead of inserting something at a negative index into the source.
 977 | 
 978 | ## Module Source Types
 979 | 
 980 | Modules now have to define which source types they support via `Module.getSourceTypes()`. Depending on that, different plugins call `source()` with these types. i. e. for source type `javascript` the `JavascriptModulesPlugin` embeds the source code into the bundle. Source type `webassembly` will make the `WebAssemblyModulesPlugin` emit a wasm file. Custom source types are also supported, i. e. the mini-css-extract-plugin will probably use the source type `stylesheet` to embed the source code into a css file.
 981 | 
 982 | There is no relationship between module type and source type. i. e. module type `json` also uses source type `javascript` and module type `webassembly/experimental` uses source types `javascript` and `webassembly`.
 983 | 
 984 | MIGRATION: Custom modules need to implement these new interface methods.
 985 | 
 986 | ## Extensible Stats
 987 | 
 988 | Stats `preset`, `default`, `json` and `toString` are now baked in by a plugin system. Converted the current Stats into plugins.
 989 | 
 990 | MIGRATION: Instead of replacing the whole Stats functionality, you can now customize it. Extra information can now be added to the stats json instead of writing a separate file.
 991 | 
 992 | ## New Watching
 993 | 
 994 | The watcher used by webpack was refactored. It was previously using `chokidar` and the native dependency `fsevents` (only on OSX). Now it's only based on native node.js `fs`. This means there is no native dependency left in webpack.
 995 | 
 996 | It also captures more information about filesystem while watching. It now captures mtimes and watches event times, as well as information about missing files. For this, the `WatchFileSystem` API changed a little bit. While on it we also converted Arrays to Sets and Objects to Maps.
 997 | 
 998 | ## SizeOnlySource after emit
 999 | 
1000 | webpack now replaces the Sources in `Compilation.assets` with `SizeOnlySource` variants to reduce memory usage.
1001 | 
1002 | ## Emitting assets multiple times
1003 | 
1004 | The warning `Multiple assets emit different content to the same filename` has been made an error.
1005 | 
1006 | ## ExportsInfo
1007 | 
1008 | The way how information about exports of modules is stored has been refactored. The ModuleGraph now features an `ExportsInfo` for each `Module`, which stores information per export. It also stores information about unknown exports and if the module is used in a side-effect-only way.
1009 | 
1010 | For each export the following information is stored:
1011 | 
1012 | - Is the export used? yes, no, not statically known, not determined. (see also `optimization.usedExports`)
1013 | - Is the export provided? yes, no, not statically known, not determined. (see also `optimization.providedExports`)
1014 | - Can be export name be renamed? yes, no, not determined.
1015 | - The new name, if the export has been renamed. (see also `optimization.mangleExports`)
1016 | - Nested ExportsInfo, if the export is an object with information attached itself
1017 |   - Used for reexporting namespace objects: `import * as X from "..."; export { X };`
1018 |   - Used for representing structure in JSON modules
1019 | 
1020 | ## Code Generation Phase
1021 | 
1022 | The Compilation features Code Generation as separate compilation phase now. It no longer runs hidden in `Module.source()` or `Module.getRuntimeRequirements()`.
1023 | 
1024 | This should make the flow much cleaner. It also allows to report progress for this phase and makes Code Generation more visible when profiling.
1025 | 
1026 | MIGRATION: `Module.source()` and `Module.getRuntimeRequirements()` are deprecated now. Use `Module.codeGeneration()` instead.
1027 | 
1028 | ## Improved Code Generation
1029 | 
1030 | webpack detects when ASI happens and generates shorter code when no semicolons are inserted. `Object(...)` -> `(0, ...)`
1031 | 
1032 | webpack merges multiple export getters into a single runtime function call: `r.d(x, "a", () => a); r.d(x, "b", () => b);` -> `r.d(x, {a: () => a, b: () => b});`
1033 | 
1034 | ## DependencyReference
1035 | 
1036 | webpack used to have a single method and type to represent references of dependencies (`Compilation.getDependencyReference` returning a `DependencyReference`).
1037 | This type used to include all information about this reference like the referenced Module, which exports have been imported, if it's a weak reference and also some ordering related information.
1038 | 
1039 | Bundling all these information together makes getting the reference expensive and it's also called very often every time somebody needs one piece of information.
1040 | 
1041 | In webpack 5 this part of the codebase was refactored and the method has been split up.
1042 | 
1043 | - The referenced module can be read from the ModuleGraphConnection
1044 | - The imported export names can be get via `Dependency.getReferencedExports()`
1045 | - There is a `weak` flag on the `Dependency` class
1046 | - Ordering is only relevant to `HarmonyImportDependencies` and can be get via `sourceOrder` property
1047 | 
1048 | ## Presentational Dependencies
1049 | 
1050 | There is now a new type of dependency in `NormalModules`: Presentational Dependencies
1051 | 
1052 | These dependencies are only used during the Code Generation phase but are not used during Module Graph building.
1053 | So they can never have referenced modules or influence exports/imports.
1054 | 
1055 | These dependencies are cheaper to process and webpack uses them when possible
1056 | 
1057 | ## Deprecated loaders
1058 | 
1059 | - [`null-loader`](https://github.com/webpack-contrib/null-loader)
1060 |   
1061 |   It will be deprecated. Use 
1062 |   
1063 |   ```js
1064 |   alias: {
1065 |       xyz$: false
1066 |   }
1067 |   ```  
1068 |   
1069 |   or use an absolute path
1070 |  
1071 |   ```js
1072 |   alias: { 
1073 |     [path.resolve(__dirname, "....")]: false 
1074 |   } 
1075 |   ```
1076 |   
1077 | # Minor Changes
1078 | 
1079 | - `Compiler.name`: When generating a compiler name with absolute paths, make sure to separate them with `|` or `!` on both parts of the name.
1080 |   - Using space as a separator is now deprecated. (Paths could contain spaces)
1081 |   - Hint: `|` is replaced with space in Stats string output.
1082 | - `SystemPlugin` is now disabled by default.
1083 |   - MIGRATION: Avoid using it as the spec has been removed. You can re-enable it with `Rule.parser.system: true`
1084 | - `ModuleConcatenationPlugin`: concatenation is no longer prevented by `DependencyVariables` as they have been removed
1085 |   - This means it can now concatenate in cases of `module`, `global`, `process` or the ProvidePlugin
1086 | - `exec` removed from the loader context
1087 |   - MIGRATION: This can be implemented in the loader itself
1088 | - `Stats.presetToOptions` removed
1089 |   - MIGRATION: Use `compilation.createStatsOptions` instead
1090 | - `SingleEntryPlugin` and `SingleEntryDependency` removed
1091 |   - MIGRATION: use `EntryPlugin` and `EntryDependency`
1092 | - Chunks can now have multiple entry modules
1093 | - `ExtendedAPIPlugin` removed
1094 |   - MIGRATION: No longer needed, `__webpack_hash__` and `__webpack_chunkname__` can always be used and runtime code is injected where needed.
1095 | - `ProgressPlugin` no longer uses tapable context for `reportProgress`
1096 |   - MIGRATION: Use `ProgressPlugin.getReporter(compiler)` instead
1097 | - `ProvidePlugin` is now re-enabled for `.mjs` files
1098 | - `Stats` json `errors` and `warnings` no longer contain strings but objects with information splitted into properties.
1099 |   - MIGRATION: Access the information on the properties. i. e. `message`
1100 | - `Compilation.hooks.normalModuleLoader` is deprecated
1101 |   - MIGRATION: Use `NormalModule.getCompilationHooks(compilation).loader` instead
1102 | - Changed hooks in `NormalModuleFactory` from waterfall to bailing, changed and renamed hooks that return waterfall functions
1103 | - Removed `compilationParams.compilationDependencies`
1104 |   - Plugins can add dependencies to the compilation by adding to `compilation.file/context/missingDependencies`
1105 |   - Compat layer will delegate `compilationDependencies.add` to `fileDependencies.add`
1106 | - `stats.assetsByChunkName[x]` is now always an array
1107 | - `__webpack_get_script_filename__` function added to get the filename of a script file
1108 | - `getResolve(options)` in the loader API will merge options in a different way, see `module.rules` `resolve`
1109 | - `"sideEffects"` in package.json will be handled by `glob-to-regex` instead of `micromatch`
1110 |   - This may have changed semantics in edge-cases
1111 | - `checkContext` was removed from `IgnorePlugin`
1112 | - New `__webpack_exports_info__` API allows export usage introspection
1113 | - SourceMapDevToolPlugin applies to non-chunk assets too now
1114 | - EnvironmentPlugin shows an error now when referenced env variable is missing and has no fallback
1115 | - Remove serve property from schema
1116 | 
1117 | # Other Minor Changes
1118 | 
1119 | - removed buildin directory and replaced buildins with runtime modules
1120 | - Removed deprecated features
1121 |   - BannerPlugin now only support one argument that can be an object, string or function
1122 | - removed `CachePlugin`
1123 | - `Chunk.entryModule` is deprecated, use ChunkGraph instead
1124 | - `Chunk.hasEntryModule` is deprecated
1125 | - `Chunk.addModule` is deprecated
1126 | - `Chunk.removeModule` is deprecated
1127 | - `Chunk.getNumberOfModules` is deprecated
1128 | - `Chunk.modulesIterable` is deprecated
1129 | - `Chunk.compareTo` is deprecated
1130 | - `Chunk.containsModule` is deprecated
1131 | - `Chunk.getModules` is deprecated
1132 | - `Chunk.remove` is deprecated
1133 | - `Chunk.moveModule` is deprecated
1134 | - `Chunk.integrate` is deprecated
1135 | - `Chunk.canBeIntegrated` is deprecated
1136 | - `Chunk.isEmpty` is deprecated
1137 | - `Chunk.modulesSize` is deprecated
1138 | - `Chunk.size` is deprecated
1139 | - `Chunk.integratedSize` is deprecated
1140 | - `Chunk.getChunkModuleMaps` is deprecated
1141 | - `Chunk.hasModuleInGraph` is deprecated
1142 | - `Chunk.updateHash` signature changed
1143 | - `Chunk.getChildIdsByOrders` signature changed (TODO: consider moving to `ChunkGraph`)
1144 | - `Chunk.getChildIdsByOrdersMap` signature changed (TODO: consider moving to `ChunkGraph`)
1145 | - `Chunk.getChunkModuleMaps` removed
1146 | - `Chunk.setModules` removed
1147 | - deprecated Chunk methods removed
1148 | - `ChunkGraph` added
1149 | - `ChunkGroup.setParents` removed
1150 | - `ChunkGroup.containsModule` removed
1151 | - `ChunkGroup.remove` no longer disconnected the group from block
1152 | - `ChunkGroup.compareTo` signature changed
1153 | - `ChunkGroup.getChildrenByOrders` signature changed
1154 | - `ChunkGroup` index and index renamed to pre/post order index
1155 |   - old getter is deprecated
1156 | - `ChunkTemplate.hooks.modules` signature changed
1157 | - `ChunkTemplate.hooks.render` signature changed
1158 | - `ChunkTemplate.updateHashForChunk` signature changed
1159 | - `Compilation.hooks.optimizeChunkOrder` removed
1160 | - `Compilation.hooks.optimizeModuleOrder` removed
1161 | - `Compilation.hooks.advancedOptimizeModuleOrder` removed
1162 | - `Compilation.hooks.optimizeDependenciesBasic` removed
1163 | - `Compilation.hooks.optimizeDependenciesAdvanced` removed
1164 | - `Compilation.hooks.optimizeModulesBasic` removed
1165 | - `Compilation.hooks.optimizeModulesAdvanced` removed
1166 | - `Compilation.hooks.optimizeChunksBasic` removed
1167 | - `Compilation.hooks.optimizeChunksAdvanced` removed
1168 | - `Compilation.hooks.optimizeChunkModulesBasic` removed
1169 | - `Compilation.hooks.optimizeChunkModulesAdvanced` removed
1170 | - `Compilation.hooks.optimizeExtractedChunksBasic` removed
1171 | - `Compilation.hooks.optimizeExtractedChunks` removed
1172 | - `Compilation.hooks.optimizeExtractedChunksAdvanced` removed
1173 | - `Compilation.hooks.afterOptimizeExtractedChunks` removed
1174 | - `Compilation.hooks.stillValidModule` added
1175 | - `Compilation.hooks.statsPreset` added
1176 | - `Compilation.hooks.statsNormalize` added
1177 | - `Compilation.hooks.statsFactory` added
1178 | - `Compilation.hooks.statsPrinter` added
1179 | - `Compilation.fileDependencies`, `Compilation.contextDependencies` and `Compilation.missingDependencies` are now LazySets
1180 | - `Compilation.entries` removed
1181 |   - MIGRATION: Use `Compilation.entryDependencies` instead
1182 | - `Compilation._preparedEntrypoints` removed
1183 | - `dependencyTemplates` is now a `DependencyTemplates` class instead of a raw `Map`
1184 | - `Compilation.fileTimestamps` and `contextTimestamps` removed
1185 |   - MIGRATION: Use `Compilation.fileSystemInfo` instead
1186 | - `Compilation.waitForBuildingFinished` removed
1187 |   - MIGRATION: Use the new queues
1188 | - `Compilation.addModuleDependencies` removed
1189 | - `Compilation.prefetch` removed
1190 | - `Compilation.hooks.beforeHash` is now called after the hashes of modules are created
1191 |   - MIGRATION: Use `Compiliation.hooks.beforeModuleHash` instead
1192 | - `Compilation.applyModuleIds` removed
1193 | - `Compilation.applyChunkIds` removed
1194 | - `Compiler.root` added, which points to the root compiler
1195 |   - it can be used to cache data in WeakMaps instead of statically scoped
1196 | - `Compiler.hooks.afterDone` added
1197 | - `Source.emitted` is no longer set by the Compiler
1198 |   - MIGRATION: Check `Compilation.emittedAssets` instead
1199 | - `Compiler/Compilation.compilerPath` added: It's a unique name of the compiler in the compiler tree. (Unique to the root compiler scope)
1200 | - `Module.needRebuild` deprecated
1201 |   - MIGRATION: use `Module.needBuild` instead
1202 | - `Dependency.getReference` signature changed
1203 | - `Dependency.getExports` signature changed
1204 | - `Dependency.getWarnings` signature changed
1205 | - `Dependency.getErrors` signature changed
1206 | - `Dependency.updateHash` signature changed
1207 | - `Dependency.module` removed
1208 | - There is now a base class for `DependencyTemplate`
1209 | - `MultiEntryDependency` removed
1210 | - `EntryDependency` added
1211 | - `EntryModuleNotFoundError` removed
1212 | - `SingleEntryPlugin` removed
1213 | - `EntryPlugin` added
1214 | - `Generator.getTypes` added
1215 | - `Generator.getSize` added
1216 | - `Generator.generate` signature changed
1217 | - `HotModuleReplacementPlugin.getParserHooks` added
1218 | - `Parser` was moved to `JavascriptParser`
1219 | - `ParserHelpers` was moved to `JavascriptParserHelpers`
1220 | - `MainTemplate.hooks.moduleObj` removed
1221 | - `MainTemplate.hooks.currentHash` removed
1222 | - `MainTemplate.hooks.addModule` removed
1223 | - `MainTemplate.hooks.requireEnsure` removed
1224 | - `MainTemplate.hooks.globalHashPaths` removed
1225 | - `MainTemplate.hooks.globalHash` removed
1226 | - `MainTemplate.hooks.hotBootstrap` removed
1227 | - `MainTemplate.hooks` some signatures changed
1228 | - `Module.hash` deprecated
1229 | - `Module.renderedHash` deprecated
1230 | - `Module.reasons` removed
1231 | - `Module.id` deprecated
1232 | - `Module.index` deprecated
1233 | - `Module.index2` deprecated
1234 | - `Module.depth` deprecated
1235 | - `Module.issuer` deprecated
1236 | - `Module.profile` removed
1237 | - `Module.prefetched` removed
1238 | - `Module.built` removed
1239 | - `Module.used` removed
1240 |   - MIGRATION: Use `Module.getUsedExports` instead
1241 | - Module.usedExports deprecated
1242 |   - MIGRATION: Use `Module.getUsedExports` instead
1243 | - `Module.optimizationBailout` deprecated
1244 | - `Module.exportsArgument` removed
1245 | - `Module.optional` deprecated
1246 | - `Module.disconnect` removed
1247 | - `Module.unseal` removed
1248 | - `Module.setChunks` removed
1249 | - `Module.addChunk` deprecated
1250 | - `Module.removeChunk` deprecated
1251 | - `Module.isInChunk` deprecated
1252 | - `Module.isEntryModule` deprecated
1253 | - `Module.getChunks` deprecated
1254 | - `Module.getNumberOfChunks` deprecated
1255 | - `Module.chunksIterable` deprecated
1256 | - `Module.hasEqualsChunks` removed
1257 | - `Module.useSourceMap` moved to `NormalModule`
1258 | - `Module.addReason` removed
1259 | - `Module.removeReason` removed
1260 | - `Module.rewriteChunkInReasons` removed
1261 | - `Module.isUsed` removed
1262 |   - MIGRATION: Use `isModuleUsed`, `isExportUsed` and `getUsedName` instead
1263 | - `Module.updateHash` signature changed
1264 | - `Module.sortItems` removed
1265 | - `Module.unbuild` removed
1266 |   - MIGRATION: Use `invalidateBuild` instead
1267 | - `Module.getSourceTypes` added
1268 | - `Module.getRuntimeRequirements` added
1269 | - `Module.size` signature changed
1270 | - `ModuleFilenameHelpers.createFilename` signature changed
1271 | - `ModuleProfile` class added with more data
1272 | - `ModuleReason` removed
1273 | - `ModuleTemplate.hooks` signatures changed
1274 | - `ModuleTemplate.render` signature changed
1275 | - `Compiler.dependencies` removed
1276 |   - MIGRATION: Use `MultiCompiler.setDependencies` instead
1277 | - `MultiModule` removed
1278 | - `MultiModuleFactory` removed
1279 | - `NormalModuleFactory.fileDependencies`, `NormalModuleFactory.contextDependencies` and `NormalModuleFactory.missingDependencies` are now LazySets
1280 | - `RuntimeTemplate` methods now take `runtimeRequirements` arguments
1281 | - `serve` property is removed
1282 | - `Stats.jsonToString` removed
1283 | - `Stats.filterWarnings` removed
1284 | - `Stats.getChildOptions` removed
1285 | - `Stats` helper methods removed
1286 | - `Stats.toJson` signature changed (second argument removed)
1287 | - `ExternalModule.external` removed
1288 | - `HarmonyInitDependency` removed
1289 | - `Dependency.getInitFragments` deprecated
1290 |   - MIGRATION: Use `apply` `initFragements` instead
1291 | - DependencyReference now takes a function to a module instead of a Module
1292 | - HarmonyImportSpecifierDependency.redirectedId removed
1293 |   - MIGRATION: Use `setId` instead
1294 | - acorn 5 -> 7
1295 | - Testing
1296 |   - HotTestCases now runs for multiple targets `async-node` `node` `web` `webworker`
1297 |   - TestCases now also runs for filesystem caching with `store: "instant"` and `store: "pack"`
1298 |   - TestCases now also runs for deterministic module ids
1299 | - Tooling added to order the imports (checked in CI)
1300 | - Chunk name mapping in runtime no longer contains entries when chunk name equals chunk id
1301 | - add `resolvedModuleId` `resolvedModuleIdentifier` and `resolvedModule` to reasons in Stats which point to the module before optimizations like scope hoisting
1302 | - show `resolvedModule` in Stats toString output
1303 | - loader-runner was upgraded: https://github.com/webpack/loader-runner/releases/tag/v3.0.0
1304 | - `file/context/missingDependencies` in `Compilation` are no longer sorted for performance reasons
1305 |   - Do not rely on the order
1306 | - webpack-sources was upgraded: https://github.com/webpack/webpack-sources/releases/tag/v2.0.0-beta.0
1307 | - webpack-command support was removed
1308 | - Use schema-utils@2 for schema validation
1309 | - `Compiler.assetEmitted` has an improved second argument with more information
1310 | - BannerPlugin omits trailing whitespace
1311 | - removed `minChunkSize` option from `LimitChunkCountPlugin`
1312 | - reorganize from javascript related files into sub-directory
1313 |   - `webpack.JavascriptModulesPlugin` -> `webpack.javascript.JavascriptModulesPlugin`
1314 | - Logger.getChildLogger added
1315 | - change the default of entryOnly of the DllPlugin to true
1316 | - remove special request shortening logic and use single relative paths for readable module names
1317 | - allow webpack:// urls in SourceMaps to provided paths relative to webpack root context
1318 | - add API to generate and process CLI arguments targeting webpack configuration
1319 | - add `__system_context__` as context from System.js when using System.js as libraryTarget
1320 | - add bigint support for the DefinePlugin
1321 | - add bigint support for basic evaluations like maths
1322 | - remove ability to modify the compilation hash after the hash has been created
1323 | - remove HotModuleReplacementPlugin multiStep mode
1324 | - `assetInfo` from `emitAsset` will now merge when nested objects or arrays are used
1325 | - `[query]` is now a valid placeholder when for paths based on a `filename` like assets
1326 | - add `Compilation.deleteAsset` to correctly delete an assets and non-shared related assets
1327 | - expose `require("webpack-sources")` as `require("webpack").sources`
1328 | - terser 5


--------------------------------------------------------------------------------
/guides/module-federation.md:
--------------------------------------------------------------------------------
  1 | # Module Federation
  2 | 
  3 | ## Motivation
  4 | 
  5 | Multiple separate builds should form a single application.
  6 | These separate builds should not have build dependencies between each other,
  7 | so they can be developed and deployed individually.
  8 | 
  9 | This is often known as Micro-Frontends, but is not limited to that.
 10 | 
 11 | ## Low-level concepts
 12 | 
 13 | We distinguish between local and remote modules.
 14 | Local modules are normal modules which are part of the current build.
 15 | Remote modules are modules that are not part of the current build and loaded from a so called container at runtime.
 16 | 
 17 | Loading remote modules is considered as async operation.
 18 | When using a remote module these async operation will be placed in the next chunk loading operation(s)
 19 | that is between the remote module and the entrypoint.
 20 | It's not possible to use a remote module without a chunk loading operation.
 21 | 
 22 | A chunk loading operation is usually an `import()`, but older constructs like `require.ensure` or `require([...])` are possible as well.
 23 | 
 24 | A container is created through a container entry, which exposes async access to specified modules.
 25 | The exposed access is separated into two steps: 1. loading the module (async) and 2. evaluating the module (sync).
 26 | 
 27 | Step 1 will done during chunk loading. Step 2 will be done during module evaluation interleaved with other (local and remote) modules.
 28 | This way evaluation order is unaffected by converting a module from local to remote or the other way around.
 29 | 
 30 | Nesting container is possible.
 31 | Containers can use modules from other containers.
 32 | Circular dependencies between container are also possible.
 33 | 
 34 | ### Overriding
 35 | 
 36 | A container is able to flag selected local modules as "overridable".
 37 | A consumer of the container is able to provide "overrides", which are modules that replace one of the overridable module of the container.
 38 | All modules of the container will use the replacement module instead of the local module when the consumer provides one.
 39 | When the consumer doesn't provide a replacement module, all modules of the container will use the local one.
 40 | 
 41 | The container will organize overridable modules in a way that they do not need to be downloaded when they has been overriding by the consumer.
 42 | This usually happens by placing them into separate chunks.
 43 | 
 44 | One the other hand the provider of the replacement modules will only provide async loading functions which allow the container to load replacement modules only when they are needed.
 45 | The provider will organize replacement modules in a way that they do not need to be downloaded when they are not requested by the container at all.
 46 | This usually happens by placing them into separate chunks.
 47 | 
 48 | A "name" is used to identify overridable modules from the container.
 49 | 
 50 | Overrides are provided in a similar way as the container exposes modules, separated into two steps: 1. Loading (async) and 2. evaluating (sync).
 51 | 
 52 | In nested scenarios, where a container uses other containers to load modules from, is overriding a transitive operation.
 53 | Providing overrides to one container will also override these modules in nested container.
 54 | This means that using a container will automatically make all "names" of the overridable modules, part of the overriding interface of the parent container.
 55 | 
 56 | Overrides must be provided before modules of the container are loaded, otherwise behavior is undefined.
 57 | 
 58 | ## High-level concepts
 59 | 
 60 | Each build act as container and also consumes other build as containers.
 61 | This way each build is able to access any other exposed module by loading it from its container.
 62 | 
 63 | Shared modules are modules that are both, overridable and provided as overrides to nested container.
 64 | They usually point to the same module in each build, e. g. the same library.
 65 | 
 66 | ## Building blocks
 67 | 
 68 | ### `OverridablesPlugin` (low level)
 69 | 
 70 | This plugin makes specified modules "overridable".
 71 | A local API (`__webpack_override__`) allows to provide overrides.
 72 | 
 73 | ### `ContainerPlugin` (low level)
 74 | 
 75 | This plugins creates an additional container entry with the specified exposed modules.
 76 | It also uses the `OverridablesPlugin` internally and exposes the `override` API to consumer of the container.
 77 | 
 78 | ### `ContainerReferencePlugin` (low level)
 79 | 
 80 | This plugins adds specified references to containers as externals and allows to import remote modules from these containers.
 81 | It also calls the `override` API of these containers to provide overrides to them.
 82 | Local overrides (via `__webpack_override__` or `override` API when build is also a container) plus specified overrides are provided to all referenced containers.
 83 | 
 84 | ### `ModuleFederationPlugin` (high level)
 85 | 
 86 | This plugins combines `ContainerPlugin` and `ContainerReferencePlugin`.
 87 | Overrides and overridables are combined into a single list of specified shared modules.
 88 | 
 89 | ## Concept goals
 90 | 
 91 | * Any module type supported by webpack should be possible to expose and use.
 92 | * Chunk loading should load everything needed in parallel. (Web: single round-trip to server)
 93 | * Control from consumer to container
 94 |   * Overriding modules is a one-directional operation
 95 |   * Sibling containers cannot override each others modules
 96 | * Concept should be environment-independent
 97 |   * Usable in web, node.js, etc.
 98 | 
 99 | ## Use cases
100 | 
101 | ### Separate builds per page
102 | 
103 | Each page of an SPA is exposed from container build in a separate build.
104 | The application shell is also a separate build referencing all pages as remove modules.
105 | This way each page can be separately deployed.
106 | The application shell is deployed when routes are updated or new routes are added.
107 | The application shell defines commonly used libraries as shared modules to avoid duplication of them in the page builds
108 | 
109 | ### Components library as container
110 | 
111 | Many applications that share a common components library.
112 | This component library is build as container with each component exposed.
113 | Each application consumes components from the component library container.
114 | Changes to the component library can be separately deployed without the need to re-deploy all applications.
115 | The application automatically use the up-to-date version of the component library.
116 | 


--------------------------------------------------------------------------------
/guides/persistent-caching.md:
--------------------------------------------------------------------------------
  1 | Welcome to the persistent caching guide.
  2 | 
  3 | # Opt-in
  4 | 
  5 | First, note that persistent caching is not enabled by default. You have to opt-in using it.
  6 | 
  7 | Why is that?
  8 | webpack tries to favor safety over performance.
  9 | We don't want to enable a feature by default that will improve your performance by 95% but breaks your application/workflow/build in 5%.
 10 | 
 11 | That sounds like it's broken, but believe me, it's not.
 12 | But it requires an extra step by the developer to configure it correctly.
 13 | 
 14 | While serialization and deserialization would work out-of-the-box without extra steps by the developer, the part that may not work out-of-the-box is cache invalidation.
 15 | 
 16 | What's cache invalidation?
 17 | webpack needs to figure out when cache entries are no longer valid and stop using them for the build.
 18 | So this happens when you change a file in your application.
 19 | 
 20 | Example: You change `magic.js`.
 21 | webpack must invalidate the cache entry for `magic.js`.
 22 | The build will process the file again, i. e. runs babel, typescript, whatever, parses the file and runs Code Generation again.
 23 | Then webpack probably also invalidates the cache entry for `bundle.js`,
 24 | and the build will rebuild this file from the contained modules.
 25 | 
 26 | For this webpack tracks `fileDependencies` `contextDependencies` and `missingDependencies` for each Module, and creates a file system snapshot.
 27 | This snapshot is compared with the real file system and when differences are detected a re-build is triggered for that module.
 28 | 
 29 | Then for the cache entry of `bundle.js`, webpack stores an `etag`, which is a hash of all contributors.
 30 | This `etag` is compared and only when it matches the cache entry can be used.
 31 | 
 32 | All this was also required for in-memory caching in webpack 4.
 33 | And all this works out-of-the-box from developer-view without extra configuration.
 34 | For persistent caching in webpack 5, there is a new challenge.
 35 | 
 36 | webpack also needs to invalidate cache entries:
 37 | * when you npm upgrade a loader or plugin
 38 | * when you change your configuration
 39 | * when you change a file that is being read in the configuration
 40 | * when you npm upgrade a dependency that is used in the configuration
 41 | * when you pass different command-line arguments to your build script
 42 | * when you have a custom build script and change that
 43 | 
 44 | Here it becomes tricky.
 45 | webpack is not able to handle all these cases out-of-the-box.
 46 | That's why we've chosen the safe way and made persistent caching an opt-in feature.
 47 | We want you to learn how to enable persistent caching to give you the correct hints.
 48 | We want you to know which configuration needs to be used to handle i. e. your custom build script.
 49 | 
 50 | # Build dependencies, version and name
 51 | 
 52 | To handle these "dependencies" of your build webpack provides three new tools:
 53 | 
 54 | ## Build dependencies
 55 | 
 56 | This is a new configuration option `cache.buildDependencies`, which allows specifying code dependencies of the build process.
 57 | To make it easier webpack takes care of the resolving and following of dependencies of specified values.
 58 | 
 59 | There are two possible types of values: files and directories.
 60 | Directories must end with a slash. Everything else is resolved as a file.
 61 | 
 62 | For directories, the nearest `package.json` is analysed for dependencies.
 63 | For files, we will look into the Node.js module cache to find dependencies.
 64 | 
 65 | Example: The build usually depends on the `lib` folder of `webpack` itself.
 66 | You could specify it this way:
 67 | 
 68 | ``` js
 69 | cache.buildDependencies: {
 70 |     defaultWebpack: ["webpack/lib/"]
 71 | }
 72 | ```
 73 | 
 74 | This invalidates the persistent cache when anything in `webpack/lib` or in dependencies of webpack like `watchpack`, `enhanced-resolved`, etc. changes.
 75 | Coincidentally this is already the default value, so you don't have to specify it.
 76 | 
 77 | Another example: The build usually also depends on your configuration file.
 78 | You could specify it this way:
 79 | 
 80 | ``` js
 81 | cache.buildDependencies: {
 82 |     config: [__filename]
 83 | }
 84 | ```
 85 | 
 86 | The `__filename` variable points to the current file in Node.js.
 87 | 
 88 | This invalidates the persistent cache when your config or anything the config depends on via `require()` changes.
 89 | As your config probably references all used plugins via `require()` they also become build dependencies.
 90 | 
 91 | If your configuration file reads a file via `fs.readFile`, this would **not** become a build dependency, as webpack only follows `require()`.
 92 | You need to add such files to `buildDependencies` manually.
 93 | 
 94 | ## Version
 95 | 
 96 | Some dependencies of your build can't be expressed as references to a file, i. e. values read from a database, environment variables or values passed on the command line.
 97 | For these values, there is a new configuration option `cache.version`.
 98 | 
 99 | `cache.version` is a string. Passing a different string will invalidate the persistent cache.
100 | 
101 | Example: Your config reads the environment variable `GIT_REV` and uses this value with the `DefinePlugin` to embed it into the bundle.
102 | This makes `GIT_REV` a dependency for your build.
103 | You could specify it this way:
104 | 
105 | ``` js
106 | cache: {
107 |     version: `${process.env.GIT_REV}`
108 | }
109 | ```
110 | 
111 | ## Name
112 | 
113 | In some cases, dependencies toggle between multiple different values and invalidating the persistent cache for each value change would be wasteful.
114 | For these values, there is a new configuration options `cache.name`.
115 | 
116 | `cache.name` is a string. Passing a value will create a separate independent persistent cache.
117 | 
118 | `cache.name` is used as the filename of the persistent cache file. Make sure to only pass short and fs-safe names.
119 | 
120 | Example: Your config uses the `--env.target mobile|desktop` argument to creates builds for either mobile or desktop users.
121 | You could specify it this way:
122 | 
123 | ``` js
124 | cache: {
125 |     name: `${env.target}`
126 | }
127 | ```
128 | 
129 | # Performance optimizations
130 | 
131 | Hashing and timestamping a large part of `node_modules` for build and normal dependencies would be pretty expensive, and would slow down webpack a lot.
132 | To avoid this webpack includes a performance optimization that skips over files in `node_modules` by default and uses the `version` and `name` in `package.json` as a source of truth.
133 | 
134 | This optimization will be used for all paths in the configuration option `snapshot.managedPaths`.
135 | It defaults to the `node_modules` directory in which webpack is installed.
136 | 
137 | **Do not edit `node_modules` by hand** when this optimization is enabled.
138 | You can disable it with `cache.managedPaths: []`.
139 | 
140 | When using Yarn PnP another optimization kicks in.
141 | All files in the yarn cache are skipped for hashing and timestamping at all (not even `version` and `name` is tracked).
142 | This is valid as Yarn uses hashes in the file path, so the content of the files is actually immutable and will never change.
143 | 
144 | This is controlled by the configuration option `snapshot.immutablePaths`.
145 | It defaults to the yarn cache in which webpack is installed when Yarn PnP is enabled.
146 | 
147 | We could tell you to not edit the yarn cache by hand, but this is a no-go anyway.
148 | 
149 | # Snapshot types
150 | 
151 | When none of the `snapshot.managedPaths` or `snapshot.immutablePaths` optimization kicks in webpack creates a snapshot, which will later compared with the (updated?) state of the filesystem.
152 | For different use cases there are different types of snapshots:
153 | 
154 | * Timestamp: The modified timestamp is read from filesystem, stored and compared.
155 | * Contenthash: The content of the file is read from filesystem, a hash is stored and compared.
156 | * Timestamp + Contenthash: The modified timestamp and the content of the file is read from filesystem, the timestamp and a hash of the content is stored. The timestamp is compared first and on missmatch the hash is compared.
157 | 
158 | Timestamping is very fast to capture and compare as it only needs a meta data read from filesystem. Contenthashing is slow compared to that, because it need to read the file content from filesystem. But timestamping might invalidate the cache even when the file content is the same, but only the timestamp changed. This can happen because of multiple factors:
159 | 
160 | * git operations always update the timestamp. e. g. fresh clone, changing branches
161 | * save without changes
162 | 
163 | So the question is: Do you expect timestamp changes, while content stays equal? And is the extra performance cost worth it?
164 | 
165 | "Timestamp" makes sense when we expect timestamps to stay equal and the invalidation cost is not that high. Here the faster capture and compare is preferable over rare additional invalidations.
166 | 
167 | "Timestamp + Contenthash" makes sense when we expect timestamps to stay equal, but invalidation cost is so high, that we don't want to risk additional invalidations. The slower capturing is a one time cost we need to accept here. Comparing is usually fast as we expect timestamps to stay equal.
168 | 
169 | "Contenthash" makes sense when we expect timestamps to not stay equal. This saves capturing and comparing the timestamp, that won't be equal anyway.
170 | 
171 | We also need to look at different operations in webpack that need snapshots and how much a cache invalidation costs.
172 | 
173 | Resolving (`snapshot.resolve`): Snapshots are used to determine if a request need to be resolved again.
174 | When the cache can't be used the resolving algorithm runs and figures out the resulting file the request points to.
175 | 
176 | Modules (`snapshot.module`): Snapshots are used to determine if a module need to be rebuild.
177 | When the cache can't be used the loaders has to be executed again and the result has to be parsed.
178 | 
179 | Resolving build dependencies (`snapshot.resolveBuildDependencies`): Snapshots are used to determine if a build dependency request need to be resolved again.
180 | When the cache can't be used the resolving algorithm runs to figure out where the build dependency is on disk.
181 | 
182 | Build Dependencies (`snapshot.buildDependencies`): Snapshots are used to determine if build dependencies have changed.
183 | When the cache can't be used the whole persistent cache will be invalidated as the inner workings of the build have changed.
184 | 
185 | We see that different operations have different costs on cache invalidation. We need to consider that when choosing the snapshot type.
186 | 
187 | Scenario Local development computer:
188 | 
189 | Here we would expect timestamps to usually be equal. So using "Timestamp" for resolving and modules makes sense.
190 | For (resolving) build dependencies "Timestamp + Contenthash" makes sense, as an unnecessary invalidation would be very costy.
191 | 
192 | Scenario CI build:
193 | 
194 | As CI build usually create a fresh git clone of the source code, we expect timestamps to not be equal.
195 | So "Contenthash" makes sense for all operations here
196 | 
197 | Scenario CI build with update:
198 | 
199 | Some CI Servers can be configured to only run a "git pull" instead of a full clone. In this case timestamps would stay equal and the "Timestamp" resp. "Timestamp + Contenthash" method would make sense (similar to a local development computer).
200 | 
201 | # Use the persistent cache
202 | 
203 | Make sure you have read and understood the information above!
204 | 
205 | Here is a typical config to enable the persistent cache:
206 | 
207 | ``` js
208 | cache: {
209 |     type: "filesystem",
210 |     buildDependencies: {
211 |         config: [ __filename ] // you may omit this when your CLI automatically adds it
212 |     }
213 | }
214 | ```
215 | 
216 | ## Watching
217 | 
218 | The persistent cache can be used for single builds and continuous building (watch).
219 | 
220 | When setting `cache.type: "filesystem"` webpack internally enables the filesystem cache and the memory cache in a layered way.
221 | Reading from cache will look into the memory cache first and fallback to filesystem cache.
222 | Writing to cache will write to both caches.
223 | 
224 | The filesystem cache won't directly serialize write requests to disk. It will wait until the compilation process has finished and the compiler is idling.
225 | This happens because serialization and disk writing uses up resources and we don't want to add delay the compilation process.
226 | 
227 | For single builds the workflow is:
228 | 
229 | * Loading cache
230 | * Building
231 | * Emitting
232 | * Display results (stats)
233 | * Persisting cache (if changed)
234 | * Process exits
235 | 
236 | For continuous builds (watch) the workflow is:
237 | 
238 | * Loading cache
239 | * Building
240 | * Emitting
241 | * Display results (stats)
242 | * Attach filesystem watchers
243 | * Wait `cache.idleTimeoutForInitialStore`
244 | * Persisting cache (if changed)
245 | * On change:
246 |   * Building
247 |   * Emitting
248 |   * Display results (stats)
249 |   * Wait `cache.idleTimeout`
250 |   * Persisting cache (if changed)
251 | 
252 | You see the two new configuration options `cache.idleTimeout` and `cache.idleTimeoutForInitialStore` which control how long the compiler has to idle before cache is persisted.
253 | `cache.idleTimeout` defaults to 60s and `cache.idleTimeoutForInitialStore` defaults to 0s.
254 | As serialization blocks the event loop, no change is detected while the cache is serialized.
255 | The delay tries to avoid recompilation delay in watch mode due to fast-paced editing of files while trying to keep the persistent cache fresh for the next cold start.
256 | It's a trade-off, feel free to choose a value that fits your workflow. Smaller values shorten cold startup time and increase the risk of delayed rebuilds. Bigger values can increase cold startup time and reduce the risk of delayed rebuilds.
257 | 
258 | ## Error handling
259 | 
260 | The persistent cache recovers from any error by either dropping the whole cache and doing a fresh build or by omitting the offending cache entry and leaving this item uncached.
261 | 
262 | Warnings will be emitted in such cases with the webpack infrastructure logger.
263 | See `infrastructureLogging` configuration option for details.
264 | By default they will be printed to stderr.
265 | 
266 | ## Garbage collection
267 | 
268 | Unused cache entries are removed from the cache after 1 month.
269 | 
270 | ## Splitting in files
271 | 
272 | The persistent caching system will automatically distribute cache entries into cache files aiming for the following:
273 | 
274 | * Unused and used cache entries should not be together in a cache file.
275 | * Cache files should be at least 1 MB big.
276 | * A maximum of 50,000 fresh cache items are together in a cache file.
277 | 
278 | After a short while of usage this should result in:
279 | 
280 | * No cache items are deserialized that are not used
281 | * Cache items are grouped to benefit from object deduplication
282 | * Too big files are not created that would be expensive to rewrite
283 | 
284 | ---
285 | 
286 | # Details
287 | 
288 | The following information is not needed for normal usage.
289 | 
290 | ## Guideline for higher-level tools using webpack
291 | 
292 | A tool that wraps webpack may choose different defaults.
293 | When it doesn't allow to use a custom config to extend webpack, it could switch the persistent cache on by default as it has full control over all build dependencies.
294 | 
295 | ## Guideline for CLIs
296 | 
297 | A CLI using webpack could add some build dependencies by default, which is not possible for the webpack itself.
298 | 
299 | * It should set `cache.buildDependencies.defaultConfig` to the used config file by default.
300 | * It should append the command line arguments to `cache.version`
301 | * It may add a note to `cache.name` when command line arguments are used
302 | 
303 | ## Debug information
304 | 
305 | With the following config additional debug information will be emitted:
306 | 
307 | ``` js
308 | infrastructureLogging: {
309 |     debug: /webpack\.cache/
310 | }
311 | ```
312 | 
313 | ## Internal workflow
314 | 
315 | * webpack reads the cache file.
316 |   * There is no cache file -> build without cache
317 |   * `version` in the cache file doesn't match the `cache.version` -> build without cache
318 | * webpack compares the `resolve snapshot` with the filesystem
319 |   * It does match -> continue below
320 |   * It doesn't match:
321 |     * Resolve all `resolve results` again
322 |       * It doesn't match -> build without cache
323 |       * It does match -> continue below
324 | * webpack compares the `build dependencies snapshot` with the filesystem
325 |   * It doesn't match -> build without cache
326 |   * It does match -> continue below
327 | * cache metadata is deserialized
328 | * build runs (with or without cache)
329 |   * accessing cache entries causes cache files to be deserialized
330 |   * build dependencies are tracked
331 |     * from `cache.buildDependencies`
332 |     * from used loaders
333 |     * defaults
334 | * new build dependencies are resolved
335 |   * `resolve dependencies` are tracked
336 |   * `resolve results` are tracked
337 | * a snapshot from all new `resolve dependencies` is created
338 |   * If there is already a snapshot for that, both are merged
339 | * a snapshot from all new `build dependencies` is created
340 |   * If there is already a snapshot for that, both are merged
341 | * persistent cache files are serialized to disk
342 | 
343 | ## Serialization
344 | 
345 | All classes that should support serialization need to have a serializer registered:
346 | 
347 | ``` js
348 | webpack.util.serialization.register(Constructor, request, name, serializer);
349 | ```
350 | 
351 | `Constructor` should be a class or constructor function.
352 | For any object that should be serialized `object.constructor` will be used to find a serializer.
353 | 
354 | `request` will be used to load the module that calls `register`.
355 | It should point to the current module.
356 | It will be used this way: `require(request)`.
357 | 
358 | `name` is used to differentiate multiple `register` calls with the same `request`.
359 | 
360 | `serializer` is an object with at least two methods `serialize` and `deserialize`.
361 | 
362 | `serializer.serialize(object, context)` is called when an object should be serialized.
363 | `context` is an object that contains at least a `write(anything)` method.
364 | This method writes something into the output stream.
365 | The passed value will be serialized too.
366 | 
367 | `serializer.deserialize(context)` is called when a serialized object should be deserialized.
368 | `context` is an object that contains at least a `read(): anything` method.
369 | This method deserializes something from the input stream.
370 | `deserialize` must return the deserialized object.
371 | 
372 | `serialize` and `deserialize` should read and write the same objects in the same order.
373 | 
374 | Example:
375 | 
376 | ``` js
377 | // some-module/lib/MyClass.js
378 | class MyClass {
379 |     constructor(a, b) {
380 |         this.a = a;
381 |         this.b = b;
382 |         this.c = undefined;
383 |     }
384 | }
385 | 
386 | register(MyClass, "some-module/lib/MyClass", null, {
387 |     serialize(obj, { write }) {
388 |         write(obj.a);
389 |         write(obj.b);
390 |         write(obj.c);
391 |     },
392 |     deserialize({ read }) {
393 |         const obj = new MyClass(read(), read());
394 |         obj.c = read();
395 |         return obj;
396 |     }
397 | });
398 | ```
399 | 
400 | You can expect serializer for primitive types and basic javascript classes to be already registered, i. e. string, number, Array, Set, Map, RegExp, plain objects, Error.
401 | 


--------------------------------------------------------------------------------