Stats
Actions
Tags
'%20stop-opacity%3D'0.16'%2F%3E%3Cstop%20offset%3D'1'%20stop-color%3D'rgb(200%2C90%2C60)'%20stop-opacity%3D'0.03'%2F%3E%3C%2FlinearGradient%3E%3C%2Fdefs%3E%3Crect%20width%3D'320'%20height%3D'200'%20fill%3D'url(%23g)'%2F%3E%3Ccircle%20cx%3D'250'%20cy%3D'56'%20r%3D'92'%20fill%3D'rgb(200%2C90%2C60)'%20fill-opacity%3D'0.06'%2F%3E%3Ccircle%20cx%3D'64'%20cy%3D'172'%20r%3D'58'%20fill%3D'rgb(200%2C90%2C60)'%20fill-opacity%3D'0.05'%2F%3E%3C%2Fsvg%3E)
From deepspace
Builds and manages real-time collaborative apps with DeepSpace SDK on Cloudflare Workers, including login, scaffolding, live sync, RBAC, and Stripe payments.
How this skill is triggered — by the user, by Claude, or both
Slash command
/deepspace:deepspaceThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
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`.
assets/integrations/README.mdassets/integrations/amazon.yamlassets/integrations/anthropic.yamlassets/integrations/anymailfinder.yamlassets/integrations/apify.yamlassets/integrations/cloudconvert.yamlassets/integrations/composio.yamlassets/integrations/elevenlabs.yamlassets/integrations/email.yamlassets/integrations/exa.yamlassets/integrations/fal.yamlassets/integrations/finance.yamlassets/integrations/firecrawl.yamlassets/integrations/freepik.yamlassets/integrations/gemini.yamlassets/integrations/github.yamlassets/integrations/google.yamlassets/integrations/index.yamlassets/integrations/latex.yamlassets/integrations/linkedin.yamlDeepSpace 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.
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.
npm create deepspace@latest <app-name> # no login needed; <app-name> seeds the dir AND wrangler `name`
cd <app-name> # (= 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
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 <feature> # inspect a feature before installing
npx deepspace add <feature> # 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 <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') // 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<T> and merges server-side. For any other hook (messaging, presence, Yjs, canvas, cron, jobs), read references/sdk-reference.md before guessing.
npx deepspace test # after runtime-affecting changes; multi-user features need a 2-user spec → references/testing.md
npx deepspace deploy # → <wrangler.name>.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 <email> can deploy the app and manage its secrets (not undeploy or transfer it). → references/collaborators.md.
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. |
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/)._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.src/pages/ — generouted scans only there; pages under src/features/<name>/ 404.(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.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/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.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.mdnpx claudepluginhub deepdotspace/deepspace-skillGuides collaborative design exploration before implementation: explores context, asks clarifying questions, proposes approaches, and writes a design doc for user approval.
Creates structured, bite-sized implementation plans from specs or requirements before writing code. Useful for breaking down multi-step tasks into testable steps with file structure and task boundaries.
Resolves in-progress git merge or rebase conflicts by analyzing history, understanding intent, and preserving both changes where possible. Runs automated checks after resolution.