alchemy

Infrastructure-as-Effects — cloud infrastructure and application logic as a single, type-safe Effect program.

Docs · Tutorial · Examples · Discord

---

A Worker bound to a R2 bucket and serving objects from it:

const Bucket = Cloudflare.R2.Bucket("bucket");

export default Cloudflare.Worker(
  "api",
  { main: import.meta.url },
  Effect.gen(function* () {
    const bucket = yield* Cloudflare.R2.ReadWriteBucket(Bucket);
    return {
      fetch: Effect.gen(function* () {
        const request = yield* HttpServerRequest;
        const object = yield* bucket.get(request.url);
        return HttpServerResponse.stream(object!.body);
      })
    };
  }).pipe(Effect.provide(Cloudflare.R2.ReadWriteBucketBinding)),
);

One ReadWriteBucket(Bucket) call wires the binding, env var, and typed client — at deploy time and at runtime.

---

• One program, one language. Resources, Lambdas/Workers, IAM, and SDKs live in the same Effect program — no YAML, no second runtime.
• Bindings, not glue code. S3.GetObject(bucket) wires the IAM policy, env var, and a typed SDK call in a single line.
• Errors in the type system. Every cloud API failure is a tagged Effect error you handle — or don’t — on purpose.
• AWS + Cloudflare today. S3, SQS, DynamoDB, Kinesis, Lambda, EC2 / Workers, R2, D1, Durable Objects, Containers.
• Same code, every stage. Local dev, plan / deploy, smoke tests, and CI all share one mental model.

bun add alchemy@latest effect@rc

GitHub Action

Use the root action to deploy prod from main, deploy PR previews as staging-{number}, and destroy PR previews when the PR closes:

- uses: alchemy-run/alchemy@v1
  env:
    CLOUDFLARE_ACCOUNT_ID: ${{ vars.CLOUDFLARE_ACCOUNT_ID }}
    CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

The workflow must install the alchemy CLI before this action runs.

Bootstrap with an AI coding agent

Paste this into Claude Code, Cursor, or any agent that can fetch a URL:

You are an Alchemy expert. Read https://alchemy.run/llms.txt to load the
full documentation index, then act as my pair on this project.

Goal: help me set up, build, test, and deploy a cloud application with
\`alchemy\` (Infrastructure-as-Effects, powered by Effect).

Follow the patterns from the docs and the /examples folder. Stay idiomatic
to Effect: use Layers for wiring, return Effects from lifecycle code, and
keep infra and runtime in the same program. Ask before introducing new
dependencies or breaking conventions.

Learn more

• What is Alchemy? — the framework in 2 minutes
• Getting Started — your first Stack
• Tutorial — five-part walkthrough to a tested, CI-deployed app
• Examples — runnable projects on AWS and Cloudflare
• llms.txt — agent-ready documentation index

alchemy is in alpha. Expect breaking changes. Come hang in our Discord.

Credits

Blacksmith

Thanks to Blacksmith for sponsoring our CI runners. Their fast Linux, macOS, and Windows runners help us test our packages across platforms and deploy our content-heavy website in mere minutes.

---

Summary

Infrastructure as Effects (1.4k stars, Apache-2.0, TypeScript; alchemy-run/sam-goodwin): infra and application logic in ONE fully type-safe ESM TypeScript program built on the Effect library — no YAML, no dedicated interpreter. Cloud errors map to controlled Effect-typed errors (declarative retries/failure handling); Effect Layers wire IAM policies, env vars, provider switching; AWS (S3, DynamoDB, Lambda, SQS) + Cloudflare (Workers, R2, D1); local dev via AWS emulators in Docker or workerd with hot reload. ‘Infrastructure as Code is solved’ flywheel thesis; AI-agent bootstrap prompt in README (llms.txt docs index).

Learnings

• IaE vs IaC: the collapse of the infra/app split is the genuine novelty — one program declares the bucket and runs the code against it, so cross-references (queue URL into the consumer) are ordinary typed values, not interpolation strings. Effect’s typed errors give infra failure handling the same rigor as app error handling. Trade: fully bought into Effect-TS — a deliberately deep ecosystem bet; Cloudflare+AWS-only provider surface (bespoke, not bridged). Pairs with celld (OSS) thinking: the serverless lane gets its own IaC story.

Gotchas

• (none yet)

Hands-on

(open: hands-on on AWS free tier — does the IaE error-mapping hold up on a real stack? Effect types are the interesting part)