Alchemy Cloudflare

Alchemy Cloudflare IaC

TypeScript-first Infrastructure as Code for deploying TanStack Start applications to Cloudflare Workers.

Core Concepts

• alchemy.run.ts: Infrastructure definition file (TypeScript, not YAML)
• TanStackStart resource: Wraps Worker config specifically for TanStack builds
• Hyperdrive resource: Provides pooled PlanetScale connections
• Type inference: typeof worker.Env provides types without codegen
• Secrets: alchemy.secret() encrypts values with ALCHEMY_PASSWORD

Quick Start

1. Install Dependencies

pnpm add alchemy @cloudflare/workers-types

2. Create alchemy.run.ts

import alchemy from "alchemy"
import { Hyperdrive, TanStackStart } from "alchemy/cloudflare"
import { Branch as PlanetScaleBranch, Password as PlanetScalePassword } from "alchemy/planetscale"

const app = await alchemy("my-app", {
  stage: process.env.STAGE ?? "dev",
  phase: process.argv.includes("--destroy") ? "destroy" : "up",
})

// PlanetScale branch + password + Hyperdrive connection pooling
const psBranch = await PlanetScaleBranch("ps-branch", {
  organization: "my-org",
  database: "my-db",
  name: "dev",
  parentBranch: "main",
})

const psPassword = await PlanetScalePassword("ps-password", {
  organization: "my-org",
  database: "my-db",
  branch: psBranch,
  role: "admin",
})

const hyperdrive = await Hyperdrive("hyperdrive", {
  origin: {
    host: psPassword.host,
    database: "my-db",
    user: psPassword.username,
    password: psPassword.password.unencrypted,
    port: 3306,
    scheme: "mysql",
  },
})

const worker = await TanStackStart("my-worker", {
  bindings: { HYPERDRIVE: hyperdrive },
  domains: ["my-app.com"],  // Custom domain
})

export type Env = typeof worker.Env

await app.finalize()

3. Configure Vite

CRITICAL: Alchemy plugin must be FIRST in plugins array.

// app.config.ts
import { defineConfig } from "@tanstack/react-start/config"
import viteTsConfigPaths from "vite-tsconfig-paths"
import { alchemy } from "alchemy/cloudflare/tanstack-start"

export default defineConfig({
  vite: {
    plugins: [
      alchemy(),  // MUST be first
      viteTsConfigPaths({ root: "./" }),
    ],
    build: {
      target: "esnext",
      rollupOptions: {
        external: ["node:async_hooks", "cloudflare:workers"],
      },
    },
  },
})

4. Deploy

# Set encryption password (once)
export ALCHEMY_PASSWORD="your-secure-password"

# Deploy
bun alchemy.run.ts

# Deploy to specific stage
STAGE=prod bun alchemy.run.ts

# Destroy resources
bun alchemy.run.ts --destroy

Local Development

# Run dev server with Cloudflare emulation
pnpm alchemy dev

What this provides:

• Direct PlanetScale connections via Hyperdrive dev mode
• KV, R2, Durable Objects bindings
• Same Env types as production

Only required env var:

ALCHEMY_PASSWORD=your-password

PlanetScale + Drizzle Integration

Migration Workflow

1. Modify schema in src/db/schema.ts
2. During development: pnpm db:push (pushes to PlanetScale dev branch)
3. Before merging: pnpm db:generate --name=feature-name
4. Deploy: Migrations are applied via drizzle-kit push in CI

Accessing PlanetScale via Hyperdrive

// In server functions or loaders
import { env } from 'cloudflare:workers'

const db = drizzle(env.HYPERDRIVE)
// Use db...

Common Patterns

Multiple Environments

const stage = process.env.STAGE ?? "dev"

const app = await alchemy("my-app", { stage })

// Conditional resources
const domains = stage === "prod" 
  ? ["app.com", "www.app.com"]
  : [`${stage}.app.com`]

await TanStackStart("worker", { domains })

Secrets Management

// In alchemy.run.ts
const worker = await TanStackStart("worker", {
  vars: {
    PUBLIC_API_URL: "https://api.example.com",
  },
  secretTextBindings: {
    AUTH_SECRET: alchemy.secret(process.env.AUTH_SECRET!),
    STRIPE_KEY: alchemy.secret(process.env.STRIPE_KEY!),
  },
})

KV Namespace

import { KVNamespace, TanStackStart } from "alchemy/cloudflare"

const sessions = await KVNamespace("sessions")

await TanStackStart("worker", {
  kvNamespaces: { SESSIONS: sessions },
})

Troubleshooting

"cloudflare:workers" resolve error

Add to vite config:

rollupOptions: {
  external: ["node:async_hooks", "cloudflare:workers"],
}

"Route files should not import @/db"

Server functions must be in src/server-fns/ files, not inline in route files. Routes can only import and call server functions.

PlanetScale connection issues

Check that PLANETSCALE_SERVICE_TOKEN_ID and PLANETSCALE_SERVICE_TOKEN are set. Verify the branch exists in PlanetScale dashboard.

Migration not applying

Use pnpm db:push for dev. For production, migrations are applied via drizzle-kit push in CI.

References

• references/vite-config.md - Complete Vite configuration example
• references/alchemy-run.md - Full alchemy.run.ts example with all resources