Local Development

Learn how to use Alchemy's development mode to run your application locally.

Alchemy’s development mode provides a local development experience for Cloudflare Workers, featuring hot reloading, local resource emulation, and seamless integration with remote Cloudflare services.

Get Started

To run Alchemy in development mode, use the alchemy dev command to:

Emulate Cloudflare Workers and associated resources locally
Watch for and auto-apply changes to your infrastructure
Hot reload Workers when you make changes to your runtime code

bun alchemy dev

You can also specify additional options:

# run dev mode with default settings
bun alchemy dev

# specify a stage
bun alchemy dev --stage dev

# use a custom script
bun alchemy dev ./my-infra.ts

# use an environment file
bun alchemy dev --env-file .env.dev

npx alchemy dev

You can also specify additional options:

# run dev mode with default settings
npx alchemy dev

# specify a stage
npx alchemy dev --stage dev

# use a custom script
npx alchemy dev ./my-infra.ts

# use an environment file
npx alchemy dev --env-file .env.dev

pnpm alchemy dev

You can also specify additional options:

# run dev mode with default settings
pnpm alchemy dev

# specify a stage
pnpm alchemy dev --stage dev

# use a custom script
pnpm alchemy dev ./my-infra.ts

# use an environment file
pnpm alchemy dev --env-file .env.dev

yarn alchemy dev

You can also specify additional options:

# run dev mode with default settings
yarn alchemy dev

# specify a stage
yarn alchemy dev --stage dev

# use a custom script
yarn alchemy dev ./my-infra.ts

# use an environment file
yarn alchemy dev --env-file .env.dev

Workers

In development mode, the Cloudflare Worker resource runs in Miniflare, a local environment that emulates the Cloudflare Workers runtime. By default, Workers run on the first available port beginning at 1337:

const worker = await Worker("my-worker", {
  entrypoint: "worker.ts",
});
console.log(worker.url); // http://localhost:1337

You can also set a custom port for the Worker:

const worker = await Worker("my-worker", {
  entrypoint: "worker.ts",
  dev: {
    port: 3000,
  },
});
console.log(worker.url); // http://localhost:3000

Tunnel

Route requests from the public internet to your locally running Worker via a Cloudflare Tunnel.

const worker = await Worker("my-worker", {
  entrypoint: "worker.ts",
  dev: {
    tunnel: true,
  },
});

Bindings

Most Cloudflare bindings are automatically emulated in development mode, such as D1Database, KVNamespace, and R2Bucket:

const d1 = await D1Database("my-d1");
const kv = await KVNamespace("my-kv");
const r2 = await R2Bucket("my-r2");
const queue = await Queue("my-queue");
const worker = await Worker("my-worker", {
  entrypoint: "worker.ts",
  bindings: {
    D1: d1,
    KV: kv,
    R2: r2,
    QUEUE: queue,
  },
});

Secrets and plain-text bindings are also supported with no additional configuration:

const worker = await Worker("my-worker", {
  entrypoint: "worker.ts",
  bindings: {
    PLAIN_TEXT: "Hello, world!",
    API_KEY: alchemy.secret("pk_dev_1234567890"),
  },
});

Remote Bindings

Some Cloudflare resources can be used as bindings in development mode. By default, resources that support local emulation run locally, but you can optionally set dev.remote: true to use the real deployed resource from Cloudflare instead.

const api = await Worker("my-api", {
  entrypoint: "api.ts",
  dev: {
    remote: true,  // Use deployed worker instead of local emulation
  },
});
const kv = await KVNamespace("my-kv", {
  dev: {
    remote: true,  // Use deployed KV instead of local emulation
  },
});
const worker = await Worker("my-worker", {
  entrypoint: "worker.ts",
  bindings: {
    KV: kv,
    API: api
  },
});

Binding Support

Resource	Local Emulation	Remote Binding	Documentation
`Ai`	❌	✅	Ai
`AnalyticsEngine`	✅	❌	AnalyticsEngine
`Assets`	✅	❌	Assets
`BrowserRendering`	❌	✅	BrowserRendering
`Container`	✅	✅	Container
`DispatchNamespace`	❌	✅	DispatchNamespace
`D1Database`	✅	✅	D1Database
`DurableObjectNamespace`	❌	✅	DurableObjectNamespace
`Hyperdrive`	✅	❌	Hyperdrive
`Images`	✅	✅	Images
`KVNamespace`	✅	✅	KVNamespace
`Queue`	✅	✅	Queue
`Pipeline`	✅	❌	Pipeline
`RateLimit`	✅	❌	RateLimit
`R2Bucket`	✅	✅	R2Bucket
`VectorizeIndex`	❌	✅	VectorizeIndex
`VersionMetadata`	✅	❌	VersionMetadata
`Worker`	✅	✅	Worker
`Workflow`	✅	❌	Workflow

