Alchemy

Alchemy is a TypeScript-native Infrastructure-as-Code framework. This skill provides comprehensive knowledge of Alchemy’s APIs, patterns, and conventions.

Load references/alchemy-concepts.md for full details on any topic below.

Quick Start

New Project

alchemy create my-app --template vite

Add to Existing Project

alchemy init

Core File: 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();

Commands

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

Task Routing

Based on what the user asks, determine which knowledge to load:

Key Concepts

Resources

Resources are memoized async functions with create/update/delete lifecycle. Every resource takes an ID and props:

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

Bindings

Connect resources to Workers with type-safe bindings:

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

Access in worker code with type inference:

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

Secrets

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

Stages

Isolated copies of your infrastructure. Default is $USER locally:

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

Dev Mode

Local emulation with Miniflare, hot reload, framework integration:

alchemy dev

Framework Adapters

Each framework has a resource and a Vite plugin/adapter:

Providers

Alchemy has 20+ providers. The main ones:

Conventions

• Default import: import alchemy from "alchemy"
• Named imports from subpaths: import { Worker } from "alchemy/cloudflare"
• await app.finalize() is always the last line of alchemy.run.ts
• Physical names include app name + stage for uniqueness
• Stage defaults to $USER locally; use --stage prod for production
• Sensitive values always wrapped with alchemy.secret()
• State stored in .alchemy/ directory (add to .gitignore or commit for shared state)

Reference Files

Load these on demand for detailed information:

• references/alchemy-concepts.md — Comprehensive reference covering all Alchemy concepts: apps, stages, scopes, phases, resources, secrets, state, bindings, CLI, dev mode, profiles, framework adapters, serialization, and all 20+ providers with their resources.
• references/resource-patterns.md — Implementation patterns for building custom resources (17 sections). Load when the user wants to create custom resources or contribute to Alchemy.
• references/test-patterns.md — Test conventions and patterns (15 sections). Load when writing tests for custom resources.
• references/doc-patterns.md — Documentation templates (10 sections). Load when writing docs for Alchemy providers.
• references/checklist.md — Completeness verification checklist. Load when verifying a provider implementation.

Provider Development Workflow

Use this workflow when the user is building a new provider or custom resource for the Alchemy framework itself (not just using Alchemy in their app).

Phase 1: Research

Study the provider’s API, identify CRUD-capable entities, authentication method, rate limits.

Phase 2: Design

Define resource list, Props/Output interfaces, API client approach, dependency order.

Phase 3: API Client

Create alchemy/src/{provider}/api.ts — minimal fetch wrapper, env var auth with Secret.unwrap() fallback.

Phase 4: Resources

Implement each resource. Load references/resource-patterns.md.

• Resource("{provider}::{Resource}", ...) with create/update/delete lifecycle
• Physical name: props.name ?? this.output?.name ?? this.scope.createPhysicalName(id)
• Must use function declaration (not arrow), context via this
• Export type guard (is{Resource}) for binding support

Phase 5: Tests

Write tests. Load references/test-patterns.md.

• alchemy.test(import.meta, { prefix: BRANCH_PREFIX })
• try/finally with destroy(scope) and API verification

Phase 6: Documentation

Write docs, guide, examples. Load references/doc-patterns.md.

• Resource docs: alchemy-web/src/content/docs/providers/{provider}/{resource}.md
• Guide: alchemy-web/src/content/docs/guides/{provider}.mdx
• Example: examples/{provider}/alchemy.run.ts

Phase 7: Verify

Run checklist. Load references/checklist.md.

• bun format, bun vitest alchemy/test/{provider}/, bun tsc -b