EdgeSpark project structure

An EdgeSpark project created with edgespark init has a root project plus separate server/ and web/ apps. Your repo owns the app schema and bucket declarations in server/src/defs/. EdgeSpark generates runtime types and platform-managed schema files in server/src/__generated__/.

Directory layout

Key files

`server/src/index.ts`

Your server entry point. Define a static Hono app and export it as the default export:

server/src/index.ts

import { db } from "edgespark";
import { auth } from "edgespark/http";
import { Hono } from "hono";
import { posts } from "@defs";

const app = new Hono()
  .get("/api/posts", async (c) => {
    const rows = await db.select().from(posts);
    return c.json(rows);
  })
  .get("/api/me", (c) => {
    return c.json({ email: auth.user.email });
  });

export default app;

EdgeSpark requires your server module to default-export the Hono app. Keep the contract explicit with export default app;. The variable name can differ, but the module’s default export must be the app instance. You can split routes across multiple files and import them into server/src/index.ts. All app routes still need to live under /api/*, /api/public/*, or /api/webhooks/*.

`server/src/defs/`

Repo-authored definitions. This is where you declare your app schema, storage buckets, and typed runtime keys:

File	Contains
`db_schema.ts`	Your Drizzle table definitions
`db_relations.ts`	Your Drizzle relations
`storage_schema.ts`	Your bucket declarations
`runtime.ts`	`VarKey` and `SecretKey` unions for vars and secrets
`index.ts`	Required barrel that re-exports defs and generated files

These are the files you edit. After changing them, use the matching CLI command:

edgespark db generate and edgespark db migrate for db_schema.ts
edgespark storage apply for storage_schema.ts
edgespark auth apply for configs/auth-config.yaml

`server/src/generated/`

Generated files from the platform. Do not edit these manually.

File	Contains
`sys_schema.ts`	Platform-managed database tables
`sys_relations.ts`	Relations for platform-managed tables
`edgespark.d.ts`	Generated module declarations for `edgespark` imports
`server-types.d.ts`	Generated SDK types used by the scaffold and defs

Run edgespark pull to refresh generated files. edgespark pull schema refreshes pulled system schema, and edgespark pull types refreshes generated SDK types.

`edgespark.toml`

Project configuration file created by edgespark init. It points EdgeSpark at your server and web directories:

edgespark.toml

project_id = "abc123"

[server]
path = "server"

[web]
path = "web"
output_path = "web/dist"

Commit this file. The CLI reads it to know which project to deploy and where each part of the scaffold lives.

`configs/auth-config.yaml`

Local auth configuration file. Use it with edgespark auth pull and edgespark auth apply when you need to manage sign-in methods and auth settings in code.

`web/src/lib/edgespark.ts`

The scaffolded browser client entry point. It creates the @edgespark/web singleton used for frontend auth, managed auth UI, and same-origin API calls.

Web import alias

The web scaffold also configures the @/ alias for web/src/*, so imports such as @/lib/edgespark and @/hooks/useAuth work out of the box.

Root `package.json`

The root package is intentionally minimal. It is not a workspace. Install dependencies separately in server/ and web/.

Install dependencies

cd server && npm install
cd ../web && npm install

Organizing routes

As your project grows, split routes into separate files:

server/src/index.ts

import { auth } from "edgespark/http";
import { Hono } from "hono";
import { postsRoutes } from "./routes/posts";
import { usersRoutes } from "./routes/users";

const app = new Hono()
  .get("/api/me", (c) => c.json({ email: auth.user.email }));

app.route("/api/posts", postsRoutes);
app.route("/api/users", usersRoutes);

export default app;

server/src/routes/posts.ts

import { db } from "edgespark";
import { Hono } from "hono";
import { posts } from "@defs";

export const postsRoutes = new Hono().get("/", async (c) => {
  const rows = await db.select().from(posts);
  return c.json(rows);
});

The client object

What the runtime SDK provides and how imports from edgespark work.

Declarative workflow

How repo-authored defs and generated files stay in sync.

Quickstart

Create your first project and deploy it in minutes.

CLI commands

edgespark init options and the rest of the public CLI surface.

Getting started

Concepts

Build

Deploy

Directory layout

Key files

`server/src/index.ts`

`server/src/defs/`

`server/src/generated/`

`edgespark.toml`

`configs/auth-config.yaml`

`web/src/lib/edgespark.ts`

Web import alias

Root `package.json`

Install dependencies

Organizing routes

See also

The client object

Declarative workflow

Quickstart

CLI commands

​Directory layout

​Key files

​server/src/index.ts

​server/src/defs/

​server/src/__generated__/

​edgespark.toml

​configs/auth-config.yaml

​web/src/lib/edgespark.ts

​Web import alias

​Root package.json

​Install dependencies

​Organizing routes

​See also

The client object

Declarative workflow

Quickstart

CLI commands

Directory layout

Key files

`server/src/index.ts`

`server/src/defs/`

`server/src/generated/`

`edgespark.toml`

`configs/auth-config.yaml`

`web/src/lib/edgespark.ts`

Web import alias

Root `package.json`

Install dependencies

Organizing routes

See also