Learn Alchemy

Alchemy 2 declares and deploys cloud resources through Effect programs. Effect describes work with typed failures36 and required dependencies. One program declares resources, bindings23, deployment state, and the Worker that uses them.

A service is a named interface for one job. A Layer builds services and supplies their construction dependencies. A contract defines an action’s name, input, output, failure, and metadata.

Start with this repo’s Cloudflare resources. Alchemy also supports other providers. Learn the vocabulary to write infrastructure and check planned changes.

Sam Goodwin7 describes an Effect as a promise with more information: its return value, errors, and requirements. His Alchemy shorthand is “if it compiles, it should deploy and run.” Use compilation for feedback. Check cloud API failures during deployment.

The vocabulary

Trace one deploy

Read apps/infra/alchemy.run.ts from top to bottom.

  1. The file imports Alchemy, the Cloudflare provider, Effect, and the Mischief Worker from apps/site/src/worker.ts.
  2. Alchemy.Stack creates the program. Effect.gen gives it a place to yield resources and return outputs.
  3. Cloudflare.providers() supplies Cloudflare operations. Cloudflare.state() lets Alchemy compare this run with prior state.
  4. ALCHEMY_DEV guards resources that should not be touched by local development.
  5. The Zone is named RatstackZone and adopted because ratstack.sh already exists. A Zone normally retains on destroy, and this Stack does not opt into deleting it.
  6. The DNS-AID SVCB and TXT records point agent discovery at the deployed site. They use the adopted Zone’s zoneId.
  7. Cloudflare.DNS.Dnssec keeps DNSSEC active. It is adopted for the same reason as the Zone.
  8. Mischief declares the Worker with ratstack.sh as its custom domain, www.ratstack.sh as a redirect, and port 1337 for dev.
  9. The Worker construction yields its WorkerLoader and four RateLimit bindings: API_PER_IP, EXECUTE_GLOBAL, EXECUTE_PER_IP, and INTEREST_PER_IP. Effect.provide(Cloudflare.Workers.RateLimitBinding) supplies the RateLimit client layer.
  10. apps/site/src/worker.ts also yields the Interest and InterestIndex Durable Objects. EVENTS_ENABLED chooses Basin or basinFoundation: both keep the bucket, stream, and visitor salt; enabled adds the catalog, sink, and pipeline. The Worker supplies the subscriber delivery implementation when it starts, outside core.
  11. The Stack yields Website from apps/web/src/website.ts and returns both mischiefUrl and websiteUrl.

The outputs omit the production DNS declarations:

export default Alchemy.Stack(
  "RatStack",
  { providers: Cloudflare.providers(), state: Cloudflare.state() },
  Effect.gen(function* stack() {
    const mischief = yield* Mischief;
    const website = yield* Website;
    return { mischiefUrl: mischief.url, websiteUrl: website.url };
  })
);

The Stack is an Effect. Importing it describes work. The CLI runs it during a plan or deploy.

Follow the Worker bindings

apps/site/src/worker.ts exports class Mischief extends Cloudflare.Worker<Mischief>()(...) {} with main: import.meta.url, so Alchemy bundles the default Worker export. Its construction Effect yields bindings before it returns the fetch implementation. Alchemy populates Cloudflare.WorkerEnvironment dynamically; this repo keeps the expected binding shape in local types at that boundary.

const stageRateLimits = rateLimitDeclarations(yield * Stage);
yield * Cloudflare.WorkerLoader("CODE_SANDBOX");
yield * Cloudflare.RateLimit("API_PER_IP", stageRateLimits.API_PER_IP);
yield * Cloudflare.RateLimit("EXECUTE_GLOBAL", stageRateLimits.EXECUTE_GLOBAL);
yield * Cloudflare.RateLimit("EXECUTE_PER_IP", stageRateLimits.EXECUTE_PER_IP);
yield *
  Cloudflare.RateLimit("INTEREST_PER_IP", stageRateLimits.INTEREST_PER_IP);
