Project structure

A scaffolded app is a Vite + React project with a Cloudflare Worker entry point. This page lists what npm create deepspace@latest ships and what each file is for.

Top-level files#

Agent tooling#

src/ - application code#

Pages and layouts#

Routing is file-based via generouted: every file under src/pages/ becomes a route. Folders in parentheses are route groups - they apply a layout without appearing in the URL.

The three route tiers#

A page's folder decides its capabilities. The scaffold ships three tiers, and each carries a contract:

Put each page in the lowest tier that satisfies it: static if it needs no data, (app)/ if it needs data but should work signed out, (app)/(protected)/ only when the page is meaningless without a user.

Components#

Data layer#

Schemas are imported by worker.ts and baked into the bundle at deploy time. There is no runtime schema registry - adding or changing a schema requires a redeploy.

Worker-side route modules#

worker.ts stays thin by delegating to these:

Theming and navigation#

Feature surfaces#

These ship pre-wired with empty defaults. Edit to populate, or delete the file if the feature isn't needed. Use npx deepspace add <feature> to install additional surfaces.

public/ - static assets#

Large images and media should not live here or in Git - see deepspace app files.

tests/ - Playwright and Vitest specs#

Run with npx deepspace test run. See Testing.

App identity#

wrangler.toml carries two different names, and the distinction matters:

name = "my-app"                              # subdomain label - my-app.app.space

[vars]
DEEPSPACE_APP_ID = "app_01KZAA0A8YCS2..."    # immutable identity
APP_NAME = "my-app"

DEEPSPACE_APP_ID never changes. Data, secrets, collaborators, releases, and the cloud repo all key to it, which is why renaming an app (changing name, then deploy --rename) is safe: the URL moves, everything else travels. deepspace app init mints the id; --new-id deliberately forks the repo into a separate app.

The Durable Object manifest#

worker.ts exports a __DO_MANIFEST__ constant listing the DO classes the app uses:

export const __DO_MANIFEST__ = [
  { binding: 'RECORD_ROOMS', className: 'AppRecordRoom', sqlite: true },
  { binding: 'YJS_ROOMS', className: 'AppYjsRoom', sqlite: true },
  { binding: 'CANVAS_ROOMS', className: 'AppCanvasRoom', sqlite: true },
  { binding: 'PRESENCE_ROOMS', className: 'AppPresenceRoom', sqlite: true },
  { binding: 'CRON_ROOMS', className: 'AppCronRoom', sqlite: true },
  { binding: 'JOB_ROOMS', className: 'AppJobRoom', sqlite: true },
] as const satisfies DOManifest

Each entry has a binding (the env binding name your Hono routes look up), a className (the DO subclass exported from the same file), and sqlite (true for SQLite-backed DOs).

This constant exists for TypeScript inference. The Env interface picks up the binding names from it automatically:

interface Env extends DOBindings<typeof __DO_MANIFEST__> {
  // ...your secrets and custom bindings
}

The deploy-time bindings and migrations are declared in wrangler.toml under [durable_objects] and [[migrations]]; keep the two in sync. Don't remove classes you no longer use without clearing their stored data first - records persist across deploys, and rollback refuses to drop a class without --allow-do-deletion.

Next steps#

• Quickstart - build something with these files.
• Architecture - how everything fits together.
• Data model - collections, records, and the envelope shape.