271 lines
8.3 KiB
Markdown
271 lines
8.3 KiB
Markdown
[tests]: https://img.shields.io/circleci/project/github/shellscape/webpack-manifest-plugin.svg
|
|
[tests-url]: https://circleci.com/gh/shellscape/webpack-manifest-plugin
|
|
[cover]: https://codecov.io/gh/shellscape/webpack-manifest-plugin/branch/master/graph/badge.svg
|
|
[cover-url]: https://codecov.io/gh/shellscape/webpack-manifest-plugin
|
|
[size]: https://packagephobia.now.sh/badge?p=webpack-manifest-plugin
|
|
[size-url]: https://packagephobia.now.sh/result?p=webpack-manifest-plugin
|
|
|
|
<div align="center">
|
|
<img width="256" src="https://raw.githubusercontent.com/shellscape/webpack-manifest-plugin/master/assets/manifest.svg?sanitize=true" alt="webpack-manfiest-plugin"><br/><br/>
|
|
</div>
|
|
|
|
[![tests][tests]][tests-url]
|
|
[![cover][cover]][cover-url]
|
|
[![size][size]][size-url]
|
|
[](https://liberamanifesto.com)
|
|
|
|
# webpack-manifest-plugin
|
|
|
|
A Webpack plugin for generating an asset manifest.
|
|
|
|
:heart: Please consider [Sponsoring my work](https://github.com/sponsors/shellscape)
|
|
|
|
## Requirements
|
|
|
|
`webpack-manifest-plugin` is an [evergreen 🌲](./.github/FAQ.md#what-does-evergreen-mean) module.
|
|
|
|
This module requires an [Active LTS](https://github.com/nodejs/Release) Node version (v10.0.0+) and Webpack v4.44.0+.
|
|
|
|
## Contributing
|
|
|
|
This repository leverages [pnpm](https://pnpm.js.org/) for dependency management.
|
|
|
|
To begin, please install `pnpm`:
|
|
|
|
```console
|
|
$ npm install pnpm -g
|
|
```
|
|
|
|
## Install
|
|
|
|
Using npm:
|
|
|
|
```console
|
|
npm install webpack-nano webpack-manifest-plugin --save-dev
|
|
```
|
|
|
|
_Note: We recommend using [webpack-nano](https://github.com/shellscape/webpack-nano), a very tiny, very clean webpack CLI._
|
|
|
|
## Usage
|
|
|
|
Create a `webpack.config.js` file:
|
|
|
|
```js
|
|
const { WebpackManifestPlugin } = require('webpack-manifest-plugin');
|
|
const options = { ... };
|
|
|
|
module.exports = {
|
|
// an example entry definition
|
|
entry: [ 'app.js' ],
|
|
...
|
|
plugins: [
|
|
new WebpackManifestPlugin(options)
|
|
]
|
|
};
|
|
```
|
|
|
|
And run `webpack`:
|
|
|
|
```console
|
|
$ npx wp
|
|
```
|
|
|
|
With the default options, the example above will create a `manifest.json` file in the output directory for the build. The manifest file will contain a map of source filenames to the corresponding build output file. e.g.
|
|
|
|
```json
|
|
{
|
|
"dist/batman.js": "dist/batman.1234567890.js",
|
|
"dist/joker.js": "dist/joker.0987654321.js"
|
|
}
|
|
```
|
|
|
|
### Options
|
|
|
|
### `basePath`
|
|
|
|
Type: `String`<br>
|
|
Default: `''`
|
|
|
|
Specifies a path prefix for all keys in the manifest. Useful for including your output path in the manifest.
|
|
|
|
### `fileName`
|
|
|
|
Type: `String`<br>
|
|
Default: `manifest.json`
|
|
|
|
Specifies the file name to use for the resulting manifest. By default the plugin will emit `manifest.json` to your output directory. Passing an absolute path to the `fileName` option will override both the file name and path.
|
|
|
|
### `filter`
|
|
|
|
Type: `Function`<br>
|
|
Default: `undefined`
|
|
|
|
Allows filtering the files which make up the manifest. The passed function should match the signature of `(file: FileDescriptor) => Boolean`. Return `true` to keep the file, `false` to remove the file.
|
|
|
|
### `generate`
|
|
|
|
Type: `Function`<br>
|
|
Default: `undefined`
|
|
|
|
A custom `Function` to create the manifest. The passed function should match the signature of `(seed: Object, files: FileDescriptor[], entries: string[]) => Object` and can return anything as long as it's serialisable by `JSON.stringify`.
|
|
|
|
### `map`
|
|
|
|
Type: `Function`<br>
|
|
Default: `undefined`
|
|
|
|
Allows modifying the files which make up the manifest. The passed function should match the signature of `(file: FileDescriptor) => FileDescriptor` where an object matching `FileDescriptor` is returned.
|
|
|
|
### `publicPath`
|
|
|
|
Type: `String`<br>
|
|
Default: `<webpack-config>.output.publicPath`
|
|
|
|
A path prefix that will be added to values of the manifest.
|
|
|
|
### `removeKeyHash`
|
|
|
|
Type: `RegExp | false`<br>
|
|
Default: `/([a-f0-9]{32}\.?)/gi`
|
|
|
|
If set to a valid `RegExp`, removes hashes from manifest keys. e.g.
|
|
|
|
```json
|
|
{
|
|
"index.c5a9bff71fdfed9b6046.html": "index.c5a9bff71fdfed9b6046.html"
|
|
}
|
|
```
|
|
|
|
```json
|
|
{
|
|
"index.html": "index.c5a9bff71fdfed9b6046.html"
|
|
}
|
|
```
|
|
|
|
The default value for this option is a regular expression targeting Webpack's [default md5 hash](https://webpack.js.org/configuration/output/#outputhashfunction). To target other hashing functions / algorithms, set this option to an appropriate `RegExp`. To disable replacing the hashes in key names, set this option to `false`.
|
|
|
|
### `seed`
|
|
|
|
Type: `Object`<br>
|
|
Default: `{}`
|
|
|
|
A cache of key/value pairs used to seed the manifest. This may include a set of [custom key/value](https://developer.mozilla.org/en-US/Add-ons/WebExtensions/manifest.json) pairs to include in your manifest, or may be used to combine manifests across compilations in [multi-compiler mode](https://github.com/webpack/webpack/tree/master/examples/multi-compiler). To combine manifests, pass a shared seed object to each compiler's `WebpackManifestPlugin` instance.
|
|
|
|
### `serialize`
|
|
|
|
Type: `Function(Object) => string`<br>
|
|
Default: `undefined`
|
|
|
|
A `Function` which can be leveraged to serialize the manifest in a different format than json. e.g. `yaml`.
|
|
|
|
### `sort`
|
|
|
|
Type: `Function`<br>
|
|
Default: `undefined`
|
|
|
|
Allows sorting the files which make up the manifest. The passed function should match the signature of `(fileA: FileDescriptor, fileB: FileDescriptor) => Number`. Return `0` to indicate no change, `-1` to indicate the file should be moved to a lower index, and `1` to indicate the file shoud be moved to a higher index.
|
|
|
|
### `useEntryKeys`
|
|
|
|
Type: `Boolean`<br>
|
|
Default: `false`
|
|
|
|
If `true`, the keys specified in the `entry` property will be used as keys in the manifest. No file extension will be added (unless specified as part of an `entry` property key).
|
|
|
|
### `useLegacyEmit`
|
|
|
|
Type: `Boolean`<br>
|
|
Default: `false`
|
|
|
|
If `true`, the manifest will be written on the deprecated webpack `emit` hook to be compatible with not yet updated webpack plugins.
|
|
|
|
A lot of webpack plugins are not yet updated to match the new webpack 5 API. This is a problem when other plugins use the deprecated `emit` hook. The manifest will be written before these other plugins and thus files are missing on the manifest.
|
|
|
|
### `writeToFileEmit`
|
|
|
|
Type: `Boolean`<br>
|
|
Default: `false`
|
|
|
|
If `true`, will emit the manifest to the build directory _and_ in memory for compatibility with `webpack-dev-server`.
|
|
|
|
## Manifest File Descriptor
|
|
|
|
This plugin utilizes the following object structure to work with files. Many options for this plugin utilize the structure below.
|
|
|
|
```ts
|
|
{
|
|
chunk?: Chunk;
|
|
isAsset: boolean;
|
|
isChunk: boolean;
|
|
isInitial: boolean;
|
|
isModuleAsset: boolean;
|
|
name: string | null;
|
|
path: string;
|
|
}
|
|
```
|
|
|
|
### `chunk`
|
|
|
|
Type: [`Chunk`](https://github.com/webpack/webpack/blob/master/lib/Chunk.js)
|
|
|
|
Only available if `isChunk` is `true`
|
|
|
|
### `isInitial`
|
|
|
|
Type: `Boolean`
|
|
|
|
Is required to run you app. Cannot be `true` if `isChunk` is `false`.
|
|
|
|
### `isModuleAsset`
|
|
|
|
Type: `Boolean`
|
|
|
|
Is required by a module. Cannot be `true` if `isAsset` is `false`.
|
|
|
|
## Compiler Hooks
|
|
|
|
This plugin supports the following hooks via the `getCompilerHooks` export; `afterEmit`, `beforeEmit`. These hooks can be useful, e.g. changing manifest contents before emitting to disk.
|
|
|
|
### `getCompilerHooks`
|
|
|
|
Returns: `{ afterEmit: SyncWaterfallHook, beforeEmit: SyncWaterfallHook }`
|
|
|
|
### `assetHookStage`
|
|
|
|
Type: `Number`
|
|
Default: `Infinity`
|
|
|
|
If you need to consume the output of this plugin in another plugin, it can be useful to adjust the stage at which the manifest is generated. Pass a new stage to `assetHookStage` to change when the manifest is generated. See the [docs on `processAssets`](https://webpack.js.org/api/compilation-hooks/#list-of-asset-processing-stages) for more detail.
|
|
|
|
Note: any files added to the compilation after the stage specified will not be included in the manifest.
|
|
|
|
#### Usage
|
|
|
|
```js
|
|
const { getCompilerHooks } = require('webpack-manifest-plugin');
|
|
|
|
class BatmanPlugin {
|
|
apply(compiler) {
|
|
const { beforeEmit } = getCompilerHooks(compiler);
|
|
|
|
beforeEmit.tap('BatmanPlugin', (manifest) => {
|
|
return { ...manifest, name: 'hello' };
|
|
});
|
|
}
|
|
}
|
|
```
|
|
|
|
## Notes
|
|
|
|
- If using this plugin with `webpack-clean` and `webpack-dev-server`, please review [this issue](https://github.com/shellscape/webpack-manifest-plugin/issues/267).
|
|
|
|
## Attiribution
|
|
|
|
Special thanks to [Dane Thurber](https://github.com/danethurber), the original author of this plugin, without whom this plugin would not exist.
|
|
|
|
## Meta
|
|
|
|
[CONTRIBUTING](./.github/CONTRIBUTING.md)
|
|
|
|
[LICENSE (MIT)](./LICENSE)
|