> ## Documentation Index
> Fetch the complete documentation index at: https://docs.deep.space/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Scaffold, run, and deploy a real-time app.

This guide takes you from `npm create` to a deployed app at `<your-app>.app.space`. You'll need [Node.js 20 or higher](https://nodejs.org/) and a GitHub or Google account for sign-in.

For prerequisites and account setup, see [installation](/get-started/installation). For a tour of the files the scaffolder generates, see [project structure](/get-started/project-structure).

## 1. Scaffold an app

The `create-deepspace` package bootstraps a new project with the SDK preinstalled, a [worker](/concepts/architecture) wired to a [Durable Object](/concepts/architecture#durable-objects), and a Vite-powered React frontend.

```bash theme={null}
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.

<Tip>
  The app name becomes the deploy subdomain. It must be lowercase alphanumeric with optional dashes, up to 63 characters. You can rename later by editing `wrangler.toml`.
</Tip>

## 2. Start the dev server

```bash theme={null}
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:

```bash theme={null}
npx deepspace dev --port 5180
```

## 3. Sign in to the CLI

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

```bash theme={null}
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:

```bash theme={null}
npx deepspace whoami
```

Manage your account, deployed apps, and billing at [dashboard.deep.space](https://dashboard.deep.space).

## 4. Make it yours

Open the project in your editor.

<Tip>
  The scaffold ships a `CLAUDE.md` that points coding agents at the [DeepSpace skill](https://github.com/deepdotspace/deepspace-skill) - the canonical SDK reference for Claude Code, Cursor, and other agents. Install it once with `npx skills@latest add deepdotspace/deepspace-skill` so your assistant has accurate type signatures and patterns.
</Tip>

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](/concepts/data-model). For the full schema reference, see [worker schemas](/sdk-reference/worker/schemas).

```ts theme={null}
// 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 },
  },
}
```

```ts theme={null}
// 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`](/sdk-reference/client/records#usequery\<t>-collection-options) and [`useMutations`](/sdk-reference/client/records#usemutations\<t>-collection):

```tsx theme={null}
// 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](/guides/authentication)). Save and the page hot-reloads.

## 5. Deploy

When you're ready:

```bash theme={null}
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](/concepts/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](/guides/authentication) - pick a public, gated, or mixed model.
* [Presence and cursors](/guides/presence-and-cursors) - show who's online and broadcast cursor positions.
* [Payments](/guides/payments) - subscriptions and one-time products via Stripe.
* [AI chat](/guides/ai-chat) - streamed Claude or GPT with tool use over your records.