Gzipper

A tool for compressing files by means of Deflate, Brotli, gzip, Zopfli and zstd algorithms, works seamlessly with many CLI UI tools (Angular CLI, Vue CLI, create-react-app).

The flexibility of the algorithms could be extended by many options, including the --gzip-level, --gzip-strategy, --gzip-memory-level, --brotli-param-mode, --brotli-quality, --brotli-size-hint. All options can be declared via ENV variables (ENV variables have higher priority over CLI arguments).

You can enable --verbose mode for better visual representation, customize your file output using --output-file-format or compress with --incremental option if you have a lot of files that rarely change.

By default gzipper compress all the files but you could use --include or --exclude options for flexibility.

• Gzipper
  • Install
  • Usage
    • gzipper
    • compress|c
    • cache
  • Examples
    • CLI
    • Node.js Module
  • Options
    • compress|c
      • --incremental
      • -v, --verbose
      • -e, --exclude <extensions>
      • -i, --include <extensions>
      • -t, --threshold <number>
      • --gzip
      • --deflate
      • --brotli
      • --zopfli
      • --zstd
      • --gzip-level <number>
      • --gzip-memory-level <number>
      • --gzip-strategy <number>
      • --deflate-level <number>
      • --deflate-memory-level <number>
      • --deflate-strategy <number>
      • --brotli-param-mode <value>
      • --brotli-quality <number>
      • --brotli-size-hint <number>
      • --zopfli-num-iterations <number>
      • --zopfli-block-splitting
      • --zopfli-block-splitting-max <number>
      • --zstd-level <number>
      • --output-file-format <value>
      • --remove-larger
      • --skip-compressed
      • --workers <number>
      • --no-color
    • cache
      • purge
      • size
  • Changelog
  • Contribution
  • Support
  • Prerequisites

Install

• Globally

  npm i gzipper -g

• Locally to devDependencies.

  npm i gzipper -D

Usage

gzipper

1Usage: gzipper [options] [command]
2
3Options:
4  -V, --version                             output the version number
5  -h, --help                                display help for command
6
7Commands:
8  compress|c [options] <path> [outputPath]  compress selected path and optionally set output directory
9  cache                                     manipulations with cache
10  help [command]                            display help for command

compress|c

1Usage: gzipper compress|c [options] <path> [outputPath]
2
3compress selected path and optionally set output directory
4
5Options:
6  -v, --verbose                          detailed level of logs
7  --incremental                          incremental compression
8  -e, --exclude <extensions>             exclude file extensions from compression, example: jpeg,jpg...
9  -i, --include <extensions>             include file extensions for compression, example: js,css,html...
10  -t, --threshold <number>               exclude assets smaller than this byte size. 0 (default)
11  --deflate                              enable deflate compression
12  --brotli                               enable brotli compression
13  --gzip                                 enable gzip compression
14  --zopfli                               enable zopfli compression
15  --zstd                                 enable zstd compression
16  --gzip-level <number>                  gzip compression level 6 (default), 0 (no compression) - 9 (best compression)
17  --gzip-memory-level <number>           amount of memory which will be allocated for gzip compression 8 (default), 1 (minimum memory) - 9 (maximum memory)
18  --gzip-strategy <number>               gzip compression strategy 0 (default), 1 (filtered), 2 (huffman only), 3 (RLE), 4 (fixed)
19  --deflate-level <number>               deflate compression level 6 (default), 0 (no compression) - 9 (best compression)
20  --deflate-memory-level <number>        amount of memory which will be allocated for deflate compression 8 (default), 1 (minimum memory) - 9 (maximum memory)
21  --deflate-strategy <number>            deflate compression strategy 0 (default), 1 (filtered), 2 (huffman only), 3 (RLE), 4 (fixed)
22  --brotli-param-mode <value>            default, text (for UTF-8 text), font (for WOFF 2.0 fonts)
23  --brotli-quality <number>              brotli compression quality 11 (default), 0 - 11
24  --brotli-size-hint <number>            expected input size 0 (default)
25  --zopfli-num-iterations <number>       maximum amount of times to rerun forward and backward pass to optimize LZ77 compression cost
26  --zopfli-block-splitting               splits the data in multiple deflate blocks with optimal choice for the block boundaries
27  --zopfli-block-splitting-max <number>  maximum amount of blocks to split into (0 for unlimited, but this can give extreme results that hurt compression on some files)
28  --zstd-level <number>                  zstd compression level 1 (default), 5 (best compression)
29  --output-file-format <value>           output file format with default artifacts [filename].[ext].[compressExt]
30  --remove-larger                        remove compressed files if they larger than uncompressed originals
31  --skip-compressed                      skip compressed files if they already exist
32  --workers <number>                     numbers of workers which will be spawned, system CPU cores count (default)
33  --no-color                             disable logger colorful messages
34  -h, --help                             display help for command

