Deepspace

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 .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     # probe (--json for agents)
npx deepspace login      # only if whoami says signed-out

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    # no login needed;  seeds the dir AND wrangler `name`
cd                             # (= deploy subdomain). Edit it later in wrangler.toml, not by moving the dir.
npx deepspace dev                        # Vite + worker, HMR on localhost:5173

The two import surfaces:

import { RecordProvider, RecordScope, useQuery, useMutations, useAuth } from 'deepspace'        // frontend
import { RecordRoom, verifyJwt, CHANNELS_SCHEMA } from 'deepspace/worker'                        // 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           # 17 UI features — landing, topbar, file-manager, kanban, messaging… with auto-wired schema/routes/nav
npx deepspace add --info     # inspect a feature before installing
npx deepspace add            # install it
npx deepspace integrations list    # external APIs (weather, LLMs, stocks, sports…) via owner-pays proxy, no keys to manage

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 `. 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 | APPNAME, SCOPEID, role re-exports. | | worker.ts | Hono worker; __DOMANIFEST_ 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('items', { where: { status: 'published' }, orderBy: 'createdAt' })
const { create, put, remove } = useMutations('items')   // create returns the new recordId
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 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       # after runtime-affecting changes; multi-user features need a 2-user spec → references/testing.md
npx deepspace deploy     # → .app.space
npx deepspace deploy --env staging   # → isolated staging instance (v0.4+); rehearse risky changes first
npx deepspace kill       # if your own dev port is stuck (never kill a sibling session's)

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 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 `, 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 / 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// 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- preview config it prints. → references/preview.md

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: deepdotspace
• Source: deepdotspace/deepspace-skill
• License: MIT
• Homepage: https://deep.space

Install and usage instructions live in the source repository linked above.