{"id":17013,"library":"gzipper","title":"Gzipper CLI and Module","description":"Gzipper is a versatile command-line interface (CLI) tool and Node.js module designed for efficient file compression. It supports a comprehensive range of modern compression algorithms, including Deflate, Brotli, gzip, Zopfli, and zstd, providing developers with extensive control over the compression process. The current stable version is 8.2.1, with a regular release cadence as features and fixes are developed. Its key differentiators include fine-grained control over algorithm-specific parameters (e.g., `--gzip-level`, `--brotli-quality`), support for incremental compression, verbose output, and seamless integration with popular CLI UI tools like Angular CLI. It can compress entire directories by default or be configured with include/exclude patterns, and allows for custom output file formats. Environment variables take precedence over CLI arguments for configuration.","status":"active","version":"8.2.1","language":"javascript","source_language":"en","source_url":"https://github.com/gios/gzipper","tags":["javascript","compress","compression","brotli","deflate","zopfli","gzip","zlib","CLI","typescript"],"install":[{"cmd":"npm install gzipper","lang":"bash","label":"npm"},{"cmd":"yarn add gzipper","lang":"bash","label":"yarn"},{"cmd":"pnpm add gzipper","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"For programmatic use in ESM modules. Prefer named imports for clarity and tree-shaking.","wrong":"const { compress } = require('gzipper');","symbol":"compress","correct":"import { compress } from 'gzipper';"},{"note":"CommonJS import for Node.js environments. This is demonstrated in the official README.","symbol":"compress","correct":"const { compress } = require('gzipper');"},{"note":"Import for TypeScript type definitions when using the programmatic API with custom options.","symbol":"GzipperOptions","correct":"import type { GzipperOptions } from 'gzipper';"}],"quickstart":{"code":"import { compress } from 'gzipper';\nimport * as fs from 'node:fs';\nimport * as path from 'node:path';\n\nconst tempDir = path.join(process.cwd(), 'temp-gzipper-test');\nconst dummyFile = path.join(tempDir, 'example.txt');\n\nasync function runCompression() {\n  // Create a temporary directory and file for testing\n  if (!fs.existsSync(tempDir)) {\n    fs.mkdirSync(tempDir, { recursive: true });\n  }\n  fs.writeFileSync(dummyFile, 'This is a test file to demonstrate gzipper compression. It should be long enough to get some compression benefit.', 'utf8');\n\n  console.log('Compressing files in', tempDir);\n  try {\n    await compress(tempDir, tempDir, {\n      brotli: true, // Enable Brotli compression\n      gzip: true,   // Also enable Gzip compression\n      outputFileFormat: '[name].[ext].br', // Brotli output format\n      gzipOutputFileNameFormat: '[name].[ext].gz', // Gzip specific output format\n      verbose: true,\n      removeLarger: true // Remove original if compressed is smaller\n    });\n    console.log('Compression complete. Checking created files...');\n    console.log('Files in temp directory:', fs.readdirSync(tempDir));\n  } catch (error) {\n    console.error('Compression failed:', error);\n  } finally {\n    // Clean up temporary files and directory\n    if (fs.existsSync(tempDir)) {\n      fs.rmSync(tempDir, { recursive: true, force: true });\n      console.log('Cleaned up temporary directory:', tempDir);\n    }\n  }\n}\n\nrunCompression();\n","lang":"typescript","description":"Demonstrates programmatic usage of `gzipper` to compress a dummy file within a temporary directory using both Brotli and Gzip algorithms, with verbose output and cleanup."},"warnings":[{"fix":"Upgrade your Node.js environment to version 20.11.0 or newer (e.g., using nvm or your package manager).","message":"Gzipper requires Node.js version 20.11.0 or higher. Running it with older Node.js versions will result in execution errors.","severity":"breaking","affected_versions":">=8.0.0"},{"fix":"Always use the `--include <extensions>` (e.g., `--include js,css,html`) or `--exclude <extensions>` options to specify exactly which file types should be compressed, especially when working with entire project output directories.","message":"By default, `gzipper` will compress ALL files in the specified input directory. This can lead to unintended compression of files you don't want processed if `--include` or `--exclude` options are not used.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Be aware of your environment variables if CLI arguments or programmatic options seem to be ignored. Explicitly unset relevant `GZIPPER_` prefixed environment variables if you want CLI/code arguments to take precedence.","message":"When using `gzipper` programmatically or via CLI, environment variables with option names (e.g., `GZIPPER_BROTLI_QUALITY=11`) will override any corresponding CLI arguments or programmatic options passed directly to the `compress` function.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Define distinct output file formats for each algorithm, such as `[name].[ext].gz` for Gzip and `[name].[ext].br` for Brotli, to avoid accidental overwrites. The `compress` function also accepts `gzipOutputFileNameFormat` and `brotliOutputFileNameFormat` options.","message":"When using multiple compression algorithms (e.g., both `--gzip` and `--brotli`), ensure your `--output-file-format` or algorithm-specific output format options (e.g., `--gzip-output-file-name-format`) prevent filename collisions, otherwise files might be overwritten.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Install `gzipper` globally using `npm i -g gzipper` or ensure your shell's PATH includes `$(npm bin -g)`.","cause":"`gzipper` is not installed globally or is not in your system's PATH.","error":"gzipper: command not found"},{"fix":"Either convert your consuming script to an ES Module (e.g., add `\"type\": \"module\"` to package.json or use `.mjs` extension) and use `import { compress } from 'gzipper';`, or ensure you are using the CommonJS compatible entry point with `const { compress } = require('gzipper/cjs');` if available, or simply `require('gzipper');` which should resolve correctly based on the package.json `exports` field.","cause":"You are trying to `require()` gzipper in a CommonJS module, but gzipper's main entry point might be an ESM module or your project configuration is conflicting.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module .../node_modules/gzipper/dist/index.js from .../my-script.js not supported."},{"fix":"Ensure that the input path and output path arguments are correctly provided as strings to the `compress` function or CLI command.","cause":"The input or output directory arguments to the `compress` function (or CLI) were not provided or were undefined.","error":"Error: The 'path' argument must be of type string or an instance of Buffer or URL. Received undefined"}],"ecosystem":"npm","meta_description":null}