const environment = yield * Cloudflare.WorkerEnvironment;
// SAFETY: the Worker construction declares every RateLimitBindings member and CODE_SANDBOX before reading this environment.
const bindings = environment as RateLimitBindings & {
  readonly CODE_SANDBOX: WorkerLoaderBinding;
};

apps/site/src/rate-limits.ts keeps the four native binding names and their numeric namespace IDs together. rateLimitsFrom calls the native .limit({ key }) method and turns a failed runtime call into a defect instead of failing open.

apps/site/src/sandbox-worker-loader.ts consumes the CODE_SANDBOX binding. It loads a fresh Dynamic Worker with limits and globalOutbound: null, so the code-mode Worker can compute and call declared capabilities without reaching the network. A capability is one named action with shared value definitions and a server-side implementation.

Sam describes the constructor as a Layer: declare dependencies in the Effect, use them, then return the implementation. In his React analogy, dependencies are the hooks at the top. The returned Worker is the component.

Declarations and consumers share one construction Effect. The environment assertion relies on the declared bindings. Check missing bindings in the plan and at runtime; typecheck alone cannot prove they exist.

Plan, then deploy

The scripts live in apps/infra/package.json:

pnpm infra:plan
pnpm infra:deploy
pnpm infra:dev
pnpm infra:destroy

Run the plan first. It shows create, update, adopt, and noop actions before a provider is changed. Review replacements, domains, DNS, bindings, and stage before approving a deploy.

Production is stage prod. Pass --stage prod to the Alchemy CLI. An unflagged deploy defaults to live_$USER, which can create a second Worker instead of updating production. Never run an indiscriminate stage destroy. Name the stage explicitly and read its plan first.

Alchemy v2 represents outputs as values whose contents become available during deployment. Resources can still reference one another. Sam compares this to Pulumi’s output model. The engine sees the graph before it acts. The engine orders resource operations without hand-written await chains.

Why not wrangler.toml or Terraform

Wrangler is a good Cloudflare-specific tool. This repo needs one Effect program that declares the Zone, DNS records, DNSSEC, Worker, and the bindings consumed by the Worker, so Alchemy is the chosen boundary.

Terraform would keep infrastructure and the Effect Worker in separate languages and graphs. Alchemy can infer the Worker binding wiring from the same construction code that consumes it, while still showing a plan first.

Keep an existing tool when it already owns the state and the team knows its review path. Choose Alchemy here because the typed application and the cloud graph are one lesson.

Gotchas from this repo

Try it

  1. Run pnpm infra:plan and read every action. Do not approve a deploy. Identify which resources are noop and which would change.
  2. On a throwaway branch, add one temporary RateLimit binding in apps/site/src/worker.ts, consume it, and run the Worker typecheck. Remove it after seeing how the declaration and consumer stay aligned. Do not deploy it.
  3. Run pnpm infra:dev. Alchemy starts the Worker in local workerd, using the dev port from apps/site/src/worker.ts; the ALCHEMY_DEV branch skips the production Zone and DNS resources.

Read before changing

  1. Read AGENTS.md for pins, commands, boundaries, and the fence39: checks and hooks that reject prohibited code and shortcuts.
  2. Read VISION.md for why the scaffold keeps infrastructure and application contracts explicit.
  3. Read apps/infra/alchemy.run.ts for the Stack and the cloud footprint.
  4. Read apps/infra/package.json for plan, deploy, dev, and destroy scripts.
  5. Read apps/site/src/worker.ts for Worker construction and binding consumers.
  6. Read apps/site/src/rate-limits.ts for native rate-limit types and limits.
  7. Read apps/site/src/sandbox-worker-loader.ts for the fresh-isolate sandbox boundary.
  8. Read .brain/projects/ratstack-sh/deploy-ratstack-sh.svx for real deployment history and failures.
  9. Read .brain/projects/ratstack-sh/research-alchemy-effect-worker.svx for the Worker shape and local-dev research.

Name the resource, request a plan, and check the diff.

Last changed 2026-10-10 in 978dccc. Source on GitHub. Change log.

Unlinked mentions (17)