sailfork / t3code-github / .repos/ alchemy-effect/ website/ src/ content/ docs/ cli/ dev.mdx

alchemy dev [options]

Run your stack in development mode with hot reloading. Resources are deployed to the cloud while Workers run in the local dev runtime; file changes trigger automatic rebuilds and hot reloads.

How it works

dev re-runs your stack under bun --watch (or node --watch with type-stripping flags on supported Node versions) via alchemy/bin/exec.

--yes and dev mode are implied, so approval prompts never appear.

A failed apply keeps dev alive so healthy resources keep serving — fix the error and save to redeploy.

Flags

OptionDescription
--stage <name>Stage to use for dev (defaults to $ALCHEMY_STAGE or dev_$USER)
--forceForce updates for resources that would otherwise no-op
--profile <name>Auth profile to use (defaults to $ALCHEMY_PROFILE or default)
--env-file <path>Load environment variables from a file
--config, -c <file>Stack file to run (defaults to alchemy.run.ts)

alchemy deploy defaults to live_$USER. Using a different default here means a bare alchemy dev will not replace a stage you deployed. Pass --stage (or $ALCHEMY_STAGE) to run local emulation against a specific stage — including one you also deploy.

Tear the default local-dev stage down with alchemy destroy --stage dev_$USER.

Environment variables

VariableDescription
ALCHEMY_WORKERD_PATHPath to the workerd binary every local Workers runtime runs, instead of the one from npm (e.g. on NixOS)
ALCHEMY_WORKERD_V8_FLAGSExtra V8 flags for every local Workers runtime, separated by whitespace (e.g. --max-old-space-size=4096)

A Worker's dev.workerd option sets the same things for that Worker alone, and wins over these.

Examples

# Start dev mode (stage dev_$USER)
alchemy dev

# Emulate the prod program locally (replaces that stage's local/live mode)
alchemy dev --stage prod

Where next