building-edgespark-apps

EdgeSpark 应用开发

将此技能用于 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/web 和 authUI.mount() 作为此仓库默认的浏览器身份验证方案。

阅读顺序

仅阅读任务所需的内容：

1. edgespark.toml
2. 仓库或项目 Agent 指令文件（AGENTS.md、CLAUDE.md 或 GEMINI.md）
3. src/__generated__/edgespark.d.ts
4. src/__generated__/server-types.d.ts
5. src/defs/index.ts、src/defs/db_schema.ts、src/defs/db_relations.ts、src/defs/runtime.ts、src/defs/storage_schema.ts
6. 若已安装，则查阅 node_modules/@edgespark/web/dist/index.d.ts，了解浏览器 SDK 的准确类型
7. 若已安装，则查阅 node_modules/@edgespark/web/README.md，了解托管身份验证外观变量的含义和默认值

然后加载所需的具体参考资料：

• 按界面划分的日常开发工作流：dev-workflow.md
• 脚手架布局和生成文件规则：project-structure.md
• 容易出错的服务端用法模式：server-patterns.md
• @edgespark/web 的简明 Web 用法模式：web-patterns.md
• 身份验证配置、OAuth 提供商、回调 URL、托管身份验证主题设置和 Google One Tap：auth-patterns.md

硬性规则

• 在假设标志或具体行为之前，先运行 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() 显示托管身份验证界面。
• 对托管身份验证进行主题设置时，请使用 @edgespark/web 中的 appearance.theme 和 appearance.variables；不要建议用户为了常规的明暗主题或品牌主题设置而编辑 SDK CSS。
• 对于自定义浏览器身份验证流程，请使用 @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 MCP，不要猜测。

默认工作流

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

现有项目

1. 先阅读生成的类型文件。
2. 更改 schema、存储或运行时键之前，先阅读相关的 defs 文件。
3. 修改身份验证或浏览器 API 代码之前，先阅读 Web SDK 类型。

全新脚手架

1. 检查 edgespark.toml，确认是仅服务端还是全栈布局。
2. 如果生成的文件只是占位内容，请先运行 edgespark pull types，再对 SDK 作出假设。
3. 遵循脚手架生成的根目录、server/ 和 web/ Agent 指令文件中有关包边界的说明。

遇到问题时

1. 再次阅读生成的类型文件，然后再判断 API 的形态。
2. 先运行相关的 edgespark ... --help 命令，再猜测标志参数。
3. 使用 docs/Mintlify MCP 查询产品文档详情。

快速开始

服务端：

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();