alchemy

Alchemy

Alchemy は、TypeScript ネイティブの Infrastructure-as-Code フレームワークです。このスキルでは、Alchemy の API、パターン、規約について包括的な知識を提供します。

以下のトピックの詳細については、references/alchemy-concepts.md を読み込んでください。

クイックスタート

新しいプロジェクト

alchemy create my-app --template vite

既存のプロジェクトに追加

alchemy init

コアファイル：alchemy.run.ts

import alchemy from "alchemy";
import { Worker, KVNamespace } from "alchemy/cloudflare";

const app = await alchemy("my-app");

const kv = await KVNamespace("cache", { title: "my-cache" });

const worker = await Worker("api", {
  entrypoint: "./src/worker.ts",
  bindings: {
    CACHE: kv,
    API_KEY: alchemy.secret(process.env.API_KEY),
    STAGE: app.stage,
  },
});

await app.finalize();

コマンド

alchemy deploy              # deploy (default stage = $USER)
alchemy deploy --stage prod # deploy to prod
alchemy dev                 # local dev with hot reload
alchemy destroy             # tear down all resources

タスクの振り分け

ユーザーのリクエストに基づいて、読み込む知識を判断してください。

ユーザーのリクエスト	対応方法
プロジェクトに Alchemy をセットアップする	alchemy create または alchemy init を使用して、alchemy.run.ts を作成します
Worker を追加する	import { Worker } from "alchemy/cloudflare" を使用し、エントリーポイントとバインディングを設定します
データベース／KV／R2／キューを追加する	alchemy/cloudflare からインポートし、リソースを作成して Worker にバインドします
シークレットを使用する	入力には alchemy.secret(process.env.X) を使用し、カスタムリソースでは Secret.unwrap() を使用します
開発モードをセットアップする	alchemy dev を実行し、フレームワークアダプター／プラグインを設定します
フレームワーク（Vite／Astro など）を使用する	フレームワークアダプターについては、references/alchemy-concepts.md §11 を読み込みます
本番環境にデプロイする	alchemy deploy --stage prod を実行し、CI ガイドのパターンを参照します
Neon／Stripe／AWS／その他のプロバイダーを使用する	プロバイダー一覧については、references/alchemy-concepts.md §13 を読み込みます
カスタムリソースを構築する	実装パターンについては、references/resource-patterns.md を読み込みます
Alchemy の新しいプロバイダーを構築する	以下のプロバイダー開発ワークフローをすべて実行します

主な概念

リソース

リソースは、作成／更新／削除のライフサイクルを持つメモ化された非同期関数です。各リソースは ID と props を受け取ります。

const db = await D1Database("my-db", { name: "my-db" });

バインディング

型安全なバインディングを使用して、リソースを Worker に接続します。

const worker = await Worker("api", {
  entrypoint: "./src/worker.ts",
  bindings: { DB: db, KV: kv, SECRET: alchemy.secret("value") },
});

型推論を使って Worker コードからアクセスします。

import type { worker } from "../alchemy.run";
export default {
  async fetch(req: Request, env: typeof worker.Env) {
    await env.DB.prepare("SELECT 1").run();
  },
};

シークレット

alchemy.secret(process.env.API_KEY)  // wrap a value
alchemy.secret.env.API_KEY           // shorthand

ステージ

インフラストラクチャの分離されたコピーです。ローカル環境ではデフォルトで $USER が使用されます。

alchemy deploy              # deploys to $USER stage
alchemy deploy --stage prod # deploys to prod stage

開発モード

Miniflare によるローカルエミュレーション、ホットリロード、フレームワーク連携を利用できます。

alchemy dev

フレームワークアダプター

各フレームワークには、リソースと Vite プラグイン／アダプターがあります。

フレームワーク	リソース	プラグイン／アダプター
Vite	Vite	alchemy/cloudflare/vite
Astro	Astro	alchemy/cloudflare/astro
React Router	ReactRouter	alchemy/cloudflare/react-router
SvelteKit	SvelteKit	alchemy/cloudflare/sveltekit
Nuxt	Nuxt	alchemy/cloudflare/nuxt
TanStack Start	TanStackStart	alchemy/cloudflare/tanstack-start
BunSPA	BunSPA	（プラグインは不要）
Next.js	Nextjs	alchemy/cloudflare/nextjs
Redwood (RWSDK)	Redwood	alchemy/cloudflare/rwsdk

プロバイダー

Alchemy には 20 以上のプロバイダーがあります。主なものは次のとおりです。

