sailfork / t3code-github / .repos/ alchemy-effect/ website/ src/ content/ docs/ cloudflare/ local-development.mdx

import Terminal from "../../../components/Terminal.astro";

alchemy dev runs your Cloudflare stack on your machine. Workers execute in workerd — the same runtime used in production — with local simulators behind their bindings, websites run their frameworks' own dev servers with native HMR, containers run in Docker, and code changes hot reload in milliseconds.

alchemy dev

<Terminal content={`[g]✓[/g] [b]Bucket[/b] d[/d] [g]created[/g] d[/d] [g]✓[/g] [b]DB[/b] d[/d] [g]created[/g] d[/d] [g]✓[/g] [b]Worker[/b] d[/d] [g]created[/g] [d](local → workerd)[/d] [s2][d]• http://localhost:1337[/d]

[d]Watching for changes ...[/d]`} />

Workers run in workerd

Your Worker code executes in workerd with bindings wired to the local simulators, so binding behavior matches what you deploy:

export const Cache = Cloudflare.KV.Namespace("Cache");

export default class Api extends Cloudflare.Worker<Api>()(
  "Api",
  { main: import.meta.url },
  Effect.gen(function* () {
    const kv = yield* Cloudflare.KV.ReadWriteNamespace(Cache);
    return {
      fetch: Effect.gen(function* () {
        yield* kv.put("greeting", "hello");
        const value = yield* kv.get("greeting");
        return yield* HttpServerResponse.text(value ?? "");
      }).pipe(Effect.orDie),
    };
  }).pipe(Effect.provide(Cloudflare.KV.ReadWriteNamespaceBinding)),
) {}

In dev, kv.put lands in a local KV simulator and the Worker serves at http://localhost:<port>. Durable Objects run inside the same workerd instance, cron triggers fire on their real schedule (and the miniflare-compatible /cdn-cgi/handler/scheduled route triggers them manually), and because everything is a local process you can attach a debugger, set breakpoints, and profile.

A local resource's id is dev:-prefixed, which doubles as proof that no cloud call ran.

Websites run their own dev servers

Every Cloudflare.Website.* resource — Vite, Next.js, Astro, Nuxt, SvelteKit, Waku, Octane, Foldkit, StaticSite — runs its framework's own dev server under alchemy dev: native HMR, no cloud resources. The site's url is the local dev server's address:

const site = yield* Cloudflare.Website.Vite("Web");
// dev:    site.url = http://localhost:5173 — Vite's own dev server, HMR included
// deploy: site.url = the deployed site

See Frontend frameworks.

Containers run in Docker

A Cloudflare.Container runs as a real Docker container on your machine, driven by its Durable Object in the local workerd:

export class Sandbox extends Cloudflare.Container<
  Sandbox,
  { ping: () => Effect.Effect<string> }
>()("Sandbox") {}

export default Sandbox.make(
  { main: import.meta.url },
  Effect.gen(function* () {
    return Sandbox.of({
      ping: () => Effect.succeed("pong"),
      fetch: Effect.succeed(HttpServerResponse.text("hello")),
    });
  }),
);

All three image sources work locally: main (a bundled Effect program), context (your own Dockerfile), and image (a pre-built remote image).

FUSE mounts

A container can mount a FUSE filesystem locally, such as an R2 bucket through s3fs or tigrisfs, just as it can once deployed. Every local container gets the Docker privileges FUSE needs: CAP_SYS_ADMIN, the /dev/fuse device, and an unconfined AppArmor profile.

What's emulated

These resources ship a local provider and run as simulators in dev:

ResourceLocal behavior
Workersworkerd, with hot reload and a http://localhost:<port> URL
Durable Objectsrun inside the local workerd, including SQLite storage
KV Namespaceslocal simulator; Node-side capability clients hit the same store
R2 Bucketslocal simulator; an S3-compatible endpoint serves presigned URLs
D1 Databaseslocal simulator; migrations and importFiles apply on every reconcile
Queues + consumerslocal broker with batching, retry, and dead-letter semantics
Hyperdriveconnects directly to your database
Workflowsrun locally with real step semantics
Containersrun as Docker containers on your machine
Secrets Storelocal store seeded with the real (Redacted-sourced) values
Websitesthe framework's own dev server (Vite, Astro, Next.js, Nuxt, SvelteKit, Waku, Octane, Foldkit, StaticSite) with native HMR

Worker-only bindings are simulated too:

  • Email, both directions — a send_email binding persists messages as .eml files under .alchemy/local/email, and a POST to /cdn-cgi/handler/email drives your email() handler with accept, reject, and reply semantics.
  • Browser Rendering — env.BROWSER drives a locally-launched headless Chrome over CDP; @cloudflare/puppeteer works unchanged.
  • Images — env.IMAGES transforms run through sharp.
  • Stream — uploads land in a local video store.
  • Tail consumers — a local producer's trace events reach a local tail Worker.
  • Secret keys — secret_key CryptoKey bindings boot locally.
  • Access — dev: { access: { identity } } stubs the authenticated identity behind ctx.access, so gated paths are testable without a login wall. See Protect a Worker with Access.

Resources whose provider has no local implementation (a Vectorize index, DNS records) deploy to the real cloud, into your personal stage, so a stack that mixes emulated and live-only resources just works.

Mix in the real cloud

Alchemy.remote() opts any resource (or a whole scope) out of local emulation:

// Effect-native Worker
const browser = yield* Cloudflare.Browser("BROWSER").pipe(Alchemy.remote());

// async Worker env
env: { IMAGES: Cloudflare.Images.Images("IMAGES").pipe(Alchemy.remote()) }

Local and live compose into hybrid topologies. Pin a queue live and everything around it stays local — the local Worker produces real messages into the real queue, and its local consumer drains the same queue through a pull loop:

// the queue is real, even in dev
const Jobs = Cloudflare.Queues.Queue("Jobs").pipe(Alchemy.remote());

Your dev session sees the same traffic as staging — messages produced by deployed services or a teammate's session land in your local handler.

Switching a resource between local and live (or dev → deploy) plans a replacement — dev state never silently becomes cloud state. See Local development for the shared semantics.

Custom port

export default Cloudflare.Worker("Worker", {
  main: import.meta.url,
  dev: {
    port: 3000,
  },
  // ...
});

Test against the local stack

The test harness has the same dev mode — Test.make({ dev: true }) (available on both the Bun and Vitest adapters, off by default) runs the suite's deploy(Stack) against the local simulators instead of the cloud, no separate alchemy dev terminal needed:

const { test, beforeAll, afterAll, deploy, destroy } = Test.make({
  providers: Cloudflare.providers(),
  dev: true,
});

Workers, Durable Objects, Workflows, and the simulated bindings all run in workerd exactly as described above, and the stack's url points at http://localhost:<port>. See Test harness → dev and Tutorial Part 4.

Where next

  • Local development — the shared alchemy dev concepts: hot reload, Alchemy.remote(), and dev vs deploy semantics.
  • Frontend frameworks — framework dev servers under alchemy dev.
  • Stages — how live-in-dev resources stay isolated per developer.
  • Testing — run the same test suite against the local simulators with Test.make({ dev: true }).
  • Local Providers — build the local implementation of a resource.