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. リポジトリまたはプロジェクトのエージェント指示ファイル（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. ブラウザー SDK の正確な型を確認するため、インストールされている場合は node_modules/@edgespark/web/dist/index.d.ts
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() を使わないでください。
• カスタムフォームが明示的に求められていない限り、マネージド認証 UI には authUI.mount() を使用してください。
• マネージド認証のテーマ設定には、@edgespark/web の appearance.theme と appearance.variables を使用してください。通常のライト／ダークテーマやブランドのテーマ設定のために SDK の CSS を編集するよう、ユーザーに案内しないでください。
• カスタムのブラウザー認証フローには、手動で /api/_es/auth/* を呼び出さず、@edgespark/web の client.auth を使用してください。
• auth は edgespark ではなく edgespark/http からインポートしてください。
• 認証は /api/_es/auth/ で提供されるマネージドサービスです。OAuth コールバック URL は /api/auth/ ではなく /api/_es/auth/callback/<provider> を使用します。
• ユーザーが明示的にデバッグしている場合を除き、/api/_es/auth/*、ストレージプロバイダーの詳細、デプロイの内部仕様はプラットフォームの実装詳細として扱ってください。
• src/defs/** 内で edgespark からランタイム SDK の値をインポートしないでください。
• db.transaction() ではなく db.batch() を使用してください。
• スキーマの変更にはマイグレーションのワークフローを使用してください。edgespark db sql を通じて DDL を実行しないでください。
• S3 URI をデータベースに保存し、署名付き URL をクライアントに返してください。
• クライアントからのアップロードには、Worker 経由でファイルをストリーミングするのではなく、署名付き PUT URL を生成してください。
• vars.get() または secret.get() を使用する前に、src/defs/runtime.ts を更新してください。
• このスキル内でヘルプの内容を重複して記載せず、正確なコマンド構文は edgespark ... --help で確認してください。
• 正確な動作が不明な場合は、推測せず、ソースコード、生成された型、または docs MCP を参照してください。

デフォルトのワークフロー

領域別の運用ワークフローについては、dev-workflow.md を読んでください。

既存のプロジェクト

1. まず生成された型ファイルを読みます。
2. スキーマ、ストレージ、またはランタイムキーを変更する前に、関連する defs ファイルを読みます。
3. 認証やブラウザー API のコードを変更する前に、Web SDK の型を読みます。

新規のスキャフォールド

1. edgespark.toml を確認し、サーバーのみの構成かフルスタック構成かを把握します。
2. 生成されたファイルがプレースホルダーの場合は、SDK について判断する前に edgespark pull types を実行します。
3. パッケージの境界については、スキャフォールドによって作成されたルート、server/、web/ のエージェント指示ファイルに従います。

困ったとき

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