building-edgespark-apps

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

EdgeSpark App Development

EdgeSpark 应用开发

Use this skill for EdgeSpark-specific implementation and workflow decisions.

This skill is not EdgeSpark documentation. For exact contracts, read source, generated types, CLI help, and docs/Mintlify MCP. Use this skill for workflow, guardrails, and bug-prevention.

The reliable public surface in this repo is:

the
```
edgespark
```
CLI
scaffolded project structure from
```
edgespark init
```
generated
```
src/__generated__/edgespark.d.ts
```
generated
```
src/__generated__/server-types.d.ts
```
the
```
@edgespark/web
```
browser SDK

Learn from older examples, but do not inherit old patterns blindly. In particular, do not treat

@edgespark/client

and

renderAuthUI()

as the default path for new code.

本技能适用于EdgeSpark相关的实现和工作流决策。

本技能并非EdgeSpark文档。如需确切的接口定义，请阅读源代码、生成的类型文件、CLI帮助文档以及docs/Mintlify MCP。本技能用于指导工作流、提供规范并预防错误。

本仓库中可靠的公开内容包括：

```
edgespark
```
CLI
通过
```
edgespark init
```
生成的项目结构
生成的
```
src/__generated__/edgespark.d.ts
```
生成的
```
src/__generated__/server-types.d.ts
```
```
@edgespark/web
```
浏览器SDK

可以参考旧示例，但不要盲目沿用旧模式。尤其注意，不要将

@edgespark/client

和

renderAuthUI()

作为新代码的默认方案。

Read Order

阅读顺序

Read only what is needed for the task:

```
edgespark.toml
```
repo or project agent instruction file (
```
AGENTS.md
```
,
```
CLAUDE.md
```
, or
```
GEMINI.md
```
)
```
src/__generated__/edgespark.d.ts
```
```
src/__generated__/server-types.d.ts
```

src/defs/index.ts

src/defs/db_schema.ts

src/defs/db_relations.ts

src/defs/runtime.ts

src/defs/storage_schema.ts

node_modules/@edgespark/web/dist/index.d.ts

when installed

Then load the specific reference you need:

Day-to-day development workflows by surface: dev-workflow.md
Scaffold layout and generated-file rules: project-structure.md
Error-prone server-side usage patterns: server-patterns.md
Small web usage patterns for
```
@edgespark/web
```
: web-patterns.md
Auth config, OAuth providers, callback URLs: auth-patterns.md

仅阅读完成任务所需的内容：

```
edgespark.toml
```
仓库或项目的Agent说明文件（
```
AGENTS.md
```
、
```
CLAUDE.md
```
或
```
GEMINI.md
```
）
```
src/__generated__/edgespark.d.ts
```
```
src/__generated__/server-types.d.ts
```

src/defs/index.ts

、

src/defs/db_schema.ts

、

src/defs/db_relations.ts

、

src/defs/runtime.ts

、

src/defs/storage_schema.ts

安装完成后的

node_modules/@edgespark/web/dist/index.d.ts

然后加载你需要的特定参考文档：

按场景划分的日常开发工作流：dev-workflow.md
脚手架布局和生成文件规则：project-structure.md
易出错的服务器端使用模式：server-patterns.md
```
@edgespark/web
```
的小型Web使用模式：web-patterns.md
认证配置、OAuth提供商、回调URL：auth-patterns.md

Hard Rules

硬性规则

Run
```
edgespark <command> --help
```
before assuming flags or exact behavior.
Run
```
edgespark
```
commands on behalf of the user. Only hand off steps that explicitly require a human browser action.
Never run multiple
```
edgespark
```
commands in parallel.

Treat scaffolded

src/__generated__/edgespark.d.ts

and

src/__generated__/server-types.d.ts

as placeholders until

edgespark pull types

populates them.

Do not edit files under
```
src/__generated__/
```
.
Use
```
@edgespark/web
```
for new browser code.
Use
```
es.api.fetch()
```
for app API calls, not bare
```
fetch()
```
to same-origin app routes.
Use
```
authUI.mount()
```
for managed auth UI unless custom forms are explicitly requested.
For custom browser auth flows, use
```
client.auth
```
from
```
@edgespark/web
```
, not manual
```
/api/_es/auth/*
```
calls.
Import
```
auth
```
from
```
edgespark/http
```
, not
```
edgespark
```
.
Auth is a managed service at
```
/api/_es/auth/
```
. OAuth callback URLs use
```
/api/_es/auth/callback/<provider>
```
, not
```
/api/auth/
```
.
Treat
```
/api/_es/auth/*
```
, storage provider details, and deployment internals as platform implementation details unless the user is explicitly debugging them.
Do not import runtime SDK values from
```
edgespark
```
inside
```
src/defs/**
```
.
Use
```
db.batch()
```
instead of
```
db.transaction()
```
.
Use migration workflow for schema changes. Do not use DDL through
```
edgespark db sql
```
.
Store S3 URIs in the database and return presigned URLs to clients.
For client-originated uploads, generate presigned PUT URLs instead of streaming files through the Worker.

Update

src/defs/runtime.ts

before using

vars.get()

secret.get()

Use
```
edgespark ... --help
```
for exact command syntax instead of duplicating help text in this skill.
If exact behavior is unclear, prefer source code, generated types, or docs MCP over guessing.