Web Frameworks

Alchemy integrates with popular web frameworks, so you can use them with Alchemy’s development mode and access local resources. Typically, you’ll need to update your framework’s configuration with the relevant Alchemy adapter or plugin. For example:

First, use the Astro resource in your alchemy.run.ts script:

import { Astro } from "alchemy/cloudflare";

const astro = await Astro("my-astro-app");

Then, update your astro.config.mjs file:

import alchemy from "alchemy/cloudflare/astro";

export default defineConfig({
  integrations: [alchemy()],
});

First, use the ReactRouter resource in your alchemy.run.ts script:

import { ReactRouter } from "alchemy/cloudflare";

const reactRouter = await ReactRouter("my-react-router-app");

Then, enable the unstable_viteEnvironmentApi flag in your react-router.config.ts file:

import type { Config } from "@react-router/dev/config";

export default {
  ssr: true,
  future: {
    unstable_viteEnvironmentApi: true, // IMPORTANT: This allows Cloudflare to be used in the Vite environment.
  },
} satisfies Config;

And add the alchemy/cloudflare/react-router plugin to your vite.config.ts:

import alchemy from "alchemy/cloudflare/react-router";
import { reactRouter } from "@react-router/dev/vite";

export default defineConfig({
  plugins: [alchemy(), reactRouter()],
});

First, use the TanStackStart resource in your alchemy.run.ts script:

import { TanStackStart } from "alchemy/cloudflare";

const tanstackStart = await TanStackStart("my-tanstack-start-app");

Then, add the alchemy/cloudflare/tanstack-start plugin to your vite.config.ts:

import alchemy from "alchemy/cloudflare/tanstack-start";
import { tanstackStart } from "@tanstack/react-start/plugin/vite";
import viteReact from "@vitejs/plugin-react";

export default defineConfig({
  plugins: [
    alchemy(),
    tanstackStart({
      target: "cloudflare-module",
      customViteReactPlugin: true,
    }),
    viteReact(),
  ],
});

First, use the Vite resource in your alchemy.run.ts script:

import { Vite } from "alchemy/cloudflare";

const vite = await Vite("my-vite-app");

Then, add the alchemy/cloudflare/vite plugin to your vite.config.ts:

import alchemy from "alchemy/cloudflare/vite";

export default defineConfig({
  plugins: [alchemy()],
});

First, use the BunSPA resource in your alchemy.run.ts script:

import { BunSPA } from "alchemy/cloudflare";

const bunsite = await BunSPA("my-bun-app", {
  frontend: "src/index.html",
  entrypoint: "src/worker.ts",
});

Create a bunfig.toml file:

[serve.static]
env='BUN_PUBLIC_*'

BunSPA provides automatic integration:

Frontend: Bun’s native dev server with hot module reloading
Backend: alchemy dev runs your Worker locally with full binding support
No additional configuration needed - just run alchemy dev

First, use the SvelteKit resource in your alchemy.run.ts script:

import { SvelteKit } from "alchemy/cloudflare";

const svelteKit = await SvelteKit("my-sveltekit-app");

Then, add the alchemy/cloudflare/sveltekit adapter to your svelte.config.js file:

import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';
import alchemy from 'alchemy/cloudflare/sveltekit';

/** @type {import('@sveltejs/kit').Config} */
const config = {
  preprocess: vitePreprocess(),
  kit: {
    adapter: alchemy()
  }
};

export default config;

You should not need to update your vite.config.ts file.

First, use the Nuxt resource in your alchemy.run.ts script:

import { Nuxt } from "alchemy/cloudflare";

const nuxt = await Nuxt("my-nuxt-app");

Then, add the alchemy/cloudflare/nuxt preset to your nuxt.config.ts file:

import alchemy from "alchemy/cloudflare/nuxt";
import { defineNuxtConfig } from "nuxt/config";

export default defineNuxtConfig({
  nitro: {
    preset: "cloudflare_module",
    cloudflare: alchemy(),
  },
  modules: ["nitro-cloudflare-dev"],
});

Get Started

Workers

Tunnel

Bindings

Remote Bindings

Binding Support

Web Frameworks

Limitations