A reference reads something already deployed — a different stage, a different Stack, or both — from the persisted state store at plan time. References are lazy and don't drift: every plan re-reads the upstream's state, so downstream always sees whatever was actually last deployed.
Reference another stage
Resource.ref takes a
Logical ID; pass
stage to read that Resource from a different stage of this stack:
const { stage } = yield* Alchemy.Stack;
const project = stage.startsWith("pr-")
? yield* Neon.Project.ref("app-db", { stage: "staging" })
: yield* Neon.Project("app-db", { region: "aws-us-east-1" }); The ref has the same type as yield* Neon.Project("app-db", { … })
— pass it anywhere the real thing is accepted. Here staging owns
the database and pr-* stages borrow it; destroying a borrower
never touches the Resources it references.
Reference another Stack
Pass stack too for a Resource in a different Stack:
const sharedBucket = yield* Storage.Bucket.ref("Assets", {
stack: "shared-infra",
stage: "prod",
}); { stack, stage, id } is the full address; anything you omit
defaults to the current stack/stage. Pin stage when the stacks'
stages don't line up — pr-147 has no counterpart in
shared-infra.
Depend on a Stack's outputs
When the unit you consume is a whole Stack, import its tag and yield it:
// backend/src/Stack.ts
export class Backend extends Alchemy.Stack<
Backend,
{ url: string }
>()("Backend") {} // inside the frontend Stack's Effect.gen
const a = yield* Backend; // current stage
const b = yield* Backend.stage.prod; // pinned to "prod"
const c = yield* Backend.stage["pr-42"]; // any stage name Declare the stages as a third type parameter and a misspelled stage becomes a type error:
export class Backend extends Alchemy.Stack<
Backend,
{ url: string },
"prod" | `pr-${number}`
>()("Backend") {}
const d = yield* Backend.stage[`pr-${pr}`]; Every successful apply persists what the Stack's effect returned
as a per-stage output record; yield* Backend reads it back as a
proxy of typed Outputs, so (yield* Backend).url is
Output<string>. Full two-package walkthrough:
Multiple Stacks.
Escape hatches
When the Resource constructor isn't in scope, Output.ref is the
same lookup:
const bucket = Output.ref<typeof Bucket>("Bucket", {
stack: "shared-infra",
stage: "prod",
}); When a typed Stack handle isn't in scope, Output.stackRef reads
the output record directly:
const backend = yield* Output.stackRef<{ url: string }>("Backend", {
stage: "prod",
}); Prefer Resource.ref and yield* MyStack — same lookups, real
type bindings.
Deploy order
The upstream must already be deployed to the exact
{ stack, stage } the reference names, or the plan fails fast
with a typed InvalidReferenceError — there is no
deploy-and-hope path:
alchemy deploy --stage staging # creates app-db
alchemy deploy --stage pr-147 # borrows staging's app-db Destroy in reverse order. Resolution itself is the in-stack Output flow with one difference: a reference's upstream was reconciled by a previous deploy, so only its persisted attributes participate in this plan.
Where next
- Resource Lifecycle — how the referenced state got persisted in the first place. Next page.
- Multiple Stacks — typed Stack handles wiring a monorepo.
- Shared database across stages — the owner/borrower pattern end to end.
- Inputs & Outputs — the Output model references plug into.
- State Store — where the persisted state that refs read lives.