cache

1Usage: gzipper cache [options] [command]
2
3manipulations with cache
4
5Options:
6  -h, --help      display help for command
7
8Commands:
9  purge           purge cache storage
10  size            size of cached resources
11  help [command]  display help for command

Examples

CLI

• Globally usage

  gzipper compress [options] <path> [outputPath]

• Locally usage

  1. Add module to scripts in your package.json and run compress command npm run compress

     1  "scripts": {
     2    "gzipper": "gzipper",
     3    "compress": "gzipper compress ./src"
     4  }

  2. Use npx command

     1  "scripts": {
     2    "compress": "npx gzipper compress ./src"
     3  }

• UI build tools (e.g. Angular CLI)

  1  "scripts": {
  2    "build": "ng build && gzipper compress ./src"
  3  }

• Compress files to a certain directory ./dist (folders structure inside src will be saved)

  1  "scripts": {
  2    "compress": "gzipper compress ./src ./dist"
  3  }

• Compress files to very deep folder ./very/deep/folder/dist (all folders will be automatically created if not exist)

  1  "scripts": {
  2    "compress": "gzipper compress ./src ./very/deep/folder/dist"
  3  }

• Compress a single file

  1  "scripts": {
  2    "compress": "gzipper compress ./src/awesomeness.txt"
  3  }

Node.js Module

1import { Compress } from "gzipper";
2const gzip = new Compress('./src', './dist', {
3  verbose: true,
4  brotli: true,
5});
6
7try {
8  const files = await gzip.run();
9  console.info('Compressed files: ', files);
10} catch (err) {
11  console.error(err);
12}

Options

compress|c

CLI argument	ENV variable
--incremental	GZIPPER_INCREMENTAL (0 or 1)
-v, --verbose	GZIPPER_VERBOSE (0 or 1)
-e, --exclude <extensions>	GZIPPER_EXCLUDE
-i, --include <extensions>	GZIPPER_INCLUDE
-t, --threshold <number>	GZIPPER_THRESHOLD
--gzip	GZIPPER_GZIP (0 or 1)
--deflate	GZIPPER_DEFLATE (0 or 1)
--brotli	GZIPPER_BROTLI (0 or 1)
--zopfli	GZIPPER_ZOPFLI (0 or 1)
--zstd	GZIPPER_ZSTD (0 or 1)
--gzip-level <number>	GZIPPER_GZIP_LEVEL
--gzip-memory-level <number>	GZIPPER_GZIP_MEMORY_LEVEL
--gzip-strategy <number>	GZIPPER_GZIP_STRATEGY
--deflate-level <number>	GZIPPER_DEFLATE_LEVEL
--deflate-memory-level <number>	GZIPPER_DEFLATE_MEMORY_LEVEL
--deflate-strategy <number>	GZIPPER_DEFLATE_STRATEGY
--brotli-param-mode <value>	GZIPPER_BROTLI_PARAM_MODE
--brotli-quality <number>	GZIPPER_BROTLI_QUALITY
--brotli-size-hint <number>	GZIPPER_BROTLI_SIZE_HINT
--zopfli-num-iterations <number>	GZIPPER_ZOPFLI_NUM_ITERATIONS
--zopfli-block-splitting	GZIPPER_ZOPFLI_BLOCK_SPLITTING (0 or 1)
--zopfli-block-splitting-max <number>	GZIPPER_ZOPFLI_BLOCK_SPLITTING_MAX
--zstd-level <number>	GZIPPER_ZSTD_LEVEL
--output-file-format <value>	GZIPPER_OUTPUT_FILE_FORMAT
--remove-larger	GZIPPER_REMOVE_LARGER (0 or 1)
--skip-compressed	GZIPPER_SKIP_COMPRESSED (0 or 1)
--workers <number>	GZIPPER_WORKERS
--no-color	GZIPPER_NO_COLOR or NO_COLOR (0 or 1)

