Quickstart

This guide takes you from npm create to a deployed app at <your-app>.app.space. You'll need Node.js 20 or higher and a GitHub or Google account for sign-in.

For prerequisites and account setup, see installation. For a tour of the files the scaffolder generates, see project structure.

1. Scaffold an app#

The create-deepspace package bootstraps a new project with the SDK preinstalled, a worker wired to a Durable Object, and a Vite-powered React frontend.

npm create deepspace@latest my-app
cd my-app

The scaffolder is non-interactive by default and prints a list of files it created. Pass --interactive if you want a prompt-driven wizard.

2. Start the dev server#

npx deepspace dev

This runs Vite and the worker together and opens http://localhost:5173 with hot-module reload. The CLI also writes an app-owner JWT and platform URLs to .dev.vars, so your local worker can call the live auth, storage, and integration services.

Pass --port to run multiple apps in parallel:

npx deepspace dev --port 5180

3. Sign in to the CLI#

You'll need a DeepSpace account to deploy. One-time setup:

npx deepspace login

This opens your browser for GitHub or Google OAuth and stores a long-lived session at ~/.deepspace/session. The same session covers every app on the machine.

Check status anytime with:

npx deepspace whoami

Manage your account, deployed apps, and billing at dashboard.deep.space.

4. Make it yours#

Open the project in your editor.

Key files:

• src/pages/home.tsx - the landing route. Edit the hero copy and feature list.
• src/schemas.ts - collection schemas. Add a new collection alongside the seeded users and settings.
• src/pages/_app.tsx - the provider stack. Auth and storage are already wired.
• worker.ts - the Hono worker. Add custom routes here.
• index.html - change the <title> and data-theme attribute to pick a preset.

Try adding a todos collection. For the full schema reference, see worker schemas.

// src/schemas/todos-schema.ts
import type { CollectionSchema } from 'deepspace/worker'

export const todosSchema: CollectionSchema = {
  name: 'todos',
  columns: [
    { name: 'title', storage: 'text', interpretation: 'plain' },
    { name: 'completed', storage: 'number', interpretation: { kind: 'boolean' } },
  ],
  permissions: {
    member: { read: true, create: true, update: 'own', delete: 'own' },
    admin: { read: true, create: true, update: true, delete: true },
  },
}

// src/schemas.ts
import type { CollectionSchema } from 'deepspace/worker'
import { todosSchema } from './schemas/todos-schema'
import { usersSchema } from './schemas/users-schema'
import { settingsSchema } from './schemas/admin-schema'

export const schemas: CollectionSchema[] = [usersSchema, settingsSchema, todosSchema]

Then read and write from the UI using useQuery and useMutations:

// src/pages/(protected)/todos.tsx
import { useQuery, useMutations } from 'deepspace'

type Todo = { title: string; completed: boolean }

export default function TodosPage() {
  const { records, status } = useQuery<Todo>('todos', { orderBy: 'createdAt' })
  const { create, put, remove } = useMutations<Todo>('todos')

  if (status === 'loading') return <p>Loading…</p>

  return (
    <>
      <ul>
        {records.map((r) => (
          <li key={r.recordId}>
            <input
              type="checkbox"
              checked={r.data.completed}
              onChange={(e) => put(r.recordId, { completed: e.target.checked })}
            />
            {r.data.title}
            <button onClick={() => remove(r.recordId)}>Delete</button>
          </li>
        ))}
      </ul>
      <button onClick={() => create({ title: 'New todo', completed: false })}>
        Add
      </button>
    </>
  )
}

The page lives at /todos - Generouted picks it up automatically. The (protected) route group means it's gated behind sign-in (see authentication). Save and the page hot-reloads.

5. Deploy#

When you're ready:

npx deepspace deploy

The CLI bundles the worker, uploads it to Cloudflare Workers for Platforms, syncs any secrets from .dev.vars, and registers your subdomain. The deployment reference covers the full pipeline. Within a few seconds, your app is live at:

https://my-app.app.space

Visit the URL, sign in, and add a todo. Open the same URL in a second tab - edits sync between them instantly.

Next steps#

You have a working app. Where to go from here:

• Authentication - pick a public, gated, or mixed model.
• Presence and cursors - show who's online and broadcast cursor positions.
• Payments - subscriptions and one-time products via Stripe.
• AI chat - streamed Claude or GPT with tool use over your records.