What Are You Building?
A few common project shapes, and the exact nice-code packages each one needs — so you install what you'll use and start on the right page.
nice-code is a set of libraries you adopt as you need them, not a framework you buy into whole. Two planes carry the work — actions (call functions) and realms (live shared state) — both over one secure connection; four supporting packages fit around them. Find the row closest to what you’re building, install that set, and start where it points.
Project shapes
Section titled “Project shapes”| You’re building… | Install | Start here | See it |
|---|---|---|---|
| A multiplayer game / collaborative app — presence, positions, a shared document | @nice-code/realm @nice-code/wire | Realm quick start → Realm Mental Model | Tank Shooter |
| A live dashboard / feed — many viewers, server-driven updates | @nice-code/realm @nice-code/wire | Presence Realms | Pixel Plaza |
| A typed API / RPC layer — the client calls the server, fully typed | @nice-code/action @nice-code/error + a validator | Action quick start | Playground |
| A React app with server push — API calls and the server pushing back | @nice-code/action @nice-code/error + a validator | Bi-directional | Playground |
| Both — an app with an API and live state | @nice-code/action @nice-code/realm @nice-code/error | Both planes on one connection | Playground |
| A React Native / Expo app — any of the above, on-device | your set above + two polyfills | React Native / Expo | — |
| Just better errors anywhere in TypeScript | @nice-code/error | Error Domains | — |
| Just a reactive store for local UI state | @nice-code/state immer | Stores | — |
The supporting cast
Section titled “The supporting cast”Whichever planes you pick, these fit around them — and each stands alone if that’s all you need:
@nice-code/error— typed, serializable errors. Actions declare what they throw; realm rules reject with them; both ends catch the sameNiceError. The one error vocabulary the whole stack speaks.@nice-code/state— a small Immer-backed store with fine-grained selectors. A realm’sstoreis one of these, so synced and local state read identically.@nice-code/util— typed storage adapters (browser, Durable Object, memory) and the crypto that authenticates every secure connection.@nice-code/common-errors— ready-made validation errors + Hono middleware, so a bad request comes back as a typed error, not a bare 400.@nice-code/devtools— one call in dev opens a window over every action, realm, store, and wire frame. Inert in production.
Hosting
Section titled “Hosting”Deploying to the edge? Hosting on Cloudflare covers the three Durable Object shapes (actions, realm-only, or both on one socket). Everything runs on Bun, Node, and Workers too — the serving pages show the wiring.