> ## 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.

# EdgeSpark development workflow

> Follow the full EdgeSpark development workflow for schema, storage, auth config, vars, secrets, generated types, and current deploys.

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.

```typescript server/src/defs/db_schema.ts theme={null}
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:

```bash theme={null}
edgespark db generate
edgespark db migrate
```

If you want to validate the migration chain before deploying:

```bash theme={null}
edgespark db check
```

## 2. Declare storage buckets in the repo

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

```typescript server/src/defs/storage_schema.ts theme={null}
import type { BucketDef } from "@sdk/server-types";

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

Apply the declarations:

```bash theme={null}
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`.

```typescript server/src/defs/runtime.ts theme={null}
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:

```bash theme={null}
edgespark var set PUBLIC_API_BASE_URL=https://api.example.com
```

Use secrets for anything sensitive:

```bash theme={null}
edgespark secret set STRIPE_SECRET_KEY
```

<Warning>
  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.
</Warning>

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:

```bash theme={null}
edgespark auth pull
```

Apply your changes:

```bash theme={null}
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:

```bash theme={null}
edgespark pull
```

Or only refresh SDK types:

```bash theme={null}
edgespark pull types
edgespark pull types --check
```

## 7. Deploy and iterate

Your normal loop should be:

```bash theme={null}
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

<Columns cols={2}>
  <Card title="Project structure" icon="folder" href="/guides/project-structure">
    See where `server/src/defs/`, `server/src/__generated__/`, and `configs/` live in the scaffold.
  </Card>

  <Card title="Manage secrets" icon="key" href="/guides/secrets">
    Learn the secure browser-based secret workflow in more detail.
  </Card>
</Columns>