{"id":13270,"library":"gulp-gunzip","title":"Gulp Gunzip","description":"gulp-gunzip is a Gulp plugin designed to decompress gzip (.gz) files within a Gulp build pipeline. It functions as a streaming transformation, taking gzipped Vinyl files as input and outputting their uncompressed versions. The package is currently at version 1.1.0, with its last update occurring approximately 7 years ago, indicating it is in a `maintenance` state rather than active development. While it effectively handles standard gzip decompression, its primary differentiator is its seamless integration into the Gulp streaming workflow, making it suitable for tasks like uncompressing downloaded archives before further processing with other Gulp plugins such as `gulp-untar`.","status":"maintenance","version":"1.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/jmerrifield/gulp-gunzip","tags":["javascript","gulpplugin","gulp","gzip","gunzip"],"install":[{"cmd":"npm install gulp-gunzip","lang":"bash","label":"npm"},{"cmd":"yarn add gulp-gunzip","lang":"bash","label":"yarn"},{"cmd":"pnpm add gulp-gunzip","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required as the core build system to run this plugin. gulp-gunzip operates as a plugin within a Gulp task.","package":"gulp","optional":false}],"imports":[{"note":"This package is CommonJS-only. Direct ESM `import` is not supported without a transpiler or a Gulpfile configured for ESM (e.g., `gulpfile.mjs`) and potentially dynamic imports for legacy CJS modules.","wrong":"import gunzip from 'gulp-gunzip'","symbol":"gunzip","correct":"const gunzip = require('gulp-gunzip')"},{"note":"Gulp itself can support ESM in `gulpfile.mjs` or with `type: module` in `package.json`, but many older Gulpfiles and plugins still predominantly use CommonJS `require`.","wrong":"import gulp from 'gulp'","symbol":"gulp","correct":"const gulp = require('gulp')"}],"quickstart":{"code":"const gulp = require('gulp');\nconst gunzip = require('gulp-gunzip');\nconst untar = require('gulp-untar'); // Example for chained usage\nconst source = require('vinyl-source-stream'); // Example for fetching remote files\nconst request = require('request'); // Example for fetching remote files\nconst path = require('path');\nconst fs = require('fs');\n\n// Ensure output directories exist\nconst compressedDir = path.join(__dirname, 'compressed');\nconst uncompressedDir = path.join(__dirname, 'uncompressed');\nconst outputDir = path.join(__dirname, 'output');\n\nif (!fs.existsSync(compressedDir)) fs.mkdirSync(compressedDir);\nif (!fs.existsSync(uncompressedDir)) fs.mkdirSync(uncompressedDir);\nif (!fs.existsSync(outputDir)) fs.mkdirSync(outputDir);\n\n// Create a dummy gzipped file for the first task\nconst zlib = require('zlib');\nconst dummyContent = 'This is a test content for the gzipped file.';\nzlib.gzip(dummyContent, (err, buffer) => {\n  if (!err) {\n    fs.writeFileSync(path.join(compressedDir, 'testfile.txt.gz'), buffer);\n    console.log('Dummy gzipped file created: compressed/testfile.txt.gz');\n  }\n});\n\ngulp.task('uncompress-local', function () {\n  console.log('Starting local uncompression...');\n  return gulp.src(path.join(compressedDir, '*.gz'))\n    .pipe(gunzip())\n    .pipe(gulp.dest(uncompressedDir))\n    .on('end', () => console.log('Local files uncompressed to: ' + uncompressedDir));\n});\n\n// Example of uncompressing a remote .tar.gz file (requires 'request' and 'vinyl-source-stream')\n// NOTE: 'http://example.org/some-file.tar.gz' will likely result in a 404/dummy content\n// For a real example, replace with a valid .tar.gz URL.\ngulp.task('uncompress-remote', function (done) {\n  console.log('Attempting remote uncompression...');\n  // This URL is illustrative. A real URL to a .tar.gz would be needed.\n  const remoteFileUrl = 'https://www.google.com/robots.txt'; // Using a simple file for demonstration\n  const filename = 'remote-file.gz'; // Pretend it's gzipped for this demo\n\n  // Using a simplified request for a non-gzipped file for demonstration purposes if remoteFileUrl is not a .gz\n  // For actual .tar.gz, ensure the URL points to one and pipe through gunzip/untar\n  request(remoteFileUrl)\n    .pipe(source(filename))\n    .pipe(gunzip().on('error', (err) => {\n      console.error('Gunzip error on remote stream:', err.message);\n      // Handle cases where the remote file is not actually gzipped\n      done(); // Call done to complete the task even on error\n    }))\n    .pipe(gulp.dest(outputDir))\n    .on('end', () => {\n      console.log('Remote (simulated) file processed to: ' + outputDir);\n      done();\n    })\n    .on('error', (err) => {\n      console.error('Request stream error:', err.message);\n      done(err);\n    });\n});\n\ngulp.task('default', gulp.series('uncompress-local', 'uncompress-remote'));\n","lang":"javascript","description":"This quickstart demonstrates how to uncompress local `.gz` files using `gulp-gunzip` and how to integrate it into a pipeline for processing remote (or simulated remote) archives, showcasing its streaming capabilities within Gulp. It also includes necessary setup for dummy files and directories."},"warnings":[{"fix":"Evaluate compatibility with your specific Node.js and Gulp version. For critical applications, consider auditing its dependencies or finding a more actively maintained alternative.","message":"The package has not been updated since version 1.1.0 (published ~7 years ago). While it is stable for its core functionality, it may not receive updates for compatibility with newer Node.js versions, Gulp major releases, or address new security vulnerabilities.","severity":"gotcha","affected_versions":"<=1.1.0"},{"fix":"Test your Gulp pipelines after upgrading to 1.0.0 or later to ensure file paths are resolved as expected. Adjust `gulp.dest` configurations if necessary.","message":"Version 1.0.0 included a fix for an issue with relative paths and `file.base`. This change might alter file output paths for pipelines relying on previous, incorrect relative path handling.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Ensure that the input to `gulp-gunzip` consists of properly gzipped files. You might need to add validation steps using other Gulp plugins or Node.js's `zlib` module to verify file integrity before processing.","message":"`gulp-gunzip` expects valid gzip formatted files. Piping non-gzipped content or corrupted gzip files will result in errors or empty streams, potentially causing downstream tasks to fail or produce unexpected results.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Use `const gunzip = require('gulp-gunzip')` in CommonJS Gulpfiles (`gulpfile.js`). If your Gulpfile is configured for ESM, you may need to use dynamic `import()` or wrap the plugin in a CommonJS context, or reconsider using a pure ESM alternative if one exists.","message":"As a CommonJS-only module, `gulp-gunzip` does not natively support ES module `import` syntax. Attempting to use `import gunzip from 'gulp-gunzip'` in an ES module context (e.g., `gulpfile.mjs` or `package.json` with `\"type\": \"module\"`) will lead to errors like `ERR_REQUIRE_ESM`.","severity":"gotcha","affected_versions":">=0.0.1"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Verify that `gulp.src('./compressed/*.gz')` is correctly pointing to existing gzipped files. Add error handling to upstream pipes to diagnose silent failures (e.g., `.on('error', console.error)`).","cause":"This typically occurs when `gulp.src` does not find any files matching the glob pattern, or a preceding stream in the pipeline errors out silently, resulting in an undefined stream being passed to `.pipe(gunzip())`.","error":"Error: Cannot read property 'pipe' of undefined"},{"fix":"Ensure that the files being processed by `gulp-gunzip` are legitimate and uncorrupted gzip archives. You can pre-validate files using `zlib.gunzip` directly or other file integrity checks.","cause":"This error usually indicates that the input file is not a valid gzip file or is corrupted. `gulp-gunzip` uses Node.js's `zlib` internally, which throws this error for malformed gzip data.","error":"Error: incorrect header check"},{"fix":"Check the source of your `.gz` files for completeness. This can happen with incomplete downloads or corrupted storage. Ensure that the entire gzipped file has been received before piping it to `gulp-gunzip`.","cause":"This error suggests that the input gzip file ended prematurely or was truncated, leading to an incomplete data stream for decompression.","error":"Error: unexpected EOF"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null}