@bytecask/react

React bindings for browser-native blob storage.

Connect React applications to Bytecask with an ownership-aware provider and typed hooks for uploads, reads, and browser storage estimates.

pnpm add @bytecask/core @bytecask/react react

Quick Start · Provider · Hooks · Browser Support · Documentation

What It Is

@bytecask/react is the optional React layer over @bytecask/core. It keeps storage policy in the core package and gives components predictable loading, missing, and error states without introducing a second storage abstraction.

Highlights

• Small React surface: one provider and focused hooks over the core API.
• Explicit ownership: providers close stores they create and preserve stores supplied by the host.
• Typed async state: upload, lookup, estimate, and failure state are exposed without hiding the underlying BlobStore.
• SSR-safe imports: importing the module does not construct browser storage; create providers and stores in a browser context.
• React 18 and 19: both current application generations are supported.

Installation

pnpm add @bytecask/core @bytecask/react react

Add @bytecask/worker when the provider selects OPFS:

pnpm add @bytecask/core @bytecask/react @bytecask/worker react

Quick Start

import { BytecaskProvider, usePutBlob } from '@bytecask/react'

function UploadButton() {
  const { put, putting, error } = usePutBlob()

  return (
    <input
      type="file"
      disabled={putting}
      aria-invalid={error ? true : undefined}
      onChange={async (event) => {
        const file = event.currentTarget.files?.[0]
        if (file) console.log(await put(file))
      }}
    />
  )
}

export function App() {
  return (
    <BytecaskProvider options={{ backend: 'idb' }}>
      <UploadButton />
    </BytecaskProvider>
  )
}

The upload result is the lowercase BLAKE3 content hash. Keep that hash in the host's attachment record and let Bytecask own the corresponding bytes.

Provider Ownership

Let the provider construct and close its store:

<BytecaskProvider
  options={{
    backend: 'idb',
    idb: { databaseName: 'archive-blobs' },
    metadata: { databaseName: 'archive-metadata' },
  }}
>
  <AppRoutes />
</BytecaskProvider>

Or supply a store owned by the host:

<BytecaskProvider store={store}>
  <AppRoutes />
</BytecaskProvider>

The provider closes stores created from options when it unmounts. It does not close an explicitly supplied store.

Hooks

| Hook | Purpose | |---|---| | useBytecaskStore() | Access the current BlobStore | | usePutBlob() | Store a Blob and expose upload/error state | | useBlob(hash) | Resolve a hash to bytes with explicit status and error state | | useStorageEstimate() | Read usage, quota, and persistence information |

import { useBlob } from '@bytecask/react'

function Attachment({ hash }: { hash: string }) {
  const { status, bytes, error } = useBlob(hash)

  if (status === 'loading') return <span>Loading</span>
  if (error) return <span>Unavailable</span>
  if (status === 'missing') return <span>Restore required</span>
  if (status !== 'ready') return null
  return <span>{bytes?.byteLength ?? 0} bytes</span>
}

Missing bytes are a normal recoverable state: the host retains its attachment record and restores content from a trusted source when available.

Browser Support

• React 18 and React 19 are accepted peer versions.
• IndexedDB storage is tested in Chromium, Firefox, and Playwright WebKit.
• OPFS storage is tested in Chromium and Firefox and requires @bytecask/worker.
• The package is ESM-only and intended for modern browser applications.

Related Packages

| Package | Purpose | |---|---| | @bytecask/core | Required framework-neutral storage engine | | @bytecask/worker | Optional OPFS worker and streaming I/O |

Documentation

• Project README
• Host contract
• Coverage and browser evidence
• Core package
• Changelog

Security

Storage identity is not publisher identity. Verify signed containers or shards before loading untrusted bytes. Report vulnerabilities through the project's security policy.

License

AGPL-3.0-only. See LICENSE.