| name | deepspace |
| description | Use when building or maintaining real-time collaborative apps with the DeepSpace SDK on Cloudflare Workers — scaffolding new apps, adding features, debugging a `worker.ts` that imports from `deepspace` / `deepspace/worker` or uses `RecordRoom`, `__DO_MANIFEST__`, or `npx deepspace`. Also use when the user mentions DeepSpace or app.space, or asks for anything involving real-time sync, multiplayer state, live cursors / presence, whiteboards or canvases, collaborative text editing (Yjs), channel-based chat, per-role permissions (RBAC), Durable Object rooms, Stripe-backed subscriptions / paywalls / one-time products / tips / refunds, or one-package deploy to `.app.space` — even if they don't name DeepSpace explicitly.
|
DeepSpace builds and deploys real-time collaborative apps on Cloudflare Workers in one package — auth, RBAC, live data subscriptions, messaging, payments — and ships them to <name>.app.space.
Two hard gates come first: the user must be logged in, and the app must be scaffolded rather than hand-built.
1. Log in first
Every command that runs anything — dev, test, deploy — needs a signed-in DeepSpace account. There's no local-only mode: dev connects to deployed dev workers.
npx deepspace whoami
npx deepspace login
login opens a browser OAuth tab and polls up to 10 minutes — pause and let the user finish it at the keyboard. Don't wrap it in timeout / sleep / kill (that aborts the OAuth poll), and don't ask for their password. One login covers every app on the machine. Full login + CLI contract → references/cli.md.
2. Scaffold the app
npm create deepspace@latest <app-name>
cd <app-name>
npx deepspace dev
The two import surfaces:
import { RecordProvider, RecordScope, useQuery, useMutations, useAuth } from 'deepspace'
import { RecordRoom, verifyJwt, CHANNELS_SCHEMA } from 'deepspace/worker'
3. Build — discover before you hand-build
Run both catalogs first thing in any build — never skip on a hunch that nothing fits. The one-line names can't tell you what a block does; only add --info / integrations info can, so don't rule one out from the list alone.
npx deepspace add --list
npx deepspace add --info <feature>
npx deepspace add <feature>
npx deepspace integrations list
When you build by hand, where things live (load the matching reference from the table below as you touch each):
| Path | Purpose |
|---|
src/schemas.ts + src/schemas/ | Collection schemas. Ships usersSchema (required, don't rename) + settingsSchema. |
src/pages/ | File routes (generouted). Top level = static, (app)/ = providers + data hooks, (app)/(protected)/ = sign-in gated. _app.tsx is the root shell — extend, don't replace. → references/auth.md |
src/themes.ts + src/themes.css | Theme tokens, set on <html data-theme>. Ships two placeholders (slate dark default, paper light example) — create the app's own theme; don't ship a placeholder. → references/uiux.md §2 |
src/constants.ts | APP_NAME, SCOPE_ID, role re-exports. |
worker.ts | Hono worker; __DO_MANIFEST__ declares the DO classes. AI chat routes live in src/ai/chat-routes.ts. → references/architecture.md |
The three hooks you'll reach for constantly:
const { records, status } = useQuery<Item>('items', { where: { status: 'published' }, orderBy: 'createdAt' })
const { create, put, remove } = useMutations<Item>('items')
const { isSignedIn, isLoaded } = useAuth()
Records are envelopes — { recordId, data: T, createdBy, createdAt, updatedAt }. User fields live under .data (r.data.title, never r.title). put(recordId, patch) takes a Partial<T> and merges server-side. For any other hook (messaging, presence, Yjs, canvas, cron, jobs), read references/sdk-reference.md before guessing.
4. Test, then deploy
npx deepspace test
npx deepspace deploy
npx deepspace deploy --env staging
npx deepspace kill
Deploy's subdomain is wrangler.toml's name, not the folder. On a first deploy, clear the pre-deploy checklist in references/uiux.md §5 (real home replacing the placeholder stub, an own theme created — not slate/paper, no browser-default primitives). Deploy mechanics, the .dev.vars contract, secret handling, and multi-env / staging (--env, incl. the client-APP_NAME sync gotcha) → references/deploy.md. The full CLI catalog (integrations, test-accounts, screenshot, domain, library, dev/kill flags) → references/cli.md.
App secrets live in the platform's encrypted store, not in files: npx deepspace secrets set KEY=value — no setup step; worker code reads env.KEY in dev and prod alike, and the store (keyed by the app's immutable DEEPSPACE_APP_ID in wrangler.toml) is the only deploy input — never hand-edit .dev.vars. → references/secrets.md. The id is the app; the name is just the URL (renames, forking a cloned repo with init --new-id, ownership transfer → references/app-identity.md). Teammates the owner adds with npx deepspace collaborators add <email> can deploy the app and manage its secrets (not undeploy or transfer it). → references/collaborators.md.
Load a reference when you reach its surface
Before editing files, scan this table and Read every row whose trigger matches — in the same turn, before the first edit. Each reference also declares its own "Load when…" gate on line 1; that gate is authoritative.
| Reference | Read before |
|---|
references/workflow.md | Starting an end-to-end app build — a new product, a clone, or any multi-feature request. |
references/cli.md | The login contract, the full CLI command catalog (dev/kill/integrations/test-accounts/screenshot/library), and the test command. |
references/deploy.md | Deploy mechanics, the .dev.vars contract, secret handling, and multi-environment / staging deploys (deploy --env). |
references/secrets.md | Managing app secrets, using npx deepspace secrets, migrating a legacy .dev.vars app, configs/environments, or generated-cache behavior. |
references/app-identity.md | App ids (DEEPSPACE_APP_ID), forking a cloned repo (init --new-id), renames, apps/undeploy, ownership transfer. |
references/legacy-migration.md | A pre-app-id app (name-based id in apps, no DEEPSPACE_APP_ID), or your own deploy failing with "name … taken by another app". |
references/collaborators.md | Adding teammates to an app, deploying an app you don't own, or a 403 on deploy/secrets as a non-owner. |
references/sdk-reference.md | Any hook / type / export beyond useQuery / useMutations / useAuth — messaging, game rooms, presence, Yjs, canvas, R2. Open before node_modules/deepspace/dist/*.d.ts. |
references/schemas.md | Defining a collection, picking a permission rule, debugging "why can't this user see/edit X." |
references/auth.md | Choosing the auth model (public / gated / mixed), adding <AuthGate>, customizing the sign-in fallback. |
references/architecture.md | Editing worker.ts, adding DO classes / cross-app scopes (workspace:* / dir:* / conv:*), the identity-strip security model, app-name rules. |
references/server-actions.md | Privileged writes that bypass the caller's RBAC. |
references/ai-chat.md | A streamed chat UI with tool use over the app's records. |
references/cron.md | Scheduled tasks via AppCronRoom + useCronMonitor. |
references/jobs.md | Durable background work via AppJobRoom + useJobs (AI generation, exports, renders). |
references/bindings.md | Custom Cloudflare bindings (Vectorize / R2 / KV / D1 / Queues / AI / Browser / Hyperdrive), "auto" autoprovisioning, per-tenant metering. |
references/integrations.md | Calling external APIs through integration.post(...) and the discovery CLI. Itself points to integrations/livekit.md (audio/video rooms) and integrations/google-oauth.md (Gmail / Calendar / Drive / Contacts) when you reach those. |
references/payments.md | Anything involving money — Stripe, paywalls, subscriptions, pricing, "Upgrade" buttons, tips, refunds. Never hand-roll Stripe. |
references/domain.md | Buying / attaching / managing a custom domain. |
references/uiux.md | Theme, home page, primitives, "feels generic" feedback. Before <select> / window.confirm / window.alert. |
references/testing.md | Writing/extending specs, multi-user flows, debugging flaky tests. |
references/preview.md | Using the Claude desktop preview tool (preview_start), or when the preview shows stale code / edits never appear — especially inside a .claude/worktrees/* worktree. |
references/landing-design.md | Marketing / landing / splash pages. |
Traps worth knowing up front
- The scaffold shell is a placeholder, not a design. The stub home page, minimal nav bar, and
slate/paper themes are deliberately bare — never extend or imitate them as "the house style." Design the app's own look and theme (→ references/uiux.md; landing pages → references/landing-design/).
- Scaffold's UI primitives shadow the SDK.
_app.tsx uses ToastProvider from src/components/ui/, not deepspace. Importing useToast (or any local primitive) from deepspace throws at runtime. Import from ../components/ui.
- Page files belong in
src/pages/ — generouted scans only there; pages under src/features/<name>/ 404.
- Data/auth hooks only work under
(app)/ — providers mount in (app)/_layout.tsx, so a top-level (static) page calling useAuth/useQuery crashes at render. Details: the scaffold's CLAUDE.md § "Static vs dynamic pages" and references/auth.md.
- Don't kill or assume a clean port 5173.
tests/playwright.config.ts ships reuseExistingServer: true, so if a sibling session already holds 5173 your tests silently run against its app. Don't kill another session's processes — use npx deepspace dev --port 5174 and match webServer.port + use.baseURL in the config. → references/testing.md
- Never put identity in WebSocket URLs or
/api/* headers — the starter strips userId/role/etc. and re-applies them only from a verified JWT. Caller identity is always the JWT subject. → references/architecture.md
- Preview tool shows stale code / your edits never appear — if you're editing in
.claude/worktrees/*, the desktop preview tool serves the MAIN repo, not the worktree. Run npx deepspace dev once in the worktree and use the wt-<name> preview config it prints. → references/preview.md
