Skip to content

docs: update #157

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Apr 27, 2020
Merged

docs: update #157

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0cbae02
docs: update
alexander-akait Apr 25, 2020
bbf0785
docs: update
alexander-akait Apr 25, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
204 changes: 137 additions & 67 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,11 +47,16 @@ Default: `undefined`

Test to match files against.

**webpack.config.js**

```js
// in your webpack.config.js
new CompressionPlugin({
test: /\.js(\?.*)?$/i,
});
module.exports = {
plugins: [
new CompressionPlugin({
test: /\.js(\?.*)?$/i,
}),
],
};
```

### `include`
Expand All @@ -61,11 +66,16 @@ Default: `undefined`

Files to include.

**webpack.config.js**

```js
// in your webpack.config.js
new CompressionPlugin({
include: /\/includes/,
});
module.exports = {
plugins: [
new CompressionPlugin({
include: /\/includes/,
}),
],
};
```

### `exclude`
Expand All @@ -75,11 +85,16 @@ Default: `undefined`

Files to exclude.

**webpack.config.js**

```js
// in your webpack.config.js
new CompressionPlugin({
exclude: /\/excludes/,
});
module.exports = {
plugins: [
new CompressionPlugin({
exclude: /\/excludes/,
}),
],
};
```

### `cache`
Expand All @@ -94,22 +109,32 @@ The default path to cache directory: `node_modules/.cache/compression-webpack-pl

Enable/disable file caching.

**webpack.config.js**

```js
// in your webpack.config.js
new CompressionPlugin({
cache: true,
});
module.exports = {
plugins: [
new CompressionPlugin({
cache: true,
}),
],
};
```

#### `String`

Enable file caching and set path to cache directory.

**webpack.config.js**

```js
// in your webpack.config.js
new CompressionPlugin({
cache: 'path/to/cache',
});
module.exports = {
plugins: [
new CompressionPlugin({
cache: 'path/to/cache',
}),
],
};
```

### `filename`
Expand All @@ -128,29 +153,35 @@ The target asset filename.
`[ext]` is replaced with the extension of the original asset.
`[query]` is replaced with the query.

**webpack.config.js**

```js
// in your webpack.config.js
new CompressionPlugin({
filename: '[path].gz[query]',
});