プロバイダー	インポート	主なリソース
Cloudflare	alchemy/cloudflare	Worker、D1Database、KVNamespace、R2Bucket、Queue、DurableObjectNamespace、Hyperdrive、Zone、DnsRecords
Neon	alchemy/neon	NeonProject、NeonBranch、NeonDatabase、NeonRole
Stripe	alchemy/stripe	WebhookEndpoint、Price、Product、Coupon など 10 種類以上
AWS	alchemy/aws	Function、Table、Vpc、Subnet、SecurityGroup、Bucket、Role
AWS Control	alchemy/aws/control	AWS.{Service}.{Resource} — AWS CloudFormation 全体をカバーします
GitHub	alchemy/github	GitHubSecret
Vercel	alchemy/vercel	VercelProject、VercelDnsRecord、VercelDeployment

規約

• デフォルトのインポート：import alchemy from "alchemy"
• サブパスからの名前付きインポート：import { Worker } from "alchemy/cloudflare"
• await app.finalize() は常に alchemy.run.ts の最終行に置きます
• リソースの物理名には、一意性を保つためにアプリ名とステージ名を含めます
• ローカル環境ではステージはデフォルトで $USER です。本番環境では --stage prod を使用します
• 機密値は必ず alchemy.secret() でラップします
• 状態は .alchemy/ ディレクトリに保存されます（共有状態にする場合は .gitignore に追加するか、コミットしてください）

参考ファイル

詳細については、必要に応じて以下を読み込んでください。

• references/alchemy-concepts.md — Alchemy のすべての概念を網羅した包括的なリファレンスです。アプリ、ステージ、スコープ、フェーズ、リソース、シークレット、状態、バインディング、CLI、開発モード、プロファイル、フレームワークアダプター、シリアライズ、およびリソースを含む 20 以上のプロバイダーを扱います。
• references/resource-patterns.md — カスタムリソースを構築するための実装パターン（17 セクション）です。ユーザーがカスタムリソースを作成する場合、または Alchemy に貢献する場合に読み込んでください。
• references/test-patterns.md — テスト規約とパターン（15 セクション）です。カスタムリソースのテストを記述する場合に読み込んでください。
• references/doc-patterns.md — ドキュメントテンプレート（10 セクション）です。Alchemy プロバイダーのドキュメントを記述する場合に読み込んでください。
• references/checklist.md — 完全性を検証するためのチェックリストです。プロバイダーの実装を検証する場合に読み込んでください。

---

プロバイダー開発ワークフロー

ユーザーが Alchemy フレームワーク自体の新しいプロバイダーまたはカスタムリソースを開発している場合（アプリで Alchemy を使用するだけの場合ではありません）、このワークフローを使用してください。

フェーズ 1：調査

プロバイダーの API を調査し、CRUD に対応するエンティティ、認証方式、レート制限を特定します。

フェーズ 2：設計

リソース一覧、Props／Output インターフェース、API クライアントの方式、依存関係の順序を定義します。

フェーズ 3：API クライアント

alchemy/src/{provider}/api.ts を作成します。最小限の fetch ラッパーを用意し、Secret.unwrap() へのフォールバックを使って環境変数で認証します。

フェーズ 4：リソース

各リソースを実装します。references/resource-patterns.md を読み込んでください。

• Resource("{provider}::{Resource}", ...) を使い、作成／更新／削除のライフサイクルを実装します。
• 物理名：props.name ?? this.output?.name ?? this.scope.createPhysicalName(id)
• アロー関数ではなく、function 宣言を使用し、this 経由でコンテキストを参照します。
• バインディングに対応する型ガード（is{Resource}）をエクスポートします。

フェーズ 5：テスト

テストを記述します。references/test-patterns.md を読み込んでください。

• alchemy.test(import.meta, { prefix: BRANCH_PREFIX })
• try/finally を使用し、destroy(scope) と API の検証を行います。

フェーズ 6：ドキュメント

ドキュメント、ガイド、サンプルを作成します。references/doc-patterns.md を読み込んでください。

• リソースのドキュメント：alchemy-web/src/content/docs/providers/{provider}/{resource}.md
• ガイド：alchemy-web/src/content/docs/guides/{provider}.mdx
• サンプル：examples/{provider}/alchemy.run.ts

フェーズ 7：検証

チェックリストを実行します。references/checklist.md を読み込んでください。

• bun format、bun vitest alchemy/test/{provider}/、bun tsc -b を実行します。