Hyperdrive

Store document attachments or images, then register the drive for replication.

How it works

Hyperdrive stores versioned files using Corestore-backed metadata and content cores. Use it for attachments, images and other path-addressed data.

The example writes a text file, reads its bytes and lists the notes directory. Its storage remains in ./data.

A replicated file entry may be visible before all content blocks are available. Your app must represent missing or partially downloaded files.

Run an example

Use Node 22.17+ and npm for installation. Start in a new directory for this example so its ./data storage cannot collide with another example. Save each file below with the exact filename shown, then run the commands in order.

mkdir hyperdrive-demo
cd hyperdrive-demo
npm init -y
npm install corestore@'^7.13.0' hyperdrive@'^12.3.0'

Save as example.mjs:

import Corestore from 'corestore'
import Hyperdrive from 'hyperdrive'
const store = new Corestore('./data')
const drive = new Hyperdrive(store)
try {
  await drive.ready()
  await drive.put('/notes/welcome.txt', Buffer.from('Hello files'))
  console.log((await drive.get('/notes/welcome.txt')).toString())
  for await (const entry of drive.list('/notes')) console.log(entry.key)
} finally {
  await drive.close()
  await store.close()
}

Run from this example directory:

node example.mjs

Expected result

Hello files /notes/welcome.txt

API essentials

• put(path, bytes): save file content. get(path): read the bytes, or null if the file does not exist.
• list(directory): iterate file entries. createReadStream(path): consume a large file incrementally.
• close(): close the drive, then close its owning Corestore. /sync can register drives for replication.

Troubleshooting and limits

• Buffer is used here because the script runs under Node. Use a compatible byte utility in Bare.
• Do not call a mirrored drive a complete backup: identity recovery, encryption keys and restore testing are separate work.
• Persist the drive key and store directory if another device needs to open the same drive.

Next steps