EdgeSpark development workflow

This page is the fastest way to understand how an EdgeSpark project is meant to be changed day to day. The current scaffold is repo-driven: you edit files in the project, run the matching CLI command, deploy, and iterate.

The short version

What you want to change	Edit this	Then run
App database schema	`server/src/defs/db_schema.ts`	`edgespark db generate && edgespark db migrate`
App database relations	`server/src/defs/db_relations.ts`	Usually `edgespark pull types`, and migrations only if the schema changed
Storage buckets	`server/src/defs/storage_schema.ts`	`edgespark storage apply`
Runtime secret and var key names	`server/src/defs/runtime.ts`	`edgespark secret set ...` or `edgespark var set ...`
Auth configuration	`configs/auth-config.yaml`	`edgespark auth apply`
Pulled platform-managed files	Nothing in your app repo	`edgespark pull` or `edgespark pull types`
Deploy and test	Your app code	`edgespark deploy`, `edgespark deploy --dry-run`, and `edgespark log tail`

1. Change your app schema in the repo

Your app tables live in server/src/defs/db_schema.ts, not in a dashboard table editor.

server/src/defs/db_schema.ts

import { integer, sqliteTable, text } from "drizzle-orm/sqlite-core";

export const posts = sqliteTable("posts", {
  id: integer("id").primaryKey({ autoIncrement: true }),
  title: text("title").notNull(),
  authorId: text("author_id").notNull(),
});

After you edit the file:

edgespark db generate
edgespark db migrate

If you want to validate the migration chain before deploying:

edgespark db check

2. Declare storage buckets in the repo

Buckets live in server/src/defs/storage_schema.ts.

server/src/defs/storage_schema.ts

import type { BucketDef } from "@sdk/server-types";

export const uploads: BucketDef<"uploads"> = {
  bucket_name: "uploads",
  description: "User uploaded files",
};

Apply the declarations:

edgespark storage apply

3. Keep runtime keys explicit

When your code reads vars or secrets, declare the allowed keys in server/src/defs/runtime.ts.

server/src/defs/runtime.ts

export type VarKey =
  | "PUBLIC_API_BASE_URL";

export type SecretKey =
  | "STRIPE_SECRET_KEY";

This keeps runtime config explicit and typed.

4. Treat secrets differently from vars

Use vars for plain configuration values:

edgespark var set PUBLIC_API_BASE_URL=https://api.example.com

Use secrets for anything sensitive:

edgespark secret set STRIPE_SECRET_KEY

Secret values never go through the terminal, agent context, or third-party LLM APIs such as Anthropic, Google, or OpenAI. EdgeSpark opens a secure browser URL so the human owner can enter the secret value directly.

That distinction matters:

edgespark var set is for non-sensitive configuration
edgespark secret set is for credentials, signing keys, and tokens

5. Manage auth in `configs/auth-config.yaml`

Auth configuration lives in configs/auth-config.yaml. Pull the current config:

edgespark auth pull

Apply your changes:

edgespark auth apply

Use this for sign-in methods, provider configuration, and auth behavior that belongs in project config rather than route code.

6. Refresh generated types when needed

EdgeSpark also generates runtime type declarations in server/src/__generated__/. Refresh them with:

edgespark pull

Or only refresh SDK types:

edgespark pull types
edgespark pull types --check

7. Deploy and iterate

Your normal loop should be:

edgespark deploy
edgespark log tail

New projects currently expose one default production environment, so edgespark deploy updates that environment directly. Use edgespark deploy --dry-run when you want build validation without a live deploy.

A practical sequence

If you add a feature that needs a table, a bucket, and a secret, the normal order is:

Edit server/src/defs/db_schema.ts
Run edgespark db generate && edgespark db migrate
Edit server/src/defs/storage_schema.ts
Run edgespark storage apply
Edit server/src/defs/runtime.ts
Run edgespark secret set YOUR_SECRET_KEY
Write route code in server/src/index.ts or route files
Run edgespark pull types if needed
Run edgespark deploy --dry-run
Run edgespark deploy
Run edgespark log tail

Project structure

See where server/src/defs/, server/src/__generated__/, and configs/ live in the scaffold.

Manage secrets

Learn the secure browser-based secret workflow in more detail.

Getting started

Concepts

Build

Deploy

The short version

1. Change your app schema in the repo

2. Declare storage buckets in the repo

3. Keep runtime keys explicit

4. Treat secrets differently from vars

5. Manage auth in `configs/auth-config.yaml`

6. Refresh generated types when needed

7. Deploy and iterate

A practical sequence

See also

Project structure

Manage secrets

​The short version

​1. Change your app schema in the repo

​2. Declare storage buckets in the repo

​3. Keep runtime keys explicit

​4. Treat secrets differently from vars

​5. Manage auth in configs/auth-config.yaml

​6. Refresh generated types when needed

​7. Deploy and iterate

​A practical sequence

​See also

Project structure

Manage secrets

The short version

1. Change your app schema in the repo

2. Declare storage buckets in the repo

3. Keep runtime keys explicit

4. Treat secrets differently from vars

5. Manage auth in `configs/auth-config.yaml`

6. Refresh generated types when needed

7. Deploy and iterate

A practical sequence

See also