new CompressionPlugin({
filename: '[dir][name].gz[ext][query]',
});
module.exports = {
plugins: [
new CompressionPlugin({
filename: '[path].gz[query]',
}),
],
};
```

#### `Function`

**webpack.config.js**

```js
// in your webpack.config.js
new CompressionPlugin({
filename(info) {
// info.file is the original asset filename
// info.path is the path of the original asset
// info.query is the query
return `${info.path}.gz${info.query}`;
},
});
module.exports = {
plugins: [
new CompressionPlugin({
filename(info) {
// info.file is the original asset filename
// info.path is the path of the original asset
// info.query is the query
return `${info.path}.gz${info.query}`;
},
}),
],
};
```

### `algorithm`
Expand All @@ -164,24 +195,34 @@ The compression algorithm/function.

The algorithm is taken from [zlib](https://nodejs.org/api/zlib.html).

**webpack.config.js**

```js
// in your webpack.config.js
new CompressionPlugin({
algorithm: 'gzip',
});
module.exports = {
plugins: [
new CompressionPlugin({
algorithm: 'gzip',
}),
],
};
```

#### `Function`

Allow to specify a custom compression function.

**webpack.config.js**

```js
// in your webpack.config.js
new CompressionPlugin({
algorithm(input, compressionOptions, callback) {
return compressionFunction(input, compressionOptions, callback);
},
});
module.exports = {
plugins: [
new CompressionPlugin({
algorithm(input, compressionOptions, callback) {
return compressionFunction(input, compressionOptions, callback);
},
}),
],
};
```

### `compressionOptions`
Expand All @@ -194,11 +235,16 @@ If you use custom function for the `algorithm` option, the default value is `{}`
Compression options.
You can find all options here [zlib](https://nodejs.org/api/zlib.html#zlib_class_options).

**webpack.config.js**

```js
// in your webpack.config.js
new CompressionPlugin({
compressionOptions: { level: 1 },
});
module.exports = {
plugins: [
new CompressionPlugin({
compressionOptions: { level: 1 },
}),
],
};
```

### `threshold`
Expand All @@ -208,11 +254,16 @@ Default: `0`

Only assets bigger than this size are processed. In bytes.

**webpack.config.js**

```js
// in your webpack.config.js
new CompressionPlugin({
threshold: 8192,
});
module.exports = {
plugins: [
new CompressionPlugin({
threshold: 8192,
}),
],
};
```

### `minRatio`
Expand All @@ -225,11 +276,16 @@ Example: you have `image.png` file with 1024b size, compressed version of file h
In other words assets will be processed when the `Compressed Size / Original Size` value less `minRatio` value.
You can use `1` value to process assets that are smaller than the original. Use a value of Number.MAX_SAFE_INTEGER to process all assets even if they are larger than the original (useful when you are pre-zipping all assets for AWS)

**webpack.config.js**

```js
// in your webpack.config.js
new CompressionPlugin({
minRatio: 0.8,
});
module.exports = {
plugins: [
new CompressionPlugin({
minRatio: 0.8,
}),
],
};
```

### `deleteOriginalAssets`
Expand All @@ -239,11 +295,16 @@ Default: `false`

Whether to delete the original assets or not.

**webpack.config.js**

```js
// in your webpack.config.js
new CompressionPlugin({
deleteOriginalAssets: true,
});
module.exports = {
plugins: [
new CompressionPlugin({
deleteOriginalAssets: true,
}),
],
};
```

## Examples
Expand Down Expand Up @@ -283,20 +344,25 @@ module.exports = {

[Brotli](https://en.wikipedia.org/wiki/Brotli) is a compression algorithm originally developed by Google, and offers compression superior to gzip.

Node 11.7.0 and later has [native support](https://nodejs.org/api/zlib.html#zlib_zlib_createbrotlicompress_options) for Brotli compression in its zlib module.
Node 10.16.0 and later has [native support](https://nodejs.org/api/zlib.html#zlib_zlib_createbrotlicompress_options) for Brotli compression in its zlib module.

We can take advantage of this built-in support for Brotli in Node 11.7.0 and later by just passing in the appropriate `algorithm` to the CompressionPlugin:

**webpack.config.js**

```js
const zlib = require('zlib');

module.exports = {
plugins: [
new CompressionPlugin({
filename: '[path].br[query]',
algorithm: 'brotliCompress',
test: /\.(js|css|html|svg)$/,
compressionOptions: { level: 11 },
compressionOptions: {
// zlib’s `level` option matches Brotli’s `BROTLI_PARAM_QUALITY` option.
level: 11,
},
threshold: 10240,
minRatio: 0.8,
deleteOriginalAssets: false,
Expand All @@ -305,13 +371,15 @@ module.exports = {
};
```

**N.B.:** The `level` option matches `BROTLI_PARAM_QUALITY` [for Brotli-based streams](https://nodejs.org/api/zlib.html#zlib_for_brotli_based_streams)
**Note** The `level` option matches `BROTLI_PARAM_QUALITY` [for Brotli-based streams](https://nodejs.org/api/zlib.html#zlib_for_brotli_based_streams)

### Multiple compressed versions of assets for different algorithm

**webpack.config.js**

```js
const zlib = require('zlib');

module.exports = {
plugins: [
new CompressionPlugin({
Expand All @@ -325,7 +393,9 @@ module.exports = {
filename: '[path].br[query]',
algorithm: 'brotliCompress',
test: /\.(js|css|html|svg)$/,
compressionOptions: { level: 11 },
compressionOptions: {
level: 11,
},
threshold: 10240,
minRatio: 0.8,
}),
Expand Down