Enbox Browser

Research Preview — Enbox is under active development. APIs may change without notice.

| Browser-specific tools and features for building decentralized web applications | | ------------------------------------------------------------------------------ |

• Enbox Browser
  • Install
  • Usage
  • Bundlers and Service Workers
  • Storage Model
  • Activate Polyfills
  • Project Resources

This package contains browser-specific helpers for building DWAs (Decentralized Web Apps) with the Enbox toolkit.

Install

bun add @enbox/browser

Usage

Use the bare package entrypoint in browser apps. It re-exports the high-level API from @enbox/api, auth/session helpers from @enbox/auth, and browser-specific connect utilities.

import { BrowserConnectHandler, Enbox, defineProtocol, recordCodecs } from '@enbox/browser';

const { enbox } = await Enbox.connect({
  connectHandler : BrowserConnectHandler({ appName: 'Notes' }),
  createIdentity : true,
  protocols      : [NotesProtocol],
});

Bundlers and Service Workers

@enbox/browser declares a browser-conditioned root export that resolves to the prebuilt dist/browser.mjs bundle. Browser-aware bundlers, including secondary Vite passes used for service workers, can import @enbox/browser without adding Node global shims for process, process.env, process.browser, process.emitWarning, global, or the Node events builtin.

activatePolyfills() is unrelated to Node-global shims. It installs browser DWeb/DRL behavior such as service-worker handling for dweb URLs; it is not a compatibility shim for the SDK package graph.

Storage Model

The default browser agent storage remains Level-backed. The level package resolves to browser-level, which stores data in IndexedDB so tabs, workers, and service workers on the same origin can safely write concurrently. SQLite over OPFS is not a drop-in browser replacement for this usage because it does not provide the same cross-context write behavior.

Activate Polyfills (required for any app that renders DWN-addressed content)

activatePolyfills() installs the DWeb network stack: a service worker fetch handler that resolves DRLs — DWN-addressed URLs such as http://dweb/did:dht:abc123/protocols/read/aHR0cHM6Ly9hcmV3ZXdlYjV5ZXQuY29tL3NjaGVtYXMvcHJvdG9jb2xz/avatar — by resolving the DID to its DWN endpoints and returning the record as an ordinary Response (with an optional TTL cache via onCacheCheck). This is what lets a plain <img src> or fetch() address a record on any DWN.

Despite the name, this is not an optional compatibility shim. Without it, every DRL in your app fails as an ordinary network error — no exception at the SDK boundary, nothing in the console pointing at a missing subsystem, and everything else (connect, records, sync) keeps working. Treat it like the bundler configuration above: required scaffolding for a browser dapp.

Two ways to wire it:

• Zero-config: import and run activatePolyfills() at your page entrypoint; in a page context it registers itself as a root service worker (pass path explicitly under a strict CSP).
• Own service worker (recommended for production): call activatePolyfills() inside your sw.ts and let your build tool (e.g. vite-plugin-pwa with injectManifest) register it alongside precaching.

Verify it behaviorally, not just at build time: the worker must be registered, reach activated, and control the page (navigator.serviceWorker.controller non-null after a reload). A served-but-never-evaluated worker passes every build. Full wiring guidance, build traps, and hosting-header pitfalls: docs/architecture/browser-dapps.md.

Project Resources

| Resource | Description | | --------------------------------------- | ----------------------------------------------------------------------------- | | AGENTS.md | Contributor workflow, style, testing, and release rules | | LICENSE | Apache License, Version 2.0 |