alchemy | Blog

alchemy@2.0.0-beta.40

Fri, 15 May 2026 22:00:00 GMT

v2.0.0-beta.40 is headlined by a real Vite dev server for Cloudflare Workers — Cloudflare.Vite now boots a single process that serves your client, SSR, and Worker through Vite, with HMR. The rest of the release is fixes that quiet noisy diffs, tighten error responses, and harden codegen against odd file paths.

`Cloudflare.Vite` — real Vite dev server

Section titled “Cloudflare.Vite — real Vite dev server”

bun alchemy dev for a Cloudflare.Vite resource previously bundled the Worker and served the built output through the sidecar. That worked, but it skipped the part of the Vite toolchain people actually want during development: HMR, on-demand SSR, the client/SSR/worker environments wired together.

beta.40 replaces that with vite.createServer driven through @distilled.cloud/cloudflare-vite-plugin. The sidecar now hosts a Vite dev server that serves your client and SSR, while the Worker runs in the same process against the live module graph:

const web = yield* Cloudflare.Vite("Web", {
  main: "./src/worker.ts",
  env: { VITE_API_URL: api.url.as<string>() },
});

HMR works in dev — edit a route component, the browser hot-reloads; edit the worker, the Worker reloads.
props.env keeps the beta.39 semantics: VITE_-prefixed keys are inlined into the client/SSR bundle via import.meta.env.*, everything else is a runtime Worker binding.
Vite is resolved from the project’s own node_modules first (via createRequire) so you control the version.

AiGateway: no more update-every-deploy

Section titled “AiGateway: no more update-every-deploy”

Cloudflare.AiGateway was reporting update on every bun alchemy deploy, even when nothing had changed. Two things were going on:

The provider was diffing against news instead of observed cloud state.
The provider’s defaults didn’t match what the Cloudflare API actually returns, so the first post-create diff always showed drift.

Both are fixed. Defaults now match the API’s response shape (0, false, null where the API returns those), and Diff.ts gained the helpers needed to compare observed-vs-desired correctly. Deploys are quiet again unless something genuinely changed.

Fixes #332 and #334.

Worker HTTP: log full Cause server-side, return generic 500

Section titled “Worker HTTP: log full Cause server-side, return generic 500”

The Cloudflare Worker HTTP adapter was leaking internal error detail into 500 responses. The fix flips that: the full Cause (stack, annotations, defects) is logged on the server, and the client receives a generic Internal Server Error 500. Same behavior as Effect’s own HttpServer.serve defaults — just now consistent under Cloudflare.Worker.

This pairs with the beta.39 lifecycle adapter fix and finishes the cleanup of the Worker HTTP path.

Fixes #336.

Sanitize entrypoint URLs in generated code

Section titled “Sanitize entrypoint URLs in generated code”

Codegen for Lambda, ECS, EC2-hosted, Cloudflare Worker, and Cloudflare Container entrypoints was interpolating importPath directly into a template string:

import entrypoint from "${importPath}";
import entrypoint from ${JSON.stringify(importPath)};

On macOS/Linux this never bit anyone. On Windows, paths containing backslashes (or any path with embedded quotes, unicode, etc.) generated invalid TypeScript. JSON.stringify emits a guaranteed-valid JS string literal across every codegen site.

Other fixes

Section titled “Other fixes”

