Alchemy

references/alchemy-concepts.md

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

alchemy create

alchemy init

alchemy.run.ts

import { Worker } from "alchemy/cloudflare"

alchemy/cloudflare

alchemy.secret(process.env.X)

Secret.unwrap()

alchemy dev

references/alchemy-concepts.md

alchemy deploy --stage prod

references/alchemy-concepts.md

references/resource-patterns.md

Key Concepts

Resources

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

Bindings

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

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

$USER

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

Dev Mode

alchemy dev

Framework Adapters

Vite

alchemy/cloudflare/vite

Astro

alchemy/cloudflare/astro

ReactRouter

alchemy/cloudflare/react-router

SvelteKit

alchemy/cloudflare/sveltekit

Nuxt

alchemy/cloudflare/nuxt

TanStackStart

alchemy/cloudflare/tanstack-start

BunSPA

Nextjs

alchemy/cloudflare/nextjs

Redwood

alchemy/cloudflare/rwsdk

Providers

alchemy/cloudflare

alchemy/neon

alchemy/stripe

alchemy/aws

alchemy/aws/control

AWS.{Service}.{Resource}

alchemy/github

alchemy/vercel

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

• 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

Phase 1: Research

Phase 2: Design

Phase 3: API Client

alchemy/src/{provider}/api.ts

Phase 4: Resources

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

references/test-patterns.md

• alchemy.test(import.meta, { prefix: BRANCH_PREFIX })

• try/finally with

  destroy(scope)

  and API verification

Phase 6: Documentation

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

references/checklist.md

• bun format

  ,

  bun vitest alchemy/test/{provider}/

  ,

  bun tsc -b