Develop EdgeSpark apps locally with edgespark dev

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.

​

Start the dev server

edgespark dev

edgespark dev --port 8080

edgespark dev --reset

​

What runs locally

• Local D1 — a SQLite file managed by Miniflare. The schema in server/src/defs/db_schema.ts is pushed via drizzle-kit push before the workers start, and re-pushed after every save; destructive changes (drop column, NOT NULL without a default) auto-apply and may truncate tables.
• Local R2 — a filesystem-backed bucket. Presigned URL uploads work through a local S3 proxy.
• Local auth — email/password ready out of the box. Sessions use a local KV namespace.
• Reverse proxy on one port — http://localhost:7775/api/* hits the worker; every other path hits the Vite dev server. Same origin, so cookies and CORS are not a problem.
• Hot reload — backend source changes trigger an esbuild rebuild and reload the worker without a process restart. Frontend uses Vite HMR.
• Dev-mode email — no email is sent. Verification URLs are stored in a dev-only row keyed by email, and /api/_es/dev/auto-verify replays them through Better Auth so signup proceeds without a mailbox round-trip. To test real email delivery, deploy to a cloud environment.

​

Local values with .env.local

# Google OAuth — add http://localhost:7775/api/_es/auth/callback/google
# as a redirect URI in your Google OAuth app
GOOGLE_CLIENT_ID=123-xxx.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-xxxxxxxxxxxxxxxxxxxxxxxx

# External APIs — use test keys locally
STRIPE_SECRET_KEY=sk_test_...

⚠ GOOGLE_CLIENT_SECRET declared in runtime.ts but not in .env.local
  → Google sign-in is unavailable locally until configured

​

Dev-mode email and auto-verify

[edgespark] Verification URL for alice@example.com — auto-verify via /api/_es/dev/auto-verify

​

Hot reload behavior

​

Database and storage in dev

• Schema sync — the CLI runs drizzle-kit push against local D1 before the workers accept traffic, and again after every backend rebuild, applying server/src/defs/db_schema.ts directly. No migration files are needed locally — the production deploy still runs edgespark db migrate.
• D1 queries — identical API to production; SQL validation runs in the sidecar the same way.
• R2 uploads and downloads — stored under .edgespark/state/r2/.
• Presigned URLs — the sidecar signs URLs against a local S3 proxy. Uploading to a presigned URL writes to the local bucket.

​

Seed data with server/dev/seed.ts

import { defineSeed } from "@edgespark/devkit";
import type { SqliteRemoteDatabase } from "drizzle-orm/sqlite-proxy";
import { posts } from "../src/defs/db_schema";
import type * as schema from "../src/defs/db_schema";

export default defineSeed<SqliteRemoteDatabase<typeof schema>>(async (ctx) => {
  const { user, fetch } = await ctx.auth.createUser({
    email: "alice@example.com",
    password: "correct-horse-battery-staple",
    name: "Alice",
  });

  await ctx.db.insert(posts).values([
    { title: "Hello world", authorId: user.id },
    { title: "Second post", authorId: user.id },
  ]);

  const response = await fetch("/api/posts");
  console.log(`Seeded ${user.email} with ${(await response.json()).length} posts`);
});

​

Local state and logs

.edgespark/
├── state/
│   ├── d1/          # SQLite files (survive restarts)
│   ├── r2/          # Stored objects (survive restarts)
│   ├── kv/          # KV data (sessions, auth)
│   └── secrets.json # Auto-generated dev-only internals
└── logs/
    ├── dev.log      # Current session
    └── dev.log.prev # Previous session (rotated at 5 MB)

​

OAuth providers locally

http://localhost:7775/api/_es/auth/callback/<provider>

​

Troubleshooting

​

See also