Cloudflare.start forwards startup options — start’s options were silently dropped before they reached the container runtime. Thanks Christopher Yovanovitch (#341).
bun alchemy dev lockfile moves to @alchemy.run/node-utils and the legacy Sidecar/Lock.ts is gone (#345).
Cloudflare state store version bumped to 5 — clients pinned to older versions will refuse to load mismatched state and prompt you to upgrade.
scopeTransferToStream reverted — the optimization was causing 415 responses under workerd; reverting restores the previous (correct) HTTP semantics.
Axiom smartfilter chart subtype — used by the internal otel dashboard; available now if you build your own Axiom charts via Axiom.Chart (#339).

Contributors

Section titled “Contributors”

Big thank-you to everyone who shipped code in this beta:

Christopher Yovanovitch — Cloudflare.start options forwarding (#341)

Where to go next

Section titled “Where to go next”

alchemy@2.0.0-beta.39

Wed, 13 May 2026 18:00:00 GMT

v2.0.0-beta.39 is a fix-only release that lands three things people hit immediately after beta.38: SPAs reading import.meta.env.VITE_*, Effect RPC servers running under the Cloudflare Worker adapter, and the brand-new SendEmail binding showing up in Worker binding types.

`Cloudflare.Vite` inlines `VITE_*` env into the bundle

Section titled “Cloudflare.Vite inlines VITE_* env into the bundle”

Cloudflare.Vite("Site", { env: { ... } }) was forwarding env only as runtime Worker bindings — the values never made it into the client (or SSR) bundle. SPAs reading import.meta.env.VITE_API_URL fell back to whatever default the code hardcoded, breaking dynamic backend URLs at build time.

The build step now passes props.env through Vite’s define hook, emulating vite build’s env semantics:

const web = yield* Cloudflare.Vite("Web", {
  env: { VITE_API_URL: worker.url.as<string>() },
});
// SPA: `import.meta.env.VITE_API_URL` now contains the deployed worker URL.

The rules match Vite itself:

Only VITE_-prefixed keys are inlined into the bundle as import.meta.env.<key> (matches Vite’s default envPrefix).
Non-VITE_ entries stay out of the bundle but are still attached to the deployed Worker as runtime bindings.
Redacted values are unwrapped when they’re VITE_-prefixed — opting them into the public bundle is an explicit choice you make by naming them that way.

The tutorial gains an Inject the Worker URL at build time section covering the pattern end-to-end.

Cloudflare Worker HTTP adapter — Effect’s handled lifecycle

Section titled “Cloudflare Worker HTTP adapter — Effect’s handled lifecycle”

The Worker HTTP adapter previously hand-rolled the HttpServerRequest / HttpServerResponse bridge. That worked for simple handlers but diverged from Effect’s HttpEffect.toHandled / toWebHandler lifecycle in ways that broke scoped HTTP apps under workerd — most visibly, RpcServer.toHttpEffect hung when served through Alchemy even though the same app worked under raw Wrangler.

The adapter now runs handlers through Effect’s standard HTTP lifecycle while preserving every Worker-specific behavior:

cf-connecting-ip → remoteAddress
the original Cloudflare Request service
patched request.raw access
existing 500 response mapping from serveWebRequest

…plus the parts that were missing: stream-scope transfer, HEAD body suppression, and request-abort interruption.

The net effect: anything that worked under @effect/platform’s standard HTTP lifecycle now works under Cloudflare.Worker too. RpcServer.toHttpEffect, in particular, is unblocked.

— Thanks to Will King (#328) for the fix. Fixes #327.

`SendEmail` binding type inference

Section titled “SendEmail binding type inference”

beta.38 added Cloudflare.SendEmail but two wiring sites in Worker.ts were missed — the binding type inference didn’t know about it, and the deploy-time binding metadata didn’t emit a send_email entry. The result: typing bindings: { EMAIL: Email } on a Worker errored, and deploys silently dropped the binding.

Both are wired up now — SendEmail is a first-class member of the Worker binding union, the env key carries the right runtime type, and Cloudflare receives the expected send_email binding metadata at deploy time.

— Thanks to Gerben Mulder (#326) for catching this.

Contributors

Section titled “Contributors”

Big thank-you to everyone who shipped code in this beta:

Will King — Cloudflare Worker HTTP effect lifecycle (#328)
Gerben Mulder — SendEmail Worker binding type and meta (#326)

Where to go next

Section titled “Where to go next”

alchemy@2.0.0-beta.38

Wed, 13 May 2026 00:00:00 GMT

v2.0.0-beta.38 adds two new building blocks — full Cloudflare Email (zone routing + the send_email Worker binding) and the Action plan node for arbitrary Effects that run during apply — plus a behind-the-scenes Neon refactor onto the typed @distilled.cloud/neon SDK and a fault-tolerance fix in the apply transport.

Cloudflare Email

Section titled “Cloudflare Email”

Four new resources and one binding cover the whole flow: turn on Email Routing for a zone, register verified destination addresses, forward inbound mail with routing rules, and send outbound mail from a Worker.

// alchemy.run.ts — enable Email Routing on a zone you own
const routing = yield* Cloudflare.EmailRouting("Routing", {
  zone: "example.com",
});

// Register a verified destination
const ops = yield* Cloudflare.EmailAddress("Ops", {
  email: "ops@example.com",
});

// Forward inbound info@ → ops@
const rule = yield* Cloudflare.EmailRule("InfoForward", {
  zone: "example.com",
  matchers: [{ type: "literal", field: "to", value: "info@example.com" }],
  actions: [{ type: "forward", value: ["ops@example.com"] }],
});

// Declare a `send_email` binding (the id is the env key)
export const Email = Cloudflare.SendEmail("EmailOps", {
  destinationAddress: "ops@example.com",
  allowedSenderAddresses: ["noreply@example.com"],
});

Bind SendEmail on a Worker and the runtime client gives you send (parsed) and sendRaw (RFC 822 bytes) with the same Effect error channel as every other binding:

export default Cloudflare.Worker("Notifier",
  { main: import.meta.path },
  Effect.gen(function* () {
    const email = yield* Cloudflare.SendEmail.bind(Email);

    return {
      fetch: Effect.gen(function* () {
        yield* email.send({
          from: "noreply@example.com",
          to: "ops@example.com",
          subject: "Hello",
          text: "Hi from the edge",
        });
        return HttpServerResponse.text("sent");
      }),
    };
  }).pipe(Effect.provide(Cloudflare.SendEmailBindingLive)),
);

Providers › EmailRouting · EmailAddress · EmailRule · SendEmail

`Action` — Effects that run as part of apply

Section titled “Action — Effects that run as part of apply”

An Action is a node in the stack DAG that runs an arbitrary Effect during apply when its resolved input changes — the missing primitive for things like database migrations, cache invalidation, deploy announcements, or anything else that isn’t a cloud resource but needs to run in order alongside one.

The shape is intentionally close to Resource: define once, instantiate in a stack, pass it inputs, get an Output back that downstream nodes can depend on.

import * as Alchemy from "alchemy";
import * as Effect from "effect/Effect";

const Sync = Alchemy.Action("Sync",
  Effect.fn(function* (input: { table: string }) {
    return { rows: 42 };
  }),
);

// In a stack:
const rows = yield* Sync({ table: bucket.name });
//          ^? Output<{ rows: number }>

Unlike a Resource, an Action has no create/update/replace/delete lifecycle — the engine just hashes the resolved input and runs the body when it drifts. Removing the Action from the stack drops its persisted state in the GC pass; the body is never re-invoked on delete.

The plan reports actions on their own row:

Plan: 1 to create | 1 to update | 1 to run

~ Api (Cloudflare.Worker)
+ BucketA (Cloudflare.R2Bucket)
λ AnnounceDeploy (AnnounceDeploy) [action]
· DbMigrate (DbMigrate) [action]

λ (cyan) means will run this apply; · (gray) means input hash matches, skip. --force flips skip→run for actions the same way it does for resources.

Init-style construction works too, for the common case where the body needs Effect Services from the stack’s layers:

const Sync = Alchemy.Action("Sync",
  Effect.gen(function* () {
    const db = yield* Database;
    const logger = yield* Logger;
    return Effect.fn(function* (input: { table: string }) {
      yield* logger.info(`syncing ${input.table}`);
      return { rows: yield* db.count(input.table) };
    });
  }),
);

The init Effect runs once per process (memoized), so the runner is shared across every instance and every re-run.

Actions also participate in the dependency graph in both directions — they can take resource Outputs as input and their own output can be consumed by downstream resources or other actions. The scheduler waits on a separate “stable” signal so an action body never observes a resource’s precreate stub; it only sees terminal cloud state.

Concepts › Actions

Neon on `@distilled.cloud/neon`

Section titled “Neon on @distilled.cloud/neon”

Neon.Project and Neon.Branch no longer ship a hand-rolled HTTP wrapper — they route through the typed @distilled.cloud/neon SDK. The user-facing API is unchanged; what’s gone is the api.ts shim, the manual JSON shapes, and the per-call error mapping.

import * as api from "./api.ts";
import { getProject, updateProject, deleteProject } from "@distilled.cloud/neon/Operations";

404 handling now uses the SDK’s tagged error directly:

getProject({ project_id }).pipe(
  Effect.catchTag("NotFound", () => Effect.succeed(undefined)),
)

This is mostly an internal cleanup, but it pays off immediately: errors carry typed tags instead of opaque strings, retries hang off Schedule instead of hand-written try/catch, and the next time the upstream OpenAPI spec moves we regenerate one package instead of patching one file.

Fault tolerance in the apply transport

Section titled “Fault tolerance in the apply transport”

The transport that streams resource lifecycle events between the apply worker and the renderer now treats transient send/receive errors as retryable instead of collapsing the whole run. A flaky connection that drops mid-apply no longer aborts the stack — the transport backs off, reconnects, and resumes.

Other changes worth knowing about

Section titled “Other changes worth knowing about”

effect@4.0.0-beta.66. Tracks the latest Effect release. No public Alchemy API change; downstream apps pinning Effect themselves should bump in lockstep.
ignore is now vendored. The MIT-licensed ignore package is inlined into the Alchemy build to shrink the supply-chain surface (one less transitive dependency for everyone running alchemy deploy in CI).
OTLP dashboard refresh. Self-hosted OTel dashboards now have resource-usage ranking and error-rate charts per Stack / Stage. No code change in user code — it’s all dashboard config.

Where to go next

Section titled “Where to go next”

alchemy@2.0.0-beta.37

Tue, 12 May 2026 00:00:00 GMT

v2.0.0-beta.37 is the biggest beta in a while. The headline addition is cross-stack and cross-stage references — the missing piece that lets PR-preview stages share a database with staging instead of re-provisioning a whole Postgres cluster every time someone opens a draft PR. On top of that: fully-typed Worker-to-Worker bindings, typed Workflow I/O, the new Alchemy.Secret / Alchemy.Variable one-liners, cron triggers, and an Analytics Engine binding.

A bunch of this came from outside the core team — props to the contributors throughout, and full credits at the bottom of the post.

Cross-stack and cross-stage references

Section titled “Cross-stack and cross-stage references”

Lazy, typed references to resources deployed by a different stack or stage. The use case it was built for: ephemeral PR-preview stages that need a Neon project, shouldn’t pay for their own, and should instead share one that’s owned by staging.

Pointing a PR stage at `staging`’s database

Section titled “Pointing a PR stage at staging’s database”

Same alchemy.run.ts, conditional on the stage. If the stage looks like a PR preview (pr-147, pr-148, …), Neon.Project.ref reaches into the staging stage’s state file and pulls out the already-deployed project. Otherwise the stage creates its own.

src/Db.ts

import * as Alchemy from "alchemy";
import * as Drizzle from "alchemy/Drizzle";
import * as Neon from "alchemy/Neon";
import * as Effect from "effect/Effect";

export const NeonDb = Effect.gen(function* () {
  const { stage } = yield* Alchemy.Stack;

  const schema = yield* Drizzle.Schema("app-schema", {
    schema: "./src/schema.ts",
    out: "./migrations",
  });

  // PR previews share the long-lived staging project.
  // Every other stage gets its own.
  const project = stage.startsWith("pr-")
    ? yield* Neon.Project.ref("app-db", { stage: "staging" })
    : yield* Neon.Project("app-db", { region: "aws-us-east-1" });

  // Branches are cheap and per-stage either way.
  const branch = yield* Neon.Branch("app-branch", {
    project,
    migrationsDir: schema.out,
  });

  return { project, branch, schema };
});

Three things to note:

Same logical id, same type. "app-db" matches the id staging uses to create the project; project is Neon.Project either way, so downstream (Neon.Branch({ project })) doesn’t know or care whether it’s real or referenced.
Resolved at plan time. Alchemy reads the project’s attributes (id, host, etc.) out of staging’s persisted state store. If staging hasn’t been deployed yet, plan fails loudly with InvalidReferenceError.
PR teardown stays scoped. alchemy destroy --stage pr-147 deletes the per-PR Neon.Branch but doesn’t touch the shared project — this stage doesn’t own it.

Deploy staging once, then PR stages can point at it:

Terminal window

alchemy deploy --stage staging        # creates the project once
alchemy deploy --stage pr-147         # references it, creates only the branch

The full file lives in examples/cloudflare-neon-drizzle/src/Db.ts; the guide is at Guides › Shared database across stages.

Referencing an entire stack’s outputs

Section titled “Referencing an entire stack’s outputs”

The example above pulls one resource across stages. The other shape — pulling a whole stack’s outputs — is what you reach for in a monorepo where the frontend package wants to read the backend stack’s deployed URL.

Declare a typed stack handle once:

backend/src/Stack.ts

import * as Alchemy from "alchemy";

export class Backend extends Alchemy.Stack<
  Backend,
  { url: string }
>()("Backend") {}

Deploy the backend with Backend.make(...) (the typed shorthand for Alchemy.Stack), then yield* Backend from the frontend’s stack to get its outputs back, type-checked:

frontend/alchemy.run.ts

import * as Alchemy from "alchemy";
import * as Cloudflare from "alchemy/Cloudflare";
import { Backend } from "backend";
import * as Effect from "effect/Effect";

export default Alchemy.Stack(
  "Frontend",
  { providers: Cloudflare.providers(), state: Cloudflare.state() },
  Effect.gen(function* () {
    // Resolves Backend's outputs from the same stage of the same
    // stack name. `pr-42` frontend reads `pr-42` backend.
    const backend = yield* Backend;
    //    ^? { url: string }

    return yield* Cloudflare.Vite("Website", {
      env: { VITE_API_URL: backend.url },
    });
  }),
);

yield* Backend defaults to “same stage as the consumer”. When you need to pin — say, the prod frontend always reads the prod backend regardless of which branch deploys it — use Backend.stage.<name>:

const backend = yield* Backend.stage.prod;        // always pin to prod
const backend = yield* Backend.stage["pr-42"];    // arbitrary stage name

Under the hood, both shapes are Output.stackRef / Resource.ref reading the state store. The new APIs just make them ergonomic.

Concepts › References · Guides › Shared database · Guides › Monorepos · Tutorial › Branch from a shared database

`Alchemy.Secret` and `Alchemy.Variable`

Section titled “Alchemy.Secret and Alchemy.Variable”

The boring part of a stack — wiring an env var into a deploy target — used to leak across three files. One yield now collapses it into a line that’s also a typed runtime accessor.

// alchemy.run.ts — declare once on the Worker
export default Cloudflare.Worker("Api",
  { main: import.meta.path },
  Effect.gen(function* () {
    const apiKey = yield* Alchemy.Secret("OPENAI_API_KEY");
    //    ^? Output<Redacted<string>>

    return {
      fetch: Effect.gen(function* () {
        // …and read the bound value inside the handler.
        const key = yield* apiKey; // Redacted<string>
        return HttpServerResponse.text(
          `key has ${Redacted.value(key).length} chars`,
        );
      }),
    };
  }),
);

Wire it into another Worker as a binding:

alchemy.run.ts

import Backend, { Bucket } from "./src/backend.ts";

export const Website = Cloudflare.Vite("Website", {
  bindings: {
    BUCKET: Bucket,       // R2 binding
    BACKEND: Backend,     // Worker-to-Worker binding
  },
});

Now the caller has three ways to talk to the backend. All three are real, all three are typed, all three work in the same handler — pick whichever fits the call site.

// frontend route handler
import * as Cloudflare from "alchemy/Cloudflare";
import type Backend from "../backend.ts";
import { env } from "../env.ts";

// Option 1 — async binding (just call the platform API directly).
const object = await env.BUCKET.get(key);

// Option 2 — Worker-to-Worker fetch over the service binding.
const res = await env.BACKEND.fetch(`https://backend/?key=${encodeURIComponent(key)}`);

// Option 3 — typed RPC. `toPromiseApi<Backend>` wraps the wire-shape
// binding into a Promise<T> view that throws on `Effect.fail` and
// unwraps stream envelopes — full method signatures from `Backend`.
const backend = Cloudflare.toPromiseApi<Backend>(env.BACKEND);
const value = await backend.hello(key);
//    ^? string | null  (typed end-to-end)

Secrets and Variables

Mon, 11 May 2026 00:00:00 GMT

Wiring an env var into a deploy target is supposed to be the boring part of a stack — but in practice it usually leaks across two or three files: a value pulled out of .env, a binding declared on the resource, and an unsafe env.MY_KEY! somewhere in your handler.

Alchemy.Secret and Alchemy.Variable collapse all of that into a single line that’s also a typed runtime accessor.

const apiKey = yield* Alchemy.Secret("OPENAI_API_KEY");
//    ^? Output<Redacted<string>>

That one yield does three things:

reads the value from the active ConfigProvider at deploy time (no process.env.X! needed)
attaches it to the active deploy target’s environment as the platform’s secret binding (Cloudflare → secret_text, Lambda → encrypted env var)
hands you back an accessor — yield* apiKey inside fetch resolves the value at runtime, typed as Redacted<string>

One API, every runtime

Section titled “One API, every runtime”

The same call works whether the active runtime is a Cloudflare Worker, an AWS Lambda, or anything else that implements Alchemy’s serverless contract. Each provider routes the value to its native secret/variable binding under the hood:

// Cloudflare Worker
export default Cloudflare.Worker("Worker", { main: import.meta.path },
  Effect.gen(function* () {
    const apiKey = yield* Alchemy.Secret("OPENAI_API_KEY");
    return {
      fetch: Effect.gen(function* () {
        const key = yield* apiKey; // Redacted<string>
        return HttpServerResponse.text(`got ${Redacted.value(key).length} chars`);
      }),
    };
  }),
);

// AWS Lambda — exact same shape
export default AWS.Lambda.Function("Function", { main: import.meta.filename, url: true },
  Effect.gen(function* () {
    const apiKey = yield* Alchemy.Secret("OPENAI_API_KEY");
    return {
      fetch: Effect.gen(function* () {
        const key = yield* apiKey;
        return HttpServerResponse.text(`got ${Redacted.value(key).length} chars`);
      }),
    };
  }),
);

Plain values when you don’t need redaction

Section titled “Plain values when you don’t need redaction”

Alchemy.Variable is the same shape without the Redacted wrapper. Strings deploy as plain_text, anything else as JSON, and the runtime accessor returns the original type:

const port = yield* Alchemy.Variable("PORT", 3000);
const flags = yield* Alchemy.Variable("FLAGS", { beta: true });

// later, in fetch:
const p = yield* port; // number — 3000
const f = yield* flags; // { beta: true }

No JSON parsing, no as casts — the type you put in is the type you get back.

Four input shapes

Section titled “Four input shapes”

Both helpers accept a literal, an Effect, a Config, or default to reading from Config under the same name:

Alchemy.Secret("API_KEY");                              // Config.redacted("API_KEY")
Alchemy.Secret("API_KEY", "sk-123");                    // string literal
Alchemy.Secret("API_KEY", Effect.succeed("sk-123"));    // Effect<string | Redacted>
Alchemy.Secret("API_KEY", Config.string("OPENAI_KEY")); // Config<string | Redacted>

alchemy@2.0.0-beta.36

Sat, 09 May 2026 00:00:00 GMT

v2.0.0-beta.36 is mostly a Cloudflare-themed release — three new Worker bindings (Images, Hyperdrive, R2 lifecycle policies), all from outside the core team. Props to the contributors throughout, and full credits in the Contributors section.

Cloudflare Images binding

Section titled “Cloudflare Images binding”

Cloudflare’s image transformation runtime, exposed as a Worker binding. The Effect-native client takes an Effect Stream<Uint8Array> input — typically the request body — and either streams a transformed image back out or returns typed metadata.

// alchemy.run.ts — declare the pipeline resource
export const Pipeline = yield* Cloudflare.Images({ name: "PIPELINE" });

// in your Worker
export default class ImageWorker extends Cloudflare.Worker<ImageWorker>()(
  "ImageWorker",
  { main: import.meta.filename },
  Effect.gen(function* () {
    const images = yield* Cloudflare.Images.bind(Pipeline);

    return {
      fetch: Effect.gen(function* () {
        const request = yield* HttpServerRequest;

        // Probe the upload — returns format, width, height, etc.
        if (request.url.endsWith("/info")) {
          const info = yield* images.info(request.stream);
          return yield* HttpServerResponse.json(info);
        }

        // Transform: resize to 512×512 WebP, stream the result back.
        const transformed = yield* images
          .input(request.stream)
          .transform({ width: 512, height: 512 })
          .output({ format: "image/webp" });
        return HttpServerResponse.stream(transformed.body);
      }),
    };
  }).pipe(Effect.provide(Cloudflare.ImagesBindingLive)),
) {}

— Thanks to Alex (#237) for the contribution. Images.ts

Hyperdrive in Worker bindings

Section titled “Hyperdrive in Worker bindings”

Hyperdrive resources are bindable on Workers the same way as R2, KV, D1. Two flavors to know:

Declare a Hyperdrive over an existing origin string. Useful when the database lives outside of Alchemy (existing RDS, Supabase, etc.):

const Hyperdrive = yield* Cloudflare.Hyperdrive("DbPool", {
  origin: { connectionString: process.env.POSTGRES_URL! },
});

Wire it onto a Neon branch you already deployed. Neon.Branch exposes a pre-parsed origin output that Cloudflare.Hyperdrive takes directly — Alchemy orders the deploy graph correctly:

src/Db.ts

export const NeonDb = Effect.gen(function* () {
  const project = yield* Neon.Project("app-db", { region: "aws-us-east-1" });
  const branch  = yield* Neon.Branch("app-branch", { project });
  return { project, branch };
});

export const Hyperdrive = Effect.gen(function* () {
  const { branch } = yield* NeonDb;
  return yield* Cloudflare.Hyperdrive("app-hyperdrive", {
    origin: branch.origin,            // direct (non-pooled) Neon endpoint
  });
});

Bind it on the Worker and read the pooled connection string at runtime — Hyperdrive does the connection pooling so the Worker can spin up a fresh pg client per request without exhausting the database:

export default class Api extends Cloudflare.Worker<Api>()(
  "Api",
  {
    main: import.meta.path,
    compatibility: { flags: ["nodejs_compat"] },
  },
  Effect.gen(function* () {
    const hd = yield* Cloudflare.Hyperdrive.bind(Hyperdrive);

    return {
      fetch: Effect.gen(function* () {
        const connectionString = yield* hd.connectionString;
        const rows = yield* Effect.promise(async () => {
          const client = new Client({ connectionString });
          await client.connect();
          try {
            const r = await client.query("SELECT now() as now");
            return r.rows;
          } finally {
            await client.end().catch(() => {});
          }
        });
        return yield* HttpServerResponse.json({ rows });
      }),
    };
  }).pipe(Effect.provide(Cloudflare.HyperdriveConnectionLive)),
) {}

— Thanks to Baptiste Arnaud (#282) for the contribution. Tutorial › Neon + Hyperdrive

R2 lifecycle rules

Section titled “R2 lifecycle rules”

Object lifecycle policies on R2Bucket — age-based deletion, storage-class transitions, multipart-upload abort — declared inline alongside the rest of the bucket config. Max 1000 rules per bucket; pass an empty array (or omit) to clear all rules.

const Logs = yield* Cloudflare.R2Bucket("Logs", {
  lifecycleRules: [
    {
      id: "archive-then-delete",
      prefix: "logs/",
      // After 60 days: move to Infrequent Access.
      storageClassTransitions: [
        {
          condition: { type: "Age", maxAge: 60 * 60 * 24 * 60 },
          storageClass: "InfrequentAccess",
        },
      ],
      // After 365 days: delete entirely.
      deleteObjectsTransition: {
        condition: { type: "Age", maxAge: 60 * 60 * 24 * 365 },
      },
      // Stale multipart uploads — drop after 7 days.
      abortMultipartUploadsTransition: {
        condition: { type: "Age", maxAge: 60 * 60 * 24 * 7 },
      },
    },
  ],
});

Each entry is reconciled in place — edit the array and the next deploy applies the delta against R2’s live policy.

— Thanks to Baptiste Arnaud (#284) for the contribution. See Cloudflare R2 docs › Object lifecycles for the underlying behavior.

Fixes worth knowing about

Section titled “Fixes worth knowing about”

*.localhost resolution in dev mode. bun alchemy dev now routes *.localhost hostnames through a custom undici dispatcher, so cross-Worker fetch calls to e.g. https://backend.localhost resolve to the local sidecar instead of failing DNS.

Performance

Section titled “Performance”

Smoke tests install canaries at the workspace root rather than per-fixture. Batched smoke runs are noticeably faster on cold caches.

Contributors

Section titled “Contributors”

Big thank-you to everyone who shipped code in this beta:

Alex — Cloudflare Images binding (#237)
Baptiste Arnaud — Hyperdrive in Worker bindings (#282)
Baptiste Arnaud — R2 lifecycle rules (#284)

Where to go next

Section titled “Where to go next”

alchemy@2.0.0-beta.35

Fri, 08 May 2026 00:00:00 GMT

v2.0.0-beta.35 is out. The headline addition is an Effect-native, Stream-shaped consumer API for Cloudflare Queues — write a queue handler the same way you’d write any other Effect pipeline. Plus R2 bucket custom domains, non-string Worker env bindings, Neon logical replication, and a handful of CLI polish. Community contributors get inline shoutouts; full credits in the Contributors section.

`Cloudflare.messages(queue).subscribe(...)` — Effect-native queue consumer

Section titled “Cloudflare.messages(queue).subscribe(...) — Effect-native queue consumer”

Process Cloudflare Queue batches as a typed Effect Stream, with ack/retry exposed per message. The handler returns when the batch is done; failed messages get retried up to maxRetries. Same Worker, same Effect runtime, same bindings — the queue consumer is just another yield* in the init phase.

A real producer-and-consumer pair: a Worker accepts POSTs to /queue/send, the consumer writes each message to R2 as JSON so the result is observable. Bindings already on the Worker (bucket, queue) are in scope inside the stream handler — the consumer is a peer to the Worker’s init phase, not a separate file.

import * as Cloudflare from "alchemy/Cloudflare";
import * as Effect from "effect/Effect";
import * as Stream from "effect/Stream";
import { Bucket } from "./Bucket.ts";
import { Queue } from "./Queue.ts";

interface QueueMessageBody {
  id: string;
  text: string;
  sentAt: number;
}

export default class Api extends Cloudflare.Worker<Api>()(
  "Api",
  { main: import.meta.filename },
  Effect.gen(function* () {
    const bucket = yield* Cloudflare.R2Bucket.bind(Bucket);
    const queueResource = yield* Queue;
    const queue = yield* Cloudflare.QueueBinding.bind(queueResource);

    // Consumer side. Each batch arrives as a Stream of QueueMessage<Body>;
    // success ack()s every message, failure retry()s. Crash mid-batch and
    // unprocessed messages are redelivered.
    yield* Cloudflare.messages<QueueMessageBody>(queueResource, {
      batchSize: 25,
      maxRetries: 3,
    }).subscribe((stream) =>
      Stream.runForEach(stream, (msg) =>
        bucket
          .put(`/queue/${msg.body.id}`, JSON.stringify(msg.body), {
            httpMetadata: { contentType: "application/json" },
          })
          .pipe(Effect.asVoid),
      ),
    );

    return {
      // Producer side: POST /queue/send adds a message.
      fetch: Effect.gen(function* () {
        const request = yield* HttpServerRequest;
        if (request.url === "/queue/send" && request.method === "POST") {
          const text = yield* request.text;
          const msg: QueueMessageBody = {
            id: crypto.randomUUID(),
            text,
            sentAt: Date.now(),
          };
          yield* queue.send(msg);
          return yield* HttpServerResponse.json({ sent: msg }, { status: 202 });
        }
        return HttpServerResponse.text("ok");
      }),
    };
  }).pipe(
    Effect.provide(
      Layer.mergeAll(
        Cloudflare.R2BucketBindingLive,
        Cloudflare.QueueBindingLive,
        Cloudflare.QueueEventSourceLive, // required for `messages(...)` to dispatch
      ),
    ),
  ),
) {}

alchemy | Blog

alchemy@2.0.0-beta.40

Cloudflare.Vite — real Vite dev server

AiGateway: no more update-every-deploy

Worker HTTP: log full Cause server-side, return generic 500

Sanitize entrypoint URLs in generated code

Other fixes

Contributors

Where to go next

alchemy@2.0.0-beta.39

Cloudflare.Vite inlines VITE_* env into the bundle

Cloudflare Worker HTTP adapter — Effect’s handled lifecycle

SendEmail binding type inference

Contributors

Where to go next

alchemy@2.0.0-beta.38

Cloudflare Email

Action — Effects that run as part of apply

Neon on @distilled.cloud/neon

Fault tolerance in the apply transport

Other changes worth knowing about

Where to go next

alchemy@2.0.0-beta.37

Cross-stack and cross-stage references

Pointing a PR stage at staging’s database

Referencing an entire stack’s outputs

Alchemy.Secret and Alchemy.Variable

Worker-to-Worker bindings, fully typed

Secrets and Variables

One API, every runtime

Plain values when you don’t need redaction

Four input shapes

Where to go next

alchemy@2.0.0-beta.36

Cloudflare Images binding

Hyperdrive in Worker bindings

R2 lifecycle rules

Fixes worth knowing about

Performance

Contributors

Where to go next

alchemy@2.0.0-beta.35

Cloudflare.messages(queue).subscribe(...) — Effect-native queue consumer

`Cloudflare.Vite` — real Vite dev server

`Cloudflare.Vite` inlines `VITE_*` env into the bundle

`SendEmail` binding type inference

`Action` — Effects that run as part of apply

Neon on `@distilled.cloud/neon`

Pointing a PR stage at `staging`’s database

`Alchemy.Secret` and `Alchemy.Variable`

`Cloudflare.messages(queue).subscribe(...)` — Effect-native queue consumer