Skip to main content
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 changeEdit thisThen run
App database schemaserver/src/defs/db_schema.tsedgespark db generate && edgespark db migrate
App database relationsserver/src/defs/db_relations.tsUsually edgespark pull types, and migrations only if the schema changed
Storage bucketsserver/src/defs/storage_schema.tsedgespark storage apply
Runtime secret and var key namesserver/src/defs/runtime.tsedgespark secret set ... or edgespark var set ...
Auth configurationconfigs/auth-config.yamledgespark auth apply
Pulled platform-managed filesNothing in your app repoedgespark pull or edgespark pull types
Deploy and testYour app codeedgespark 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:
  1. Edit server/src/defs/db_schema.ts
  2. Run edgespark db generate && edgespark db migrate
  3. Edit server/src/defs/storage_schema.ts
  4. Run edgespark storage apply
  5. Edit server/src/defs/runtime.ts
  6. Run edgespark secret set YOUR_SECRET_KEY
  7. Write route code in server/src/index.ts or route files
  8. Run edgespark pull types if needed
  9. Run edgespark deploy --dry-run
  10. Run edgespark deploy
  11. Run edgespark log tail

​
See also

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.
Last modified on April 7, 2026