extract-zip

Common errors

• TypeError: extract is not a function

  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+.
  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)`.

• Error: Your Node.js version is too old. This module requires Node.js >= 10.17.0.

  cause Running `extract-zip` v2.0.1 or later on an unsupported Node.js version.
  fix Upgrade your Node.js environment to version 10.17.0 or newer. Check the official Node.js website for LTS releases.

• Error: End of Central Directory Record not found

  cause The provided source file is either not a valid zip archive or is corrupted, preventing the `yauzl` parser from identifying the central directory.
  fix Verify that the `source` path points to a legitimate and uncorrupted `.zip` file. Try opening the zip file manually to confirm its integrity.

Warnings

• breaking 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`.
  Fix: Rewrite extraction logic to use `async/await`: `await extract(source, { dir: target })` instead of `extract(source, { dir: target }, callback)`.
• breaking 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.
  Fix: Upgrade your Node.js environment to version 10.12.0 or newer. For best compatibility with current versions, upgrade to >=10.17.0.
• breaking 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.
  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.
• gotcha 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.
  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.

Install

• npm install extract-zip npm
• yarn add extract-zip yarn
• pnpm add extract-zip pnpm

Imports

• extract (ESM)
  wrong:

  import { extract } from 'extract-zip'

  correct:

  import extract from 'extract-zip'

  The primary `extract` function is the default export for ES Modules. Use `await` as the API is Promise-based.
• extract (CommonJS)
  wrong:

  const { extract } = require('extract-zip')

  correct:

  const extract = require('extract-zip')

  For CommonJS environments, `extract` is the module's default export. Avoid destructuring as it's not a named export.
• ExtractOptions (TypeScript type)
  wrong:

  import { ExtractOptions } from 'extract-zip'

  correct:

  import type { ExtractOptions } from 'extract-zip'

  Use `import type` for importing only the type definition, which is recommended for clarity and bundler optimization in TypeScript.

Quickstart

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.

import extract from 'extract-zip';
import { mkdir, mkdtemp } from 'node:fs/promises';
import { join } from 'node:path';
import { tmpdir } from 'node:os';

async function runExtractionDemo() {
  // 1. Define source and target paths.
  //    For a real scenario, 'path/to/your/archive.zip' should be an actual zip file.
  //    For this demo, we'll create a temporary directory for extraction.
  const tempExtractionDir = await mkdtemp(join(tmpdir(), 'extract-zip-demo-'));
  const sourceZipPath = join(__dirname, 'test.zip'); // Assume a 'test.zip' exists alongside this script
                                                     // For a real run, ensure this file exists.
  const targetDirectoryPath = join(tempExtractionDir, 'extracted-content');

  console.log(`Attempting to extract from: ${sourceZipPath}`);
  console.log(`To target directory: ${targetDirectoryPath}`);

  try {
    // Ensure the target directory exists before extraction (optional, extract-zip usually creates it)
    await mkdir(targetDirectoryPath, { recursive: true });

    // 2. Call the extract function.
    await extract(sourceZipPath, { dir: targetDirectoryPath });

    console.log('✅ Extraction complete!');
    console.log(`Content should be in: ${targetDirectoryPath}`);
    // Example: To list extracted files:
    // import { readdir } from 'node:fs/promises';
    // const files = await readdir(targetDirectoryPath);
    // console.log('Extracted files:', files);

  } catch (err: any) {
    console.error('❌ Extraction failed:', err.message);
    if (err.code === 'ENOENT') {
      console.error(`Hint: Make sure '${sourceZipPath}' exists and is a valid zip file.`);
    } else if (err.message.includes('End of Central Directory Record not found')) {
        console.error('Hint: The file might be corrupted or not a valid zip archive.');
    }
  } finally {
    // 3. Clean up the temporary directory. Uncomment for automatic cleanup.
    // console.log(`Cleaning up temporary directory: ${tempExtractionDir}`);
    // await rm(tempExtractionDir, { recursive: true, force: true });
    console.log(`Temporary directory created at: ${tempExtractionDir}. Please inspect and remove manually if needed.`);
  }
}

runExtractionDemo().catch(console.error);