Local Development

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.

Overview

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

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

By default, development mode emulates supported resources locally. To use the real resource from Cloudflare, set the dev.remote option:

const kv = await KVNamespace("my-kv", {
  dev: {
    remote: true,
  },
});
const worker = await Worker("my-worker", {
  entrypoint: "worker.ts",
  bindings: {
    KV: kv,
  },
});

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 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"],
});

Local Development

Overview

Workers

Bindings

Remote Bindings

Web Frameworks

Limitations