{"id":10866,"library":"extract-zip","title":"extract-zip","description":"extract-zip is a pure JavaScript library for asynchronously extracting zip archives into a specified directory. It currently stands at version 2.0.1 and leverages the `yauzl` parser internally to handle zip file structures. Version 2.0.0 marked a significant update, introducing a modern Promise-based API that replaced the older callback-style approach, and adding official TypeScript definitions for enhanced developer experience. The library maintains an active release cadence, with recent updates (like v2.0.1) addressing critical maintenance issues such as the deprecated `process.umask` and clarifying Node.js minimum version requirements. It also offers a command-line interface for direct use. Its primary differentiators include its 100% JavaScript implementation, which avoids native binaries, and its adoption of the modern async/await pattern for all extraction operations, requiring Node.js 10.17.0 or newer.","status":"active","version":"2.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/maxogden/extract-zip","tags":["javascript","unzip","zip","extract","typescript"],"install":[{"cmd":"npm install extract-zip","lang":"bash","label":"npm"},{"cmd":"yarn add extract-zip","lang":"bash","label":"yarn"},{"cmd":"pnpm add extract-zip","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core library for parsing ZIP files. `extract-zip` uses it internally for handling the ZIP file format.","package":"yauzl","optional":false}],"imports":[{"note":"The primary `extract` function is the default export for ES Modules. Use `await` as the API is Promise-based.","wrong":"import { extract } from 'extract-zip'","symbol":"extract (ESM)","correct":"import extract from 'extract-zip'"},{"note":"For CommonJS environments, `extract` is the module's default export. Avoid destructuring as it's not a named export.","wrong":"const { extract } = require('extract-zip')","symbol":"extract (CommonJS)","correct":"const extract = require('extract-zip')"},{"note":"Use `import type` for importing only the type definition, which is recommended for clarity and bundler optimization in TypeScript.","wrong":"import { ExtractOptions } from 'extract-zip'","symbol":"ExtractOptions (TypeScript type)","correct":"import type { ExtractOptions } from 'extract-zip'"}],"quickstart":{"code":"import extract from 'extract-zip';\nimport { mkdir, mkdtemp } from 'node:fs/promises';\nimport { join } from 'node:path';\nimport { tmpdir } from 'node:os';\n\nasync function runExtractionDemo() {\n  // 1. Define source and target paths.\n  //    For a real scenario, 'path/to/your/archive.zip' should be an actual zip file.\n  //    For this demo, we'll create a temporary directory for extraction.\n  const tempExtractionDir = await mkdtemp(join(tmpdir(), 'extract-zip-demo-'));\n  const sourceZipPath = join(__dirname, 'test.zip'); // Assume a 'test.zip' exists alongside this script\n                                                     // For a real run, ensure this file exists.\n  const targetDirectoryPath = join(tempExtractionDir, 'extracted-content');\n\n  console.log(`Attempting to extract from: ${sourceZipPath}`);\n  console.log(`To target directory: ${targetDirectoryPath}`);\n\n  try {\n    // Ensure the target directory exists before extraction (optional, extract-zip usually creates it)\n    await mkdir(targetDirectoryPath, { recursive: true });\n\n    // 2. Call the extract function.\n    await extract(sourceZipPath, { dir: targetDirectoryPath });\n\n    console.log('✅ Extraction complete!');\n    console.log(`Content should be in: ${targetDirectoryPath}`);\n    // Example: To list extracted files:\n    // import { readdir } from 'node:fs/promises';\n    // const files = await readdir(targetDirectoryPath);\n    // console.log('Extracted files:', files);\n\n  } catch (err: any) {\n    console.error('❌ Extraction failed:', err.message);\n    if (err.code === 'ENOENT') {\n      console.error(`Hint: Make sure '${sourceZipPath}' exists and is a valid zip file.`);\n    } else if (err.message.includes('End of Central Directory Record not found')) {\n        console.error('Hint: The file might be corrupted or not a valid zip archive.');\n    }\n  } finally {\n    // 3. Clean up the temporary directory. Uncomment for automatic cleanup.\n    // console.log(`Cleaning up temporary directory: ${tempExtractionDir}`);\n    // await rm(tempExtractionDir, { recursive: true, force: true });\n    console.log(`Temporary directory created at: ${tempExtractionDir}. Please inspect and remove manually if needed.`);\n  }\n}\n\nrunExtractionDemo().catch(console.error);","lang":"typescript","description":"This quickstart demonstrates how to use `extract-zip` with its Promise-based API to extract a zip file. It sets up a temporary directory for extraction and includes basic error handling, noting that a real zip file must exist at the specified source path for actual operation."},"warnings":[{"fix":"Rewrite extraction logic to use `async/await`: `await extract(source, { dir: target })` instead of `extract(source, { dir: target }, callback)`.","message":"The callback-style API was entirely removed in version 2.0.0. All operations now return Promises and should be handled with `await` or `.then/.catch`.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Upgrade your Node.js environment to version 10.12.0 or newer. For best compatibility with current versions, upgrade to >=10.17.0.","message":"Support for Node.js versions older than 10.12 was dropped in version 2.0.0. The library leverages `fs.promises`, which stabilized in newer Node versions.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Ensure your Node.js environment is at version 10.17.0 or higher. It's recommended to use an actively maintained Node.js LTS version.","message":"The minimum required Node.js version was corrected to 10.17.0 in version 2.0.1, due to dependencies on `fs.promises` stability. This means installations on Node.js versions between 10.12.0 and 10.16.x that worked with v2.0.0 will now fail with v2.0.1.","severity":"breaking","affected_versions":">=2.0.1"},{"fix":"Ensure your `onEntry` callback correctly handles `(entry, zipfile)` arguments if you need access to the `yauzl` instance or raw entry data, and explicitly close the `zipfile` if you open it manually within the handler.","message":"The `onEntry` option function expects two arguments: `(entry, zipfile)`. The `entry` object is forwarded directly from the `yauzl` library, and `zipfile` is the `yauzl` instance itself. Always ensure `zipfile` is closed when you are done.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"For CommonJS, use `const extract = require('extract-zip')`. For all versions >= 2.0.0, ensure you're using the Promise-based API with `await extract(source, options)`.","cause":"Attempting to use `extract` in a CommonJS module with incorrect destructuring or trying to use the old callback API after upgrading to v2.0.0+.","error":"TypeError: extract is not a function"},{"fix":"Upgrade your Node.js environment to version 10.17.0 or newer. Check the official Node.js website for LTS releases.","cause":"Running `extract-zip` v2.0.1 or later on an unsupported Node.js version.","error":"Error: Your Node.js version is too old. This module requires Node.js >= 10.17.0."},{"fix":"Verify that the `source` path points to a legitimate and uncorrupted `.zip` file. Try opening the zip file manually to confirm its integrity.","cause":"The provided source file is either not a valid zip archive or is corrupted, preventing the `yauzl` parser from identifying the central directory.","error":"Error: End of Central Directory Record not found"}],"ecosystem":"npm"}