web-dc-api: a browser SDK that puts storage, chat and identity in one DC object

One DC instance holds every capability as a module

web-dc-api is a browser-targeted SDK for decentralized applications, and the design puts every capability behind a single DC instance rather than behind separate clients. The capability table in the README lists the modules and their entry points. Wallet identity and login live on dc.auth, with accountLoginWithWallet as the key call and dc.init() as the prerequisite. User private structured data is dc.db, with initUserDB, create, find and save. Shared data is dc.keyValue, with createStore, createSharedStore, set and getWithIndex. Files and directories are dc.file, covering encrypted upload, CID download, directory traversal and streaming reads. The rest follow the same pattern: dc.comment for timelines, dc.message for an offline message box, dc.rtm for online realtime messaging, dc.aiproxy for streaming model calls and MCP, dc.rtc for calls and screen sharing, dc.whiteboard for collaborative drawing, dc.pay for packages, orders and checkout, dc.cache for short-lived distributed values, and dc.client and dc.util for node info and key helpers. The pitch in the repository description is that you can build complete agents and internet applications without any server.

Three data stores with different visibility rules

The part most likely to cause a design mistake is the set of storage options, so the README compares them in a table. ThreadDB, on dc.db, is scoped to the current user, syncs across devices, and is queried with JSON conditions, sorting and cursors, which makes it the right choice for user settings, notes and private business data. Ordinary KeyValue, from createStore, keeps one value per key per writing user, so the same key can hold different values written by different people, and it is queried by key, writer, index and time. Shared KeyValue, from createSharedStore, keeps only the latest value for a key globally, which suits global configuration, announcements and status flags. On top of that sits EntityRepository, a typed KeyValue-backed repository with save, findById and findByIndex for index queries. The README also draws a boundary the SDK does not cross: the comment system is for timeline-shaped interaction content, the message box is for sending to specific users, and neither is meant to replace a general purpose database.

Installing the package, and the one import path that works

The package is on npm, pnpm and yarn, and the install command is the same shape on all three:

npm install web-dc-api

It ships ESM, CommonJS and TypeScript types, and the README is firm that application code should import from the package root:

import { DC, LogLevel, ThemePermission } from "web-dc-api";

Deep imports are explicitly ruled out. The README says not to import from web-dc-api/lib/... or undeclared web-dc-api/dist/... paths, because the package's public exports only guarantee the root entry, web-dc-api/sw.js and web-dc-api/package.json. That is a small thing with a large practical effect: the exports map in package.json matches, with the root entry exposing types, an import path to dist/esm/index.js and a require path to dist/cjs/index.cjs, plus the two named extras. The package is marked as an ES module with sideEffects false, and it is built with Rollup, with the build scripts running npx rollup -c and a watch variant.

The browser is the target, and the README says so bluntly

The runtime requirements section is where this project tells you what it is. The main runtime target of the SDK is a modern browser, not a pure Node.js server. Core capabilities require ES2020, Web Crypto, IndexedDB and WebSocket support. File stream reading additionally needs ReadableStream, and the Worker wrappers such as wrapWorker and exposeDC need Web Worker, though using only the core modules does not make Web Worker a mandatory prerequisite. There are further constraints that have no analogue in a server library. Camera, microphone, screen sharing and Service Worker all require HTTPS, with localhost allowed for local development. Wallet login opens a wallet page, so it must be triggered from a real user interaction such as a click, or the browser will block the popup. And the package entry depends on browser globals such as window for the RTC and whiteboard capabilities, so in an SSR framework you must not import web-dc-api at the top level of a server module. You load it from a client component, or use a dynamic import with SSR turned off, and only then create the DC instance.

Initialisation is a five step handshake with a fallback endpoint

Creating the instance takes a wssUrl, a backWssUrl, appInfo, swUrl and logLevel, and the README shows the shape:

new DC({
  wssUrl,
  backWssUrl,
  appInfo,
  swUrl,
  logLevel,
});

Both WebSocket addresses are required. wssUrl is the primary chain WebSocket address, and backWssUrl is the fallback used when the primary connection fails, which may be the same address as the primary. Within appInfo, appId and appName are described as required in business terms, and the app version, icon, URL and theme colour are optional. The most consequential field is appId, which is part of the data namespace, and the README warns that you should not change it casually after launch because the application will then access a different data space. The init call is asynchronous and reports progress as a step number, with the callback receiving 0 for modules registered, 1 for the chain connected, 2 for the DC node connected, 3 for modules initialised and 4 for the temporary identity created. Step 4 is the one with a trap, which the README calls out directly.

A temporary identity exists before login, so do not trust publicKey alone

This is the sharpest edge in the documentation. The fourth init step creates a temporary identity first, so you cannot use the presence of dc.publicKey to decide whether wallet login has happened. The rule is that before calling business modules you should treat a successful accountLoginWithWallet returning an Account as the source of truth, and if you need to check on another code path, check both dc.userInfo and dc.publicKey. And on a normal exit you should call await dc.exit() rather than only auth.exitLogin() and then keep reusing the old identity fields. The Account object carries several identifiers, and the table documents them: nftAccount is the account shown to users, appAccount is the raw bytes of the account dedicated to the current application, account is the application account string usable for storage or as a business identifier, and ethAccount is the EVM compatible account. dc.publicKey?.string() is the current DC identity public key, which is only the current user's application public key after a successful wallet login.

The rest of the stack arrives as separate services

The capability table includes an extra prerequisites column, and it is where the operational shape of this SDK becomes clear. Real-time messaging needs an RTM token, or an AI agent configuration that can obtain one automatically. Real-time audio and video needs an RTC token service, and call signalling needs RTM login as well. The collaborative whiteboard needs a whiteboard token service, and its invitation feature needs RTM login. Payments need the address of a payment service. Comments need login and an explicit theme author. File access needs login, and the README also says to keep the encryption key safe. So the promise of no server of your own is real for storage and identity, but the real-time and payment features are services someone else has to run, and the SDK is a client to them. The repository also carries Chinese-language design documents at the root, including files on initialisation logic, storage, real-time voice calls, packaging, and interface documentation, which is where the details live beyond the README.

Editorial conclusion

Adopt web-dc-api if you are building a browser application that wants user-owned data, wallet-based identity and peer-to-peer features without running a backend, and you can accept that the primary target is a browser rather than a Node service. Do not adopt it for a server-side rendering stack without reading the SSR guidance, because the package entry touches window and other browser globals. Before you commit, decide your appId and never change it after launch, since it is part of the data namespace, and check the three data stores against each other, because ThreadDB, per-writer KeyValue and shared KeyValue have different visibility rules.

Frequently asked questions

Official sources

1. dcnetio/web-dc-api on GitHub
2. Issues
3. README
4. Releases