CLI and Module for Gzip and Brotli Compression

1.2.0 · abandoned · verified Wed Apr 22

gzip-cli is a command-line interface (CLI) and Node.js module designed for compressing files using both Gzip and Brotli algorithms. It provides robust functionality for specifying glob patterns to target files, defining custom output directories, and applying multiple compression extensions (e.g., .gz and .br) in a single command or programmatic call. The package supports ignoring specific file patterns and preserves the original directory structure when outputting compressed files. The current stable version, 1.2.0, was released in December 2020. The project does not adhere to a fixed release cadence. Its key differentiators include comprehensive support for both Gzip and Brotli, dual interfaces for CLI and programmatic usage, and integrated TypeScript types, enhancing developer experience in TypeScript-based projects. It is primarily used in Node.js environments for optimizing static assets during build processes.

Common errors

```
Error: no one pattern is specified. Operation is skipped.
```
cause No glob patterns were provided to the CLI command or `patterns` array in the module options.

fix Provide at least one glob pattern, e.g., `gzip 'dist/**/*.js'` or `gzip({ patterns: ['dist/**/*.js'] })`.
```
TypeError: gzip is not a function
```
cause Attempted to call `require('gzip-cli')` directly as a function in CommonJS, instead of accessing the named `gzip` export.

fix In CommonJS, use `const { gzip } = require('gzip-cli');` or `const gzipModule = require('gzip-cli'); const gzip = gzipModule.gzip;`.
```
SyntaxError: Cannot use import statement outside a module
```
cause Using ES module `import` syntax in a CommonJS (`.js`) file without explicit `type: 'module'` in `package.json` or incorrect file extension.

fix Either use CommonJS `require` syntax (`const { gzip } = require('gzip-cli');`) or ensure your project is configured for ES modules (e.g., `"type": "module"` in `package.json` and correct file extensions like `.mjs`).

Warnings

breaking Node.js versions older than 12 are no longer supported since version 1.2.0. Users on older Node.js runtimes will need to upgrade to use this version or stick to `gzip-cli@1.1.1` or earlier.
Fix: Upgrade your Node.js environment to version 12 or higher. Alternatively, pin your `gzip-cli` dependency to `1.1.1` if older Node.js versions are required.
gotcha Brotli compression support was added in version 1.1.0. Earlier versions (1.0.x) only support Gzip compression. If Brotli compression is required, ensure you are using `gzip-cli@1.1.0` or later.
Fix: Update `gzip-cli` to version `1.1.0` or higher to enable Brotli compression functionality.
gotcha Version 1.0.0 was released due to community usage rather than a formal stability guarantee, implying potential for API changes post-1.0.0. While the API has remained relatively stable, always review release notes for significant updates.
Fix: Always consult the project's GitHub repository or npm release notes when upgrading to new major or minor versions to understand potential breaking changes or API shifts.
gotcha Security vulnerability fixes for underlying dependencies were included in version 1.0.1. It is crucial to use the latest available version to benefit from these security updates and mitigate potential supply chain risks.
Fix: Ensure you are using `gzip-cli@1.0.1` or a later version to incorporate important dependency security patches.

Install

npm install gzip-cli npm
yarn add gzip-cli yarn
pnpm add gzip-cli pnpm

Imports

gzip
wrong:
```
import gzip from 'gzip-cli';
```
correct:
```
import { gzip } from 'gzip-cli';
```
The `gzip` function is a named export. Attempting a default import will result in undefined or errors.
gzip
wrong:
```
const gzip = require('gzip-cli');
```
correct:
```
const { gzip } = require('gzip-cli');
```
For CommonJS, `gzip` is a named export from the module object. Directly requiring the module returns an object, not the function itself.
CLI usage
wrong:
```
node_modules/.bin/gzip dist/**/*.js
```
correct:
```
gzip dist/**/*.js --extension=gz --extension=br
```
The `gzip` command is typically available directly in your shell after `npm install -g gzip-cli` or via `npx gzip-cli` or `npm run <script>`.

Quickstart

Demonstrates programmatic compression of static assets using Gzip and Brotli, ignoring specific patterns, within an async function.

import { gzip } from 'gzip-cli';

async function compressAssets() {
  try {
    await gzip({
      patterns: ['dist/public/**/*.{html,css,js,svg}'],
      outputExtensions: ['gz', 'br'],
      ignorePatterns: ['**/icons']
    });
    console.log('All specified assets compressed successfully with Gzip and Brotli.');
  } catch (error) {
    console.error('Failed to compress assets:', error);
    // Handle specific compression errors if needed
  }
}

compressAssets();

view raw JSON →