ENV variables have higher priority over CLI arguments.

--incremental

gzipper c ./src --incremental

A special type of compression that significantly decreases the time of compression (on the second run) if you have a lot of big and rarely updated files. It creates a .gzipper folder with pre-compressed files (cache) and config that stores all necessary metadata (.gzipperconfig).

-v, --verbose

gzipper c ./src --verbose

Get more information about executed work. (Could increase time of compression because of gathering additional metrics)

-e, --exclude <extensions>

gzipper c ./src --exclude jpeg,jpg,png,ico

Exclude file extensions from compression. Compression extensions br, gz, zz and zst are excluded by default.

-i, --include <extensions>

gzipper c ./src --include js,css,html

Include file extensions for compression (exclude others).

-t, --threshold <number>

gzipper c ./src --threshold 900

Exclude assets smaller than this byte size. Default is 0 byte.

--gzip

gzipper c ./src --gzip

Enable gzip compression. (default behavior)

--deflate

gzipper c ./src --deflate

Enable Deflate compression.

--brotli

gzipper c ./src --brotli

Enable Brotli compression.

--zopfli

gzipper c ./src --zopfli

Enable Zopfli compression.

--zstd

gzipper c ./src --zstd

Enable Zstandard compression.

--gzip-level <number>

gzipper c ./src --gzip-level 8

gzip compression level: 6 (default), 0 (no compression) - 9 (best compression). Only for --gzip.

--gzip-memory-level <number>

gzipper c ./src --gzip-memory-level 2

Amount of memory that will be allocated for gzip compression: 8 (default), 1 (minimum memory) - 9 (maximum memory). Only for --gzip.

--gzip-strategy <number>

gzipper c ./src --gzip-strategy 3

gzip compression strategy: 0 (default), 1 (filtered), 2 (huffman only), 3 (RLE), 4 (fixed). Only for --gzip.

--deflate-level <number>

gzipper c ./src --deflate-level 8

Deflate compression level: 6 (default), 0 (no compression) - 9 (best compression). Only for --deflate.

--deflate-memory-level <number>

gzipper c ./src --deflate-memory-level 2

Amount of memory that will be allocated for deflate compression: 8 (default), 1 (minimum memory) - 9 (maximum memory). Only for --deflate.

--deflate-strategy <number>

gzipper c ./src --deflate-strategy 3

Deflate compression strategy: 0 (default), 1 (filtered), 2 (huffman only), 3 (RLE), 4 (fixed). Only for --deflate.

--brotli-param-mode <value>

gzipper c ./src --brotli-param-mode text

Available values are: text (for UTF-8 text, default) and font (for WOFF 2.0 fonts). Only for --brotli.

--brotli-quality <number>

gzipper c ./src --brotli-quality 10

Brotli compression quality: 11 (default), 0 - 11. Only for --brotli.

--brotli-size-hint <number>

gzipper c ./src --brotli-size-hint 6

Estimated total input size for all files to compress: 0 (default, which means that the size is unknown). Only for --brotli.

--zopfli-num-iterations <number>

gzipper c ./src --zopfli-num-iterations 15

Maximum amount of times to rerun forward and backward pass to optimize LZ77 compression cost. Good values: 10, 15 for small files, 5 for files over several MB in size or it will be too slow. Only for --zopfli.

--zopfli-block-splitting

gzipper c ./src --zopfli-block-splitting

If true, splits the data in multiple deflate blocks with optimal choice for the block boundaries. Block splitting gives better compression. Only for --zopfli.

