Registry / http-networking / hypercore-blob-server

hypercore-blob-server

JSON →
library1.12.0jsnpmunverified

hypercore-blob-server provides an HTTP server specifically designed for streaming data (blobs and files) from Hypercore and Hyperdrive instances. It allows applications to expose content from the peer-to-peer Holepunch ecosystem over standard HTTP, making it accessible to traditional web clients or tools. Currently at version 1.12.0, it is an actively developed part of the Holepunch (formerly Dat Project) ecosystem, offering a more flexible successor to 'serve-drive'. The package differentiates itself by tightly integrating with Corestore for data management, supporting partial content delivery via HTTP Range headers, and generating direct links for both raw Hypercore blobs and Hyperdrive files, facilitating interoperability between decentralized data structures and conventional web infrastructure.

npm install hypercore-blob-server
INSTALL
IMPORT
SIG · HYPERCORE-BLOB-SER
H
hypercore-blob-server
http-networkingjavascriptv1.12.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

BlobServer
const BlobServer = require('hypercore-blob-server')
import BlobServer from 'hypercore-blob-server'
The official README example uses CommonJS `require()`. While ESM imports might work in some setups, `require()` is the most robust and documented approach for Node.js environments, especially with older v1.x projects in the Holepunch ecosystem.
BlobServer
import BlobServer from 'hypercore-blob-server'
const { BlobServer } = require('hypercore-blob-server')
For ESM environments, `import BlobServer from 'hypercore-blob-server'` is the correct syntax, as `BlobServer` is typically the default export. Attempting to destructure a CommonJS default export with `const { BlobServer } = require(...)` is a common mistake.
BlobServerOptions
import type { BlobServerOptions } from 'hypercore-blob-server'
When using TypeScript, `BlobServerOptions` can be imported as a type for defining the configuration object passed to the `BlobServer` constructor.

Demonstrates the full flow of initializing a Corestore, creating a Hypercore, appending data, starting a BlobServer, and generating a shareable link to the content.

const BlobServer = require('hypercore-blob-server') const Corestore = require('corestore') const Hypercore = require('hypercore') async function startServer () { // Initialize a Corestore for data management and persistence const store = new Corestore('./my-hypercore-data') await store.ready() // Create a Hypercore instance and append some data to it const core = store.get({ name: 'my-test-feed' }) await core.ready() await core.append(Buffer.from('Hello, Hypercore blob server!')) // Instantiate the BlobServer with the initialized corestore const server = new BlobServer(store, { port: 49833, host: '127.0.0.1', // For production deployments, consider adding a 'token' for security: // token: process.env.BLOB_SERVER_TOKEN ?? '' }) // Start the HTTP server to listen for incoming requests await server.listen() const address = server.server.address() console.log(`BlobServer listening on http://${address.address}:${address.port}`) // Generate a public URL link to the appended blob data // The 'blob' option requires precise byte offsets and lengths. const link = server.getLink(core.key, { blob: { blockOffset: 0, blockLength: 1, byteOffset: 0, byteLength: 29 }, type: 'text/plain' }) console.log('Access your Hypercore blob data here:', link) // To gracefully stop the server and close the corestore: // await server.suspend() // await store.close() } startServer().catch(console.error)
hypercore-blob-server --version
Debug
Known issues
gotchaThe `BlobServer` constructor requires a fully initialized `corestore` instance. Passing an uninitialized or incorrect object will lead to runtime errors when the server attempts to access it.
fix
Ensure `const store = new Corestore('./path/to/data'); await store.ready()` is called and awaited before passing the `store` instance to `BlobServer`.
affects: >=1.0.0
gotchaWhen serving sensitive data, the `token` option should be configured to secure access to the server. Without a token, the server is publicly accessible on its configured port to anyone who knows the URL.
fix
Configure the `token` option in the `BlobServer` constructor: `new BlobServer(store, { token: process.env.BLOB_SERVER_TOKEN })`. Clients will then need to pass this token in request headers for authorization.
affects: >=1.0.0
gotchaIncorrectly formatted `Range` headers can lead to `416 Range Not Satisfiable` errors or unexpected partial content responses. The format must strictly follow `bytes=<start>-<end>` (e.g., `bytes=0-100` or `bytes=50-`).
fix
Validate client `Range` header syntax and ensure byte offsets are within the blob's actual bounds. Ensure no spaces or invalid characters are present.
affects: >=1.0.0
gotchaWhen generating links for Hypercore blobs, the `blob` option requires a precise `{ blockOffset, blockLength, byteOffset, byteLength }` object. Errors in these values will result in 404s or malformed responses, as the server cannot locate the specified data segment.
fix
Ensure the `blob` object accurately describes the segment of data within the Hypercore. This often requires careful tracking of data appended to the core, or using library utilities to derive these values.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: store is not an object or store.ready is not a function
The `store` argument passed to the `BlobServer` constructor is either null/undefined, not an object, or is not a valid and initialized `Corestore` instance.
fix
Initialize `Corestore` correctly and ensure `await store.ready()` has been called: `const Corestore = require('corestore'); const store = new Corestore('./data-path'); await store.ready();`
Error: listen EADDRINUSE: address already in use :::49833
The default port (49833) or the custom port specified in `BlobServer` options is already in use by another process on the system.
fix
Change the `port` option in the `BlobServer` constructor to an available port (e.g., `port: 0` to let the OS assign a random available port), or terminate the process currently using the desired port.
HTTP/1.1 404 Not Found (when attempting to fetch a generated link)
The `key` for the Hypercore/Hyperdrive or the `blob` ID/`filename` provided in `server.getLink()` does not correspond to existing, accessible data within the `Corestore` being served.
fix
Verify that the `key` is correct, the associated Hypercore/Hyperdrive has been opened and contains data, and the `blob` or `filename` parameters precisely match the content intended to be served.
HTTP/1.1 416 Range Not Satisfiable (when fetching with a Range header)
The `Range` header in the client request specifies byte ranges that are outside the bounds of the available data for the requested blob, or the header format is invalid.
fix
Adjust the `Range` header to request valid byte ranges within the blob's actual size. Ensure the header format is strictly `bytes=<start>-<end>` (e.g., `Range: bytes=0-500`).
Upgrade
Version history
1.12.0latest on npm
Audit
Dependencies
corestorerequiredRequired to manage and persist Hypercore and Hyperdrive instances that the server exposes.
Agent activity
6 hits · last 30 days
node
6
Resources
hypercore-blob-server — npm install hypercore-blob-server · libregistry