alchemy

Alchemy is a TypeScript infrastructure framework built on Effect that lets you define cloud resources, IAM policies, and application runtime code (Lambdas, Workers) inside a single program instead of splitting infra config into YAML/HCL and app code into a separate runtime. Calls like Cloudflare.R2.ReadWriteBucket(Bucket) simultaneously wire the binding, environment variable, and a typed client, so a resource declaration and its consumption stay in the same file and the same type system.

It ships as both a library (the resource/provider API) and a CLI (alchemy plan|deploy|destroy|dev|logs|state) for managing stacks across environments. It targets AWS and Cloudflare today (S3, SQS, DynamoDB, Lambda, EC2, Workers, R2, D1, Durable Objects, Containers, and more), with additional first-party provider packages (Neon, PlanetScale, Hetzner, Fly.io, Axiom, Railway) developed in the same monorepo. Errors from every cloud API call are typed and handled through Effect’s error-tracking type system rather than thrown and caught ad hoc.

What You Get

• Typed resource constructors for AWS and Cloudflare (S3, SQS, DynamoDB, Lambda, EC2, Workers, R2, D1, Durable Objects, Containers) that double as runtime bindings
• A CLI (alchemy) with plan, deploy, destroy, dev, logs, state, and profile subcommands for managing stacks
• A GitHub Action for deploying prod from main and per-PR preview stacks that self-destroy on close
• First-party provider packages for Neon, PlanetScale, Hetzner, Fly.io, Axiom, and Railway alongside AWS/Cloudflare
• A local development mode (alchemy dev) that live-reloads a stack against real or emulated cloud resources

Common Use Cases

• Deploying a Cloudflare Worker bound to R2/D1/Durable Objects without hand-writing wrangler bindings
• Standing up ephemeral per-PR preview environments via the bundled GitHub Action
• Provisioning AWS resources (Lambda, DynamoDB, SQS) alongside the application code that uses them
• Managing typed IAM policies generated directly from the resource bindings a program actually uses
• Running local dev against live cloud state with alchemy dev’s watch/live-reload loop

Under The Hood

Architecture The core alchemy package (packages/alchemy) organizes around a Resource/Provider abstraction (src/Resource.ts, src/Provider.ts): a resource constructor returns an Effect that is composed into a Stack (src/Stack.ts), diffed and applied through Apply.ts/Diff.ts/Plan.ts, and reconciled against persisted state (src/State/). Cloud-specific resources live in per-provider directories (AWS/, Cloudflare/, Neon/, Hetzner/, Fly/, Axiom/, Kubernetes/, Docker/), each exposing typed bindings (e.g. Cloudflare.R2.ReadWriteBucket) that resolve to both a deploy-time resource and a runtime Effect Layer, so infrastructure declaration and application access to that infrastructure share one dependency graph. A separate Alchemist module and Cli/ package layer a command surface (plan/deploy/destroy/dev/logs/state) on top of the same resource graph, with dedicated Drift.ts logic for detecting divergence between declared and live state.

Tech Stack Written in TypeScript on the Effect ecosystem (effect, @effect/platform-*, @effect/sql-*), the monorepo is managed with pnpm workspaces, Turborepo, and Bun as the primary runtime/test driver, bundled via tsdown/rolldown. It depends on @aws-sdk/credential-providers and aws4fetch for AWS access, @octokit/rest for GitHub integration, drizzle-orm/drizzle-kit and @libsql/client for database-backed resources, and ships its own sibling packages (@alchemy.run/cloudflare-runtime, @alchemy.run/node-utils, @alchemy.run/better-auth) as workspace dependencies. Linting/formatting run through oxlint/oxfmt rather than ESLint/Prettier.

Code Quality The package carries an extensive test suite (over 1,600 *.test.ts files across the monorepo) built on @effect/vitest and a custom alchemy-test harness, covering resource lifecycle, drift, destroy robustness, and binding stability. Code is fully typed with no any-heavy escape hatches visible in core modules, uses tagged/typed errors (Data.TaggedError-style patterns) rather than throwing untyped exceptions, and enforces consistent style via a repo-wide oxlint/oxfmt configuration plus Husky pre-commit hooks.

API Design The headline ergonomic bet is binding calls that collapse three concerns (IAM policy, environment variable, typed client) into one expression, which keeps call sites short but requires learning Effect’s generator/Layer idioms before the API feels natural. Documentation is unusually thorough for an alpha project — a dedicated docs site, a five-part tutorial, over a hundred runnable examples, and an llms.txt index aimed at coding agents — which offsets the conceptual overhead of adopting Effect as a prerequisite.