Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.edgespark.dev/llms.txt

Use this file to discover all available pages before exploring further.

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