{"id":12322,"library":"unzipit","title":"unzipit.js","description":"unzipit.js is a JavaScript library providing efficient, random-access decompression of ZIP archives in both browser and Node.js environments. Currently stable at version 2.0.1, it offers significant performance advantages, claiming 6x to 25x faster extraction speeds than alternatives like JSZip, coupled with considerably lower memory consumption. A key differentiating feature is its ability to perform partial downloads of ZIP files by leveraging HTTP range requests, allowing selective extraction without fetching the entire archive. The library supports parallel processing through web workers, further enhancing speed. It accepts various input types, including URLs, Blobs, ArrayBuffers, and custom `Reader` implementations, making it versatile for diverse use cases. While designed for ESM, it also provides a CommonJS entry point for Node.js projects, with recent versions (Node >=18) primarily favoring ES Modules.","status":"active","version":"2.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/greggman/unzipit","tags":["javascript","zip","unzip","typescript"],"install":[{"cmd":"npm install unzipit","lang":"bash","label":"npm"},{"cmd":"yarn add unzipit","lang":"bash","label":"yarn"},{"cmd":"pnpm add unzipit","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"`unzip` is the primary named export for initiating the ZIP extraction process. Attempting a default import will fail.","wrong":"import unzip from 'unzipit';","symbol":"unzip","correct":"import { unzip } from 'unzipit';"},{"note":"Used to configure global options like `workerURL`. While `require` might work in some Node setups, ESM is the recommended approach for this library with Node >=18.","wrong":"const { setOptions } = require('unzipit');","symbol":"setOptions","correct":"import { setOptions } from 'unzipit';"},{"note":"Imports all exports under a namespace. `require` is incorrect for browser environments and typically for Node >=18 when using ESM.","wrong":"const unzipit = require('unzipit');","symbol":"* as unzipit (ESM)","correct":"import * as unzipit from 'unzipit';"},{"note":"This CommonJS import pattern is supported for Node.js environments. For browser or modern Node.js ESM projects, use `import` syntax.","symbol":"unzipit (CommonJS)","correct":"const unzipit = require('unzipit');"}],"quickstart":{"code":"import { unzip } from 'unzipit';\n\nasync function processZipFromUrl(zipUrl: string) {\n  try {\n    // Replace with a real URL for actual testing\n    const dataUrl = zipUrl || 'https://greggman.github.io/unzipit/test/zips/archive-with-folder.zip';\n\n    console.log(`Attempting to unzip from: ${dataUrl}`);\n    const { entries, zip } = await unzip(dataUrl);\n\n    console.log(`Total entries found: ${Object.keys(entries).length}`);\n\n    // Iterate through all entries and log their names and sizes\n    for (const [name, entry] of Object.entries(entries)) {\n      console.log(`  Entry: ${name}, Size: ${entry.size} bytes`);\n    }\n\n    // Example: Read a specific file (e.g., 'folder/file1.txt' from the example URL)\n    const specificEntry = entries['folder/file1.txt'];\n    if (specificEntry) {\n      console.log(`\\nAttempting to read 'folder/file1.txt' as text...`);\n      const textContent = await specificEntry.text();\n      console.log(`Content of 'folder/file1.txt':\\n---\\n${textContent.substring(0, 100)}...\\n---`); // Log first 100 chars\n    } else {\n      console.log(`\\nEntry 'folder/file1.txt' not found (check URL or entry name).`);\n    }\n\n    // Example: Read another entry as a Blob (e.g., if there was an image.png)\n    const imageEntry = entries['image.png']; // Replace with an actual image entry if present\n    if (imageEntry) {\n      console.log(`\\nAttempting to read 'image.png' as a Blob...`);\n      const imageBlob = await imageEntry.blob('image/png');\n      console.log(`'image.png' read as Blob of type: ${imageBlob.type}, size: ${imageBlob.size}`);\n      // In a browser, you could create an object URL: URL.createObjectURL(imageBlob);\n    } else {\n      console.log(`\\nEntry 'image.png' not found.`);\n    }\n\n  } catch (error) {\n    console.error(\"Error processing zip file:\", error);\n  }\n}\n\n// Call the function with an example URL. Pass an empty string to demonstrate 'not found' messages.\nprocessZipFromUrl('https://greggman.github.io/unzipit/test/zips/archive-with-folder.zip');","lang":"typescript","description":"Demonstrates basic usage of `unzipit` to fetch a ZIP file from a URL, list its contents, and extract specific entries as text and Blob objects, handling potential errors."},"warnings":[{"fix":"Replace `const unzipit = require('unzipit')` with `import { unzip } from 'unzipit'` or `import * as unzipit from 'unzipit'` for ES Module compatibility. Ensure your project's `package.json` specifies `\"type\": \"module\"` or uses `.mjs` file extensions for ESM.","message":"Users migrating from CommonJS (`require`) to ES Modules (`import`) or targeting modern Node.js environments (Node 18+) will experience breaking changes in import syntax.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Call `setOptions({workerURL: 'path/to/unzipit-worker.module.js'})` *before* calling `unzip`. The worker script is usually found in the `dist` folder of the `unzipit` package.","message":"When using web workers for parallel processing, the `workerURL` option *must* be correctly set to the path of `unzipit-worker.module.js`.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For Node.js, first read the file into a buffer using `fsPromises.readFile()` or use a library like `node-fetch` to get a `Blob` or `ArrayBuffer` from a URL, then pass that data to `unzip`.","message":"In Node.js environments, `unzipit` cannot directly fetch from URLs without a custom `Reader` or by pre-loading the ZIP content into an `ArrayBuffer`, `SharedArrayBuffer`, or `TypedArray`.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use `Object.entries(entries)`, `Object.keys(entries)`, or `Object.values(entries)` to iterate over the entries, as shown in the examples.","message":"The `unzip` function returns a `Zip` object with an `entries` property, which is a plain object mapping entry names to `ZipEntry` objects. Directly iterating over `entries` as an array will fail.","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":"Use a named import: `import { unzip } from 'unzipit';`.","cause":"Incorrect import syntax for named exports, typically attempting a default import for `unzip`.","error":"TypeError: (0 , unzipit__WEBPACK_IMPORTED_MODULE_0__.unzip) is not a function"},{"fix":"Use ES Module `import` statements (e.g., `import { unzip } from 'unzipit'`) or ensure your Node.js project is configured for CommonJS (`\"type\": \"commonjs\"` in `package.json`).","cause":"Attempting to use CommonJS `require` syntax in an ES Module environment (browser, or Node.js project configured for ESM).","error":"ReferenceError: require is not defined"},{"fix":"Ensure `workerURL` is a valid, publicly accessible URL relative to your web application's origin, or a data URL. Double-check the path to `unzipit-worker.module.js` in your `dist` folder.","cause":"The `workerURL` provided to `setOptions` points to an inaccessible or improperly served path for the web worker script.","error":"Failed to construct 'Worker': Script at 'path/to/unzipit-worker.module.js' cannot be accessed from origin 'null'."}],"ecosystem":"npm"}