在假设命令参数或确切行为之前，先运行
```
edgespark <command> --help
```
。
代表用户运行
```
edgespark
```
命令。仅移交明确需要人工浏览器操作的步骤。
切勿并行运行多个
```
edgespark
```
命令。

在

edgespark pull types

填充内容之前，将脚手架生成的

src/__generated__/edgespark.d.ts

和

src/__generated__/server-types.d.ts

视为占位符。

不要编辑
```
src/__generated__/
```
目录下的文件。
新的浏览器代码使用
```
@edgespark/web
```
。
应用API调用使用
```
es.api.fetch()
```
，而非针对同源应用路由的原生
```
fetch()
```
。
除非明确要求自定义表单，否则使用
```
authUI.mount()
```
来托管认证UI。
对于自定义浏览器认证流程，使用
```
@edgespark/web
```
中的
```
client.auth
```
，而非手动调用
```
/api/_es/auth/*
```
。
从
```
edgespark/http
```
导入
```
auth
```
，而非从
```
edgespark
```
导入。
认证是托管在
```
/api/_es/auth/
```
的服务。OAuth回调URL使用
```
/api/_es/auth/callback/<provider>
```
，而非
```
/api/auth/
```
。
将
```
/api/_es/auth/*
```
、存储提供商细节和部署内部视为平台实现细节，除非用户明确在调试这些内容。
不要在
```
src/defs/**
```
目录下的文件中从
```
edgespark
```
导入运行时SDK值。
使用
```
db.batch()
```
而非
```
db.transaction()
```
。
模式变更使用迁移工作流。不要通过
```
edgespark db sql
```
使用DDL。
在数据库中存储S3 URI，并向客户端返回预签名URL。
对于客户端发起的上传，生成预签名PUT URL，而非通过Worker流式传输文件。

在使用

vars.get()

或

secret.get()

之前，更新

src/defs/runtime.ts

。

使用
```
edgespark ... --help
```
获取确切的命令语法，而非在本技能中重复帮助文本。
如果确切行为不明确，优先参考源代码、生成的类型文件或docs/Mintlify MCP，而非猜测。

Default Workflow

默认工作流

For the operational workflow by area, read dev-workflow.md.

各领域的操作工作流，请阅读dev-workflow.md。

Existing project

现有项目

Read generated type files first.
Read the relevant defs files before changing schema, storage, or runtime keys.
Read the web SDK types before touching auth or browser API code.

首先阅读生成的类型文件。
在修改模式、存储或运行时密钥之前，先阅读相关的defs文件。
在接触认证或浏览器API代码之前，先阅读Web SDK类型文件。

Fresh scaffold

全新脚手架项目

Inspect
```
edgespark.toml
```
to confirm server-only vs full-stack layout.
If generated files are placeholders, run
```
edgespark pull types
```
before making SDK assumptions.
Follow the scaffolded root,
```
server/
```
, and
```
web/
```
agent instruction files for package boundaries.

检查
```
edgespark.toml
```
以确认是仅服务器端还是全栈布局。
如果生成的文件是占位符，在对SDK做出假设之前先运行
```
edgespark pull types
```
。
遵循脚手架生成的根目录、
```
server/
```
和
```
web/
```
下的Agent说明文件来划分包边界。

When Stuck

遇到问题时

Read the generated type files again before assuming an API shape.
Run the relevant
```
edgespark ... --help
```
command before guessing flags.
Use docs/Mintlify MCP for product documentation details.

在假设API形状之前，重新阅读生成的类型文件。
在猜测命令参数之前，运行相关的
```
edgespark ... --help
```
命令。
使用docs/Mintlify MCP获取产品文档细节。

Quick Start

快速开始

Server:

import { db, storage, vars, secret, ctx } from "edgespark";
import { auth } from "edgespark/http";
import { posts, buckets } from "@defs";
import { Hono } from "hono";
import { eq } from "drizzle-orm";

const app = new Hono()
  .get("/api/posts", async (c) => {
    return c.json(await db.select().from(posts));
  })
  .post("/api/posts", async (c) => {
    const data = await c.req.json();
    const [post] = await db.insert(posts)
      .values({ ...data, user_id: auth.user!.id })
      .returning();
    return c.json(post, 201);
  });

export default app;

Web:

import { createEdgeSpark } from "@edgespark/web";
import "@edgespark/web/styles.css";

const es = createEdgeSpark();

es.authUI.mount(document.getElementById("auth")!, {
  redirectTo: "/dashboard",
});

const res = await es.api.fetch("/api/posts");
const posts = await res.json();

服务器端：

import { db, storage, vars, secret, ctx } from "edgespark";
import { auth } from "edgespark/http";
import { posts, buckets } from "@defs";
import { Hono } from "hono";
import { eq } from "drizzle-orm";

const app = new Hono()
  .get("/api/posts", async (c) => {
    return c.json(await db.select().from(posts));
  })
  .post("/api/posts", async (c) => {
    const data = await c.req.json();
    const [post] = await db.insert(posts)
      .values({ ...data, user_id: auth.user!.id })
      .returning();
    return c.json(post, 201);
  });

export default app;

前端：

import { createEdgeSpark } from "@edgespark/web";
import "@edgespark/web/styles.css";

const es = createEdgeSpark();

es.authUI.mount(document.getElementById("auth")!, {
  redirectTo: "/dashboard",
});

const res = await es.api.fetch("/api/posts");
const posts = await res.json();