--zopfli-block-splitting-max <number>

gzipper c ./src --zopfli-block-splitting-max 5

Maximum amount of blocks to split into. 0 for unlimited, but this can give extreme results that hurt compression on some files. Only for --zopfli.

--zstd-level <number>

gzipper c ./src --zstd-level 8

Zstd compression level: 1 (default), 5 (best compression). Only for --zstd.

--output-file-format <value>

Output file format with artifacts, default format: [filename].[ext].[compressExt]. Where: filename -> name of your file, ext -> file extension, compressExt -> compress extension (.gz, .br, etc), hash -> uniq hash.

Example: Expected project structure.

img
  rabbit.jpg
  cat.jpg
js
  main.js
  modules.js
xml
  main.xml
index.js

• gzipper c ./src --output-file-format [filename].[compressExt].[ext]

  img
    rabbit.jpg
    rabbit.gz.jpg
    cat.jpg
    cat.gz.jpg
  js
    main.js
    main.gz.js
    modules.js
    modules.gz.js
  xml
    main.xml
    main.gz.xml
  index.js
  index.gz.js
  

• gzipper c ./src --output-file-format test-[filename]-[hash].[compressExt].[ext]

  img
    rabbit.jpg
    cat.jpg
    test-rabbit-b4564011-ba7c-4bd6-834d-bf6c7791b7d4.gz.jpg
    test-cat-739c7d7d-53ca-4f8e-912c-bad3b2b515a9.gz.jpg
  js
    main.js
    modules.js
    test-main-4cc35dbd-36f7-4889-9f41-4d93e7a25bef.gz.js
    test-modules-bce90cbd-5bf2-43c2-8b61-33aa1599b704.gz.js
  xml
    main.xml
    test-main-a90fa10e-f7a4-4af9-af67-f887bb96f98b.gz.xml
  index.js
  test-index-067c1e2d-0e12-4b57-980b-97c880c24d57.gz.js
  

• gzipper c ./src --output-file-format [filename]-[hash]-[filename]-tmp.[ext].[compressExt]

  img
    rabbit.jpg
    rabbit-b4564011-ba7c-4bd6-834d-bf6c7791b7d4-rabbit-tmp.jpg.gz
    cat.jpg
    cat-739c7d7d-53ca-4f8e-912c-bad3b2b515a9cat-tmp.jpg.gz
  js
    main.js
    main-4cc35dbd-36f7-4889-9f41-4d93e7a25bef-main-tmp.js.gz
    modules.js
    modules-bce90cbd-5bf2-43c2-8b61-33aa1599b704-modules-tmp.js.gz
  xml
    main.xml
    main-a90fa10e-f7a4-4af9-af67-f887bb96f98b-main-tmp.xml.gz
  index.js
  index-067c1e2d-0e12-4b57-980b-97c880c24d57-index-tmp.js.gz
  

--remove-larger

Removes compressed files larger than uncompressed originals in your directory.

--skip-compressed

Ignores compressed files that have already exist in your directory. Only with default --output-file-format.

--workers <number>

Spawn workers for parallel compression. Be aware of workers number because every worker creates an additional thread. More info at nodesource.com.

--no-color

Disable logger colorful messages.

cache

Command
purge
size

purge

gzipper cache purge

Removes all pre-compressed files from cache that was generated via --incremental argument.

size

gzipper cache size

Returns the size of all pre-compiled files from cache.

Changelog

CHANGELOG.md

Contribution

I appreciate every contribution, just fork the repository and send the pull request with your changes.

Support

• Node.js >= 20.11.0

Prerequisites

If you want to use --zstd compression, you have to make sure that the appropriate library is installed and available at your environment:

1where zstd.exe   # Windows
2command -v zstd  # MacOS/Linux

If you didn't find executable zstd you have to install this manually:

• MacOS using Brew

  1brew install zstd   # zstd only
  2brew install zlib   # whole library

• Windows Subsystem for Linux (WSL), Ubuntu, Debian... using APT

  1sudo apt install zstd