{"id":11380,"library":"nanotar","title":"nanotar Tar Utilities","description":"nanotar is a compact and efficient utility library designed for creating and parsing Tar archives across various JavaScript environments, including Node.js, browsers, and edge runtimes. It prioritizes performance and a minimal footprint, making it suitable for resource-constrained applications. The current stable version is 0.3.0, with releases occurring as needed for enhancements and fixes, as demonstrated by recent updates to 0.2.0 and 0.3.0. A key differentiator is its universal JavaScript runtime compatibility and the inclusion of TypeScript types, ensuring robust development. It offers core functionalities for both generating `.tar` files and extracting their contents, supporting common Tar specifications. Unlike some alternatives, it aims to be dependency-free and focuses purely on the Tar format without additional compression (like gzip) built-in, allowing users to combine it with other compression libraries as needed.","status":"active","version":"0.3.0","language":"javascript","source_language":"en","source_url":"https://github.com/unjs/nanotar","tags":["javascript","typescript"],"install":[{"cmd":"npm install nanotar","lang":"bash","label":"npm"},{"cmd":"yarn add nanotar","lang":"bash","label":"yarn"},{"cmd":"pnpm add nanotar","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"nanotar is primarily an ESM-first package. Use named imports for `createTar`.","wrong":"const { createTar } = require('nanotar')","symbol":"createTar","correct":"import { createTar } from 'nanotar'"},{"note":"Both `createTar` and `parseTar` are named exports. Do not attempt a default import.","wrong":"import parseTar from 'nanotar'","symbol":"parseTar","correct":"import { parseTar } from 'nanotar'"},{"note":"Import types using `import type` for clarity and to avoid bundling type-only declarations.","wrong":"import { TarFileItem } from 'nanotar'","symbol":"TarFileItem","correct":"import type { TarFileItem } from 'nanotar'"}],"quickstart":{"code":"import { createTar, parseTar } from 'nanotar';\n\nasync function main() {\n  const files = [\n    { name: 'file1.txt', data: new TextEncoder().encode('Hello, nanotar!') },\n    { name: 'folder/file2.json', data: new TextEncoder().encode('{\"key\": \"value\"}') }\n  ];\n\n  // Create a tar archive\n  const tarBuffer = await createTar(files);\n  console.log('Created tar archive with size:', tarBuffer.byteLength, 'bytes');\n\n  // Simulate writing to disk and reading back (e.g., using Node.js fs)\n  // For browser/edge, this would be a Blob or similar.\n  // Example: fs.writeFileSync('archive.tar', Buffer.from(tarBuffer));\n  // const readTarBuffer = new Uint8Array(fs.readFileSync('archive.tar'));\n\n  // Parse the tar archive\n  const parsedItems = [];\n  for await (const item of parseTar(tarBuffer)) {\n    parsedItems.push(item);\n    console.log(`Parsed item: ${item.name} (type: ${item.type}, size: ${item.size})`);\n    if (item.data) {\n      console.log('  Content:', new TextDecoder().decode(item.data));\n    }\n  }\n\n  console.log('Total items parsed:', parsedItems.length);\n}\n\nmain().catch(console.error);","lang":"typescript","description":"Demonstrates how to create a Tar archive from an array of files and then parse its contents back into individual items, showing basic file and folder handling."},"warnings":[{"fix":"Review any code that consumes `parseTar` output, especially for archives using extended headers or less common file types, and adapt to potentially richer item metadata or type handling.","message":"The `parseTar` function in v0.3.0 now supports extended item types and headers. While an enhancement, this may alter the structure or available metadata of `TarFileItem` objects for complex archives, potentially affecting existing parsing logic that expects only basic tar headers.","severity":"breaking","affected_versions":">=0.3.0"},{"fix":"Ensure your application does not rely on unsanitized path formats from tar archives. Validate paths after parsing if your application has specific requirements beyond what `nanotar`'s sanitization provides.","message":"Starting with v0.3.0, paths are sanitized when creating and parsing tar archives. This is a security improvement (fixing path traversal vulnerabilities) but might change the exact string of file paths if your application relied on specific, potentially unsafe, path representations.","severity":"gotcha","affected_versions":">=0.3.0"},{"fix":"Consider migrating custom filtering/metadata extraction logic to utilize the built-in `filter` and `metaOnly` options for potentially improved performance and clarity.","message":"The `parseTar` function in v0.2.0 introduced `filter` and `metaOnly` options. If upgrading from pre-0.2.0 versions and custom parsing logic was in place, these new options might provide more efficient ways to handle specific parsing needs, but could also subtly change behavior if not understood.","severity":"gotcha","affected_versions":">=0.2.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure the input to `parseTar` is a `Uint8Array` instance representing a valid tar archive. Verify file reading or network fetching produces the correct binary data.","cause":"Attempting to parse an input that is not a valid `Uint8Array` or a malformed tar archive. This can happen if the input is `null`, `undefined`, a `string`, or an invalid buffer type.","error":"TypeError: Cannot read properties of undefined (reading 'byteLength') or 'Invalid tar header'"},{"fix":"Convert `Buffer` instances to `Uint8Array` before passing them to `createTar` or `parseTar` (e.g., `new Uint8Array(buffer)`). Ensure all binary data is handled as `Uint8Array`.","cause":"Attempting to use `Buffer` objects in a non-Node.js environment (e.g., browser or Edge runtime) without a polyfill. `nanotar` expects `Uint8Array` for universal compatibility.","error":"ReferenceError: Buffer is not defined"}],"ecosystem":"npm"}