{"id":15595,"library":"drive-bundler","title":"Drive Bundler","description":"drive-bundler is a JavaScript module designed for extracting bundles of files, code, and assets from Hyperdrives or Localdrives within the Holepunch peer-to-peer ecosystem. As of version 2.6.0, it provides programmatic access to traverse a 'drive' (a distributed or local file system abstraction) and gather specified entrypoints and their dependencies into a bundled output. This library is a foundational component for building serverless, local-first, and offline-capable applications that leverage Hypercore Protocol's decentralized data structures. It differs from traditional web bundlers (like Webpack or Parcel) by operating directly on a distributed file system interface, rather than a local file system, making it crucial for distributing P2P applications and their updates efficiently. While there's no explicit fixed release cadence, the broader Holepunch ecosystem is under active development, implying regular updates and maintenance for its core modules.","status":"active","version":"2.6.0","language":"javascript","source_language":"en","source_url":"https://github.com/holepunchto/drive-bundler","tags":["javascript"],"install":[{"cmd":"npm install drive-bundler","lang":"bash","label":"npm"},{"cmd":"yarn add drive-bundler","lang":"bash","label":"yarn"},{"cmd":"pnpm add drive-bundler","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"drive-bundler operates on a 'drive' object, typically an instance of hyperdrive (a distributed file system) or localdrive (a local file system abstraction that mimics hyperdrive's API). These are runtime dependencies for practical use.","package":"hyperdrive","optional":false}],"imports":[{"note":"While the README shows `require`, `drive-bundler` likely supports (or will transition to) ESM default imports for modern Node.js and bundler environments. Named imports are less common for the main class.","wrong":"const DriveBundler = require('drive-bundler')","symbol":"DriveBundler","correct":"import DriveBundler from 'drive-bundler'"},{"note":"Always check the package.json `exports` map or bundled d.ts files to confirm if the main class is a default or named export in newer versions. This is a common point of confusion during ecosystem transitions.","wrong":"import DriveBundler from 'drive-bundler' // if it becomes a named export","symbol":"DriveBundler","correct":"import { DriveBundler } from 'drive-bundler'"}],"quickstart":{"code":"import Localdrive from 'localdrive';\nimport DriveBundler from 'drive-bundler';\nimport RAM from 'random-access-memory';\nimport { promises as fs } from 'fs';\nimport path from 'path';\n\nasync function createTempLocaldrive() {\n  const root = await fs.mkdtemp(path.join(process.cwd(), 'temp-drive-'));\n  const drive = new Localdrive(root, { \n    storage: (file) => new RAM()\n  });\n\n  // Add some dummy files to the localdrive\n  await fs.writeFile(path.join(root, 'index.js'), 'export * from \"./lib\";');\n  await fs.mkdir(path.join(root, 'lib'));\n  await fs.writeFile(path.join(root, 'lib', 'main.js'), 'export const hello = \"world\";');\n  await fs.writeFile(path.join(root, 'package.json'), JSON.stringify({\n    name: 'my-project',\n    main: 'index.js'\n  }));\n\n  console.log(`Created temporary localdrive at ${root}`);\n  return drive;\n}\n\nasync function bundleExample() {\n  const drive = await createTempLocaldrive();\n\n  try {\n    const b = new DriveBundler(drive);\n\n    // Bundle a specific entrypoint, e.g., 'index.js'\n    const { entrypoint, resolutions, sources } = await b.bundle('/index.js');\n\n    console.log('Bundling successful!');\n    console.log('Entrypoint:', entrypoint);\n    console.log('Resolved Paths:', Object.keys(resolutions));\n    console.log('Source files bundled:', Object.keys(sources));\n\n    // Example: Accessing a bundled source\n    if (sources['/lib/main.js']) {\n      console.log('Content of /lib/main.js:', sources['/lib/main.js'].toString());\n    }\n\n  } finally {\n    // Clean up the temporary drive resources\n    // In a real app, ensure proper drive closing and resource management.\n    console.log('Finished bundling example.');\n  }\n}\n\nbundleExample().catch(console.error);\n","lang":"typescript","description":"This example demonstrates how to create a temporary Localdrive, populate it with some files, and then use `DriveBundler` to extract a bundle based on a specified entrypoint, showing the resolved paths and source content."},"warnings":[{"fix":"Migrate all `require('drive-bundler')` calls to `import DriveBundler from 'drive-bundler'` or `import { DriveBundler } from 'drive-bundler'`, ensuring your project is configured for ESM (e.g., `\"type\": \"module\"` in package.json or using `.mjs` extensions).","message":"Starting with `drive-bundler` v3.0.0 (hypothetical, as a common pattern in the ecosystem), the package may transition to pure ES Module (ESM) exports only. This means CommonJS `require()` statements will no longer work directly.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Always ensure the `drive` instance is correctly initialized and, if it's a `Hyperdrive`, that it has been loaded and potentially replicated if accessing remote content. For `Localdrive`, ensure the root path exists and is accessible.","message":"The `drive` argument passed to `new DriveBundler(drive)` must be a valid instance of a Hyperdrive-compatible interface (e.g., `hyperdrive` or `localdrive`). Passing a plain object or an uninitialized drive will lead to runtime errors or unexpected bundling behavior.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Before attempting to bundle from a remote Hyperdrive, ensure sufficient replication is established with peers that have the full content. Monitor the drive's ready state and replication progress to confirm data availability.","message":"When bundling from a remote Hyperdrive, the `drive-bundler` will only have access to data that has been replicated locally. If the desired entrypoint or its dependencies have not yet been synchronized from other peers, the bundle operation may fail to find files.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"If using Node.js with ESM, use `import DriveBundler from 'drive-bundler';`. If using CommonJS (older Node.js or specifically `require`), ensure the package exports a default for `require()` or `const { DriveBundler } = require('drive-bundler');` if it's a named export. Check the package's `package.json` `exports` field for explicit guidance.","cause":"Attempting to `new` a `DriveBundler` instance when the import method did not correctly resolve the constructor, often due to CommonJS/ESM interop issues or incorrect named vs. default import.","error":"TypeError: DriveBundler is not a constructor"},{"fix":"Verify that the `drive` instance is correct and points to the expected data. Double-check the path to the entrypoint, ensuring it is absolute from the drive's root. If it's a remote Hyperdrive, confirm that the file has been replicated and is available locally.","cause":"The specified entrypoint file does not exist at the given path within the `drive` instance, or the drive itself is not properly initialized or accessible.","error":"Error: Could not read entrypoint /path/to/entry.js from drive"},{"fix":"Ensure that all required dependencies, including those normally found in `node_modules`, are explicitly present within the structure of the drive being bundled, or configure `drive-bundler` (if options allow) to resolve external modules differently. For simple asset bundling, this error might indicate missing source files rather than npm packages.","cause":"A dependency within the bundled source code cannot be resolved by the bundler. This might happen if `drive-bundler` doesn't automatically handle `node_modules`-like resolution or if the dependency isn't present in the drive.","error":"ERR_MODULE_NOT_FOUND: Cannot find package 'some-dependency'"}],"ecosystem":"npm"}