The EdgeSpark declarative workflow

EdgeSpark uses a declarative workflow for app tables, storage buckets, runtime keys, and auth config. The source of truth is your repo, not a dashboard editor. Agents should edit repo-authored defs, generate migrations, apply declarative config, pull generated SDK types when needed, and never hand-write platform types.

Files to read before writing code

Every EdgeSpark project has two important categories of files:

File	Purpose	Edit it?
`server/src/defs/db_schema.ts`	App table definitions	Yes
`server/src/defs/db_relations.ts`	App relations	Yes
`server/src/defs/storage_schema.ts`	Bucket declarations	Yes
`server/src/defs/runtime.ts`	Allowed var and secret keys	Yes
`server/src/__generated__/sys_schema.ts`	Pulled system-managed tables	No
`server/src/__generated__/sys_relations.ts`	Pulled system-managed relations	No
`server/src/__generated__/edgespark.d.ts`	Generated imports from `edgespark`	No
`server/src/__generated__/server-types.d.ts`	Generated runtime SDK types	No

Never edit files in server/src/__generated__/. They are overwritten by pull commands.

Commands you should use

# App schema workflow
edgespark db generate
edgespark db migrate
edgespark db check

# Generated platform files
edgespark pull schema
edgespark pull types
edgespark pull types --check

# Bucket and auth config sync
edgespark storage apply
edgespark auth apply

Recommended workflow

Read repo-authored defs

Start with server/src/defs/db_schema.ts, server/src/defs/storage_schema.ts, and server/src/defs/runtime.ts. These files tell you what the app intends to own.

Read generated runtime types

Open server/src/__generated__/edgespark.d.ts and server/src/__generated__/server-types.d.ts before using runtime SDK imports. Do not guess import names or method signatures.

Update schema or buckets in code

Add tables in db_schema.ts, relations in db_relations.ts, buckets in storage_schema.ts, and runtime key names in runtime.ts.

Run the matching sync command

edgespark db generate
edgespark db migrate
edgespark storage apply
edgespark pull types

Write handlers against typed imports

server/src/index.ts

import { db } from "edgespark";
import { Hono } from "hono";
import { posts } from "@defs";

const app = new Hono().get("/api/posts", async (c) => {
  return c.json(await db.select().from(posts));
});

export default app;

Type check before deploy

cd server && npx tsc --noEmit

When to pull

Use edgespark pull schema when you need the latest platform-managed tables or system metadata in server/src/__generated__/. Use edgespark pull types when runtime SDK types may be stale. In automation or CI, use:

edgespark pull types --check

Use the database

How to define schema, generate migrations, and query D1 in the current scaffold.

Handling errors

How to fix stale types, migration issues, and deploy failures.

Overview

Working with EdgeSpark

Agent setup

Files to read before writing code

Commands you should use

Recommended workflow

When to pull

See also

Use the database

Handling errors

​Files to read before writing code

​Commands you should use

​Recommended workflow

​When to pull

​See also

Use the database

Handling errors

Files to read before writing code

Commands you should use

Recommended workflow

When to pull

See also