Stack

A Stack is the top-level unit of deployment in Alchemy. It groups resources together, wires up providers, and tracks state across deploys.

Defining a Stack

Every Alchemy program exports a default Stack from an alchemy.run.ts file:

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

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

Alchemy.Stack takes three arguments:

1. Name — identifies this stack in state storage
2. Options — providers (required), state (optional)
3. Effect — a generator that declares resources and returns outputs

Stack outputs

The value returned from the generator becomes the stack’s output. After a deploy, outputs are printed to the console and available programmatically in tests:

Effect.gen(function* () {
  const bucket = yield* Cloudflare.R2Bucket("Bucket");
  const worker = yield* Worker;

  return {
    bucketName: bucket.bucketName,
    url: worker.url,
  };
});

Stages

Every Stack deploy targets a stage — an isolated instance like dev_sam, staging, or prod. The stage defaults to dev_$USER.

Resources are namespaced by stage, so dev and prod never interfere. Physical names include the stage (e.g. myapp-prod-bucket-abc123).

alchemy deploy --stage prod
alchemy deploy --stage pr-42

Accessing the Stack

Inside a resource or layer, you can access the current Stack’s metadata via the Stack service:

import { Stack } from "alchemy/Stack";

const table =
  yield *
  DynamoDB.Table("Jobs", {
    partitionKey: "id",
    attributes: { id: "S" },
  });

// Access stack metadata
const stack = yield * Stack;
console.log(stack.name); // "MyApp"
console.log(stack.stage); // "dev_sam"

This is useful for conditional logic based on the stage:

const queue =
  yield * SQS.Queue("Jobs").pipe(RemovalPolicy.retain(stack.stage === "prod"));

Stack and stages — the engine

Alchemy.Stack takes a name, a provider Layer, and an Effect that declares resources. After every deploy, alchemy persists the state of each resource so the next plan knows exactly what changed.

Every deploy targets a stage. State and physical names are namespaced per stage, so dev_sam, pr-147, and prod are completely isolated. Same program. Different stages.

# Each stage = its own state file + its own physical names.
$ alchemy deploy --stage dev_sam     # -> myapp-dev_sam-photos-a3f1
$ alchemy deploy --stage pr-147      # -> myapp-pr_147-photos-9b2c
$ alchemy deploy --stage prod        # -> myapp-prod-photos-7d4e

# Three independent deployments. Destroying one
# never touches the others.

• State, per stack — Each stack gets a state file (local, S3, R2, D1 — pluggable). The plan diffs declared resources against persisted state.
• Stages = isolation — Stages namespace both state and physical names. Two PRs deploy the same code into different resources without colliding.
• Deterministic physical names — Physical names derive from stack/stage/logical-id. Re-running create is idempotent — alchemy finds the existing resource.