alchemy

Alchemy

Alchemy 是一个原生支持 TypeScript 的基础设施即代码框架。本技能提供 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 和属性：

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