{"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,"search_vec":"'8.2.1':53 'algorithm':31,75 'algorithm-specif':74 'allow':116 'angular':100 'argument':128 'brot':34,83,134 'brotli-qu':82 'cadenc':58 'cli':2,13,96,101,127,139 'command':10 'command-lin':9 'comprehens':26 'compress':22,30,46,88,104,132,133 'configur':111,130 'control':43,72 'current':49 'custom':118 'default':108 'deflat':33,135 'design':18 'develop':40,64 'differenti':67 'directori':106 'e.g':78 'effici':20 'entir':105 'environ':122 'extens':42 'featur':60 'file':21,120 'fine':70 'fine-grain':69 'fix':62 'format':121 'grain':71 'gzip':35,80,137 'gzip-level':79 'gzipper':1,5 'includ':32,68 'include/exclude':113 'increment':87 'integr':93 'interfac':12 'javascript':131 'key':66 'level':81 'like':99 'line':11 'modern':29 'modul':4,17 'node.js':16 'output':90,119 'paramet':77 'pattern':114 'popular':95 'preced':125 'process':47 'provid':39 'qualiti':84 'rang':27 'regular':56 'releas':57 'seamless':92 'specif':76 'stabl':50 'support':24,85 'take':124 'tool':14,98 'typescript':140 'ui':97 'variabl':123 'verbos':89 'versatil':8 'version':51 'zlib':138 'zopfli':36,136 'zstd':38","created_at":"2026-04-22T15:09:35.591257+00:00","updated_at":"2026-04-22T15:09:35.591257+00:00","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,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"gzipper","cli_version":null,"type":"library","homepage":"https://www.npmjs.com/package/gzipper","github":"https://github.com/gios/gzipper","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/gzipper","openapi_spec":null,"status_page":null,"smithery":null,"categories":["devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-21","install_tag":null}}