What Are You Building?
Common project shapes and the nice-code packages each one needs, so you install only what you'll use and start on the right page.
nice-code is a set of libraries you adopt as you need them. Two do the main work: actions call functions and realms share live state. These are the two planes, and both run over one secure connection. The 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. Each also works on its own if that’s all you need:
- @nice-code/error — typed, serializable errors. Actions declare what
they throw, realm rules reject with them, and both ends catch the same
NiceError. Every package uses this one error vocabulary. - @nice-code/state — a small Immer-backed store with fine-grained
selectors. A realm’s
storeis one of these, so you read synced and local state the same way. - @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 and Hono middleware, so a bad request comes back as a typed error instead of a bare 400.
- @nice-code/devtools — one call in dev opens a window onto every action, realm, store, and wire frame. Inert in production.
Two more are for the environment your app runs in, rather than the app itself:
- @nice-code/commander — your dev environment as one typed config: the processes, the one-shot checks, and what depends on what. A setup step becomes an id you run instead of a paragraph about which terminals to open.
- @nice-code/process — the process supervisor commander is built on, usable alone: spawn a child process with readiness, restart backoff, log capture, and reliable cross-platform teardown.
Hosting
Section titled “Hosting”If you’re deploying to the edge, Hosting on Cloudflare covers the three Durable Object shapes: actions, realm-only, or both on one socket. Everything also runs on Bun, Node, and Workers, and the serving pages show the wiring.