Part 1: Your First Stack

In this first part you’ll install Alchemy and Effect, create a Stack with a Cloudflare R2 Bucket, and deploy it — all in under five minutes.

Prerequisites

Bun (recommended) or Node.js 20+
A Cloudflare account

Create a project

Start with an empty directory and initialize a package.json:

mkdir my-app && cd my-app && bun init -y

mkdir my-app && cd my-app && npm init -y

mkdir my-app && cd my-app && pnpm init

mkdir my-app && cd my-app && yarn init -y

Install dependencies

Install alchemy@2.0.0-beta.3 and effect@4.0.0-beta.48:

bun add alchemy@2.0.0-beta.3 effect@4.0.0-beta.48 @effect/platform-bun@4.0.0-beta.48

npm install alchemy@2.0.0-beta.3 effect@4.0.0-beta.48 @effect/platform-node@4.0.0-beta.48

pnpm add alchemy@2.0.0-beta.3 effect@4.0.0-beta.48 @effect/platform-node@4.0.0-beta.48

yarn add alchemy@2.0.0-beta.3 effect@4.0.0-beta.48 @effect/platform-node@4.0.0-beta.48

Create the Stack

Every Alchemy program starts with a Stack — a collection of Resources managed by Providers with state tracked between deploys.

Create an alchemy.run.ts file:

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

export default Alchemy.Stack(
  "MyApp",
  {
    providers: Layer.empty,
  },
  Effect.gen(function* () {
    // we'll add resources here next
  }),
);

This is a valid program, but it doesn’t do anything yet. The Layer.empty providers and empty generator body are placeholders.

Add a Resource

Resources represent cloud infrastructure — buckets, queues, functions, databases, and so on. Each resource is yield*-ed inside the Stack’s Effect generator.

Let’s add a Cloudflare R2 Bucket to our Stack and observe the type error:

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

export default 
import Alchemy
Alchemy.
Stack<void, Cloudflare.Providers>(stackName: string, options: {
    providers: Layer.Layer<NoInfer<Cloudflare.Providers>, never, StackServices>;
}, eff: Effect.Effect<void, never, StackServices | Cloudflare.Providers>): Effect.Effect<CompiledStack<void, any>, never, never> (+2 overloads)
export Stack
Stack(
  "MyApp",
  {
    providers: 
import Layer
Layer.
const empty: Layer.Layer<never, never, never>
A Layer that constructs an empty Context.
This layer provides no services and can be used as a neutral element
in layer composition or as a starting point for building layers.
@example 
import { Layer } from "effect"

const emptyLayer = Layer.empty
@since ― 2.0.0
@category ― constructors
empty,Error ts(2322)  ― Type 'Layer<never, never, never>' is not assignable to type 'Layer<NoInfer<Providers>, never, StackServices>'.
  Type 'Cloudflare.Providers' is not assignable to type 'never'.
  },
  
import Effect
Effect.
const gen: <Effect.Effect<Cloudflare.R2Bucket, never, Cloudflare.Providers>, void>(f: () => Generator<Effect.Effect<Cloudflare.R2Bucket, never, Cloudflare.Providers>, void, never>) => Effect.Effect<void, never, Cloudflare.Providers> (+1 overload)
Provides a way to write effectful code using generator functions, simplifying
control flow and error handling.
When to Use
gen allows you to write code that looks and behaves like synchronous
code, but it can handle asynchronous tasks, errors, and complex control flow
(like loops and conditions). It helps make asynchronous code more readable
and easier to manage.
The generator functions work similarly to async/await but with more
explicit control over the execution of effects. You can yield* values from
effects and return the final result at the end.
@example 
import { Data, Effect } from "effect"

class DiscountRateError extends Data.TaggedError("DiscountRateError")<{}> {}

const addServiceCharge = (amount: number) => amount + 1

const applyDiscount = (
  total: number,
  discountRate: number
): Effect.Effect<number, DiscountRateError> =>
  discountRate === 0
    ? Effect.fail(new DiscountRateError())
    : Effect.succeed(total - (total * discountRate) / 100)

const fetchTransactionAmount = Effect.promise(() => Promise.resolve(100))

const fetchDiscountRate = Effect.promise(() => Promise.resolve(5))

export const program = Effect.gen(function*() {
  const transactionAmount = yield* fetchTransactionAmount
  const discountRate = yield* fetchDiscountRate
  const discountedAmount = yield* applyDiscount(
    transactionAmount,
    discountRate
  )
  const finalAmount = addServiceCharge(discountedAmount)
  return `Final amount to charge: ${finalAmount}`
})
@since ― 2.0.0
@category ― Creating Effects
gen(function* () {
   const 
const bucket: Cloudflare.R2Bucket
bucket = yield* 
import Cloudflare
Cloudflare.
const R2Bucket: (id: string, props?: {
    name?: Alchemy.Input<string | undefined>;
    storageClass?: Alchemy.Input<Cloudflare.R2Bucket.StorageClass | undefined>;
    jurisdiction?: Alchemy.Input<Cloudflare.R2Bucket.Jurisdiction | undefined>;
    locationHint?: Alchemy.Input<Cloudflare.R2Bucket.Location | undefined>;
} | undefined) => Effect.Effect<Cloudflare.R2Bucket, never, Cloudflare.Providers> (+2 overloads)
R2Bucket("Bucket");
  }),
);

TypeScript is telling us that Layer.empty doesn’t provide Cloudflare.Providers — the layer required by R2Bucket.

Fix the Providers

Replace Layer.empty with Cloudflare.providers() to resolve the type error:

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

export default Alchemy.Stack(
  "MyApp",
  {
   providers: Layer.empty,
   providers: Cloudflare.providers(),
  },
  Effect.gen(function* () {
    const bucket = yield* Cloudflare.R2Bucket("Bucket");
  }),
);

Now the program type-checks. The providers layer tells Alchemy how to talk to Cloudflare’s APIs, and the type system ensures you never forget to wire it up.

Return Stack outputs

Stack outputs let you see important values after a deploy. Return an object from the generator to expose them:

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

export default 
import Alchemy
Alchemy.
Stack<{
    bucketName: Alchemy.Output<string, never>;
}, Cloudflare.Providers>(stackName: string, options: {
    providers: Layer<NoInfer<Cloudflare.Providers>, never, StackServices>;
}, eff: Effect.Effect<{
    bucketName: Alchemy.Output<string, never>;
}, never, StackServices | Cloudflare.Providers>): Effect.Effect<CompiledStack<{
    bucketName: Alchemy.Output<string, never>;
}, any>, never, never> (+2 overloads)
export Stack
Stack(
  "MyApp",
  {
    
providers: Layer<NoInfer<Cloudflare.Providers>, never, StackServices>
providers: 
import Cloudflare
Cloudflare.
const providers: () => Layer<Cloudflare.Providers | Account | Cloudflare.Credentials | WebSocketConstructor | Alchemy.Provider<Command> | Alchemy.Provider<Alchemy.Random>, never, HttpClient | Scope | import("/Users/samgoodwin/workspaces/alchemy-effect/packages/alchemy/lib/Stack").Stack | import("/Users/samgoodwin/workspaces/alchemy-effect/packages/alchemy/lib/Stage").Stage | FileSystem | Path | import("/Users/samgoodwin/workspaces/alchemy-effect/packages/alchemy/lib/Config").DotAlchemy | ChildProcessSpawner>
Cloudflare providers, bindings, and credentials for Worker-based stacks.
providers(),
  },
  
import Effect
Effect.
const gen: <Effect.Effect<Cloudflare.R2Bucket, never, Cloudflare.Providers>, {
    bucketName: Alchemy.Output<string, never>;
}>(f: () => Generator<Effect.Effect<Cloudflare.R2Bucket, never, Cloudflare.Providers>, {
    bucketName: Alchemy.Output<string, never>;
}, never>) => Effect.Effect<{
    bucketName: Alchemy.Output<string, never>;
}, never, Cloudflare.Providers> (+1 overload)
Provides a way to write effectful code using generator functions, simplifying
control flow and error handling.
When to Use
gen allows you to write code that looks and behaves like synchronous
code, but it can handle asynchronous tasks, errors, and complex control flow
(like loops and conditions). It helps make asynchronous code more readable
and easier to manage.
The generator functions work similarly to async/await but with more
explicit control over the execution of effects. You can yield* values from
effects and return the final result at the end.
@example 
import { Data, Effect } from "effect"

class DiscountRateError extends Data.TaggedError("DiscountRateError")<{}> {}

const addServiceCharge = (amount: number) => amount + 1

const applyDiscount = (
  total: number,
  discountRate: number
): Effect.Effect<number, DiscountRateError> =>
  discountRate === 0
    ? Effect.fail(new DiscountRateError())
    : Effect.succeed(total - (total * discountRate) / 100)

const fetchTransactionAmount = Effect.promise(() => Promise.resolve(100))

const fetchDiscountRate = Effect.promise(() => Promise.resolve(5))

export const program = Effect.gen(function*() {
  const transactionAmount = yield* fetchTransactionAmount
  const discountRate = yield* fetchDiscountRate
  const discountedAmount = yield* applyDiscount(
    transactionAmount,
    discountRate
  )
  const finalAmount = addServiceCharge(discountedAmount)
  return `Final amount to charge: ${finalAmount}`
})
@since ― 2.0.0
@category ― Creating Effects
gen(function* () {
    const 
const bucket: Cloudflare.R2Bucket
bucket = yield* 
import Cloudflare
Cloudflare.
const R2Bucket: (id: string, props?: {
    name?: Alchemy.Input<string | undefined>;
    storageClass?: Alchemy.Input<Cloudflare.R2Bucket.StorageClass | undefined>;
    jurisdiction?: Alchemy.Input<Cloudflare.R2Bucket.Jurisdiction | undefined>;
    locationHint?: Alchemy.Input<Cloudflare.R2Bucket.Location | undefined>;
} | undefined) => Effect.Effect<Cloudflare.R2Bucket, never, Cloudflare.Providers> (+2 overloads)
R2Bucket("Bucket");

   return {
     bucketName: 
const bucket: Cloudflare.R2Bucket
bucket.bucketName,
bucketName: Alchemy.Output<string, never>
    };
  }),
);

Deploy

Run alchemy deploy to create the Bucket on Cloudflare:

alchemy deploy

Plan: 1 to create
+ Bucket (Cloudflare.R2Bucket)

Proceed?
◉ Yes ○ No
✓ Bucket (Cloudflare.R2Bucket) created
{
  bucketName: "myapp-bucket-a1b2c3d4e5",
}

Alchemy shows a plan, asks for confirmation, creates the resource, and prints the stack outputs. Your bucket is live on Cloudflare.

Verify it worked

Run alchemy deploy again. Because nothing changed, the bucket shows as a no-op:

Plan: no changes

{
  bucketName: "myapp-bucket-a1b2c3d4e5",
}

This is the core loop — declare resources in code, deploy, and Alchemy figures out what changed.

Recap

You now have:

An alchemy.run.ts with a Stack and a Cloudflare R2 Bucket
A live bucket deployed to your Cloudflare account
Stack outputs showing the bucket name

In Part 2, you’ll add a Cloudflare Worker that uses this bucket to serve HTTP requests.