@devries-cameron20 / t3code Mirror · read-only
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 04:45 UTC

main
mdx 138 lines 4.17 KB
Raw
1 ---
2 title: References
3 description: Read an already-deployed Resource or Stack at plan time — Resource.ref by Logical ID with optional stack/stage props, or import a Stack tag and depend on its outputs.
4 ---
5
6 A reference reads something **already deployed** — a different
7 stage, a different Stack, or both — from the persisted
8 [state store](/state-store) at plan time. References are
9 lazy and don't drift: every plan re-reads the upstream's state, so
10 downstream always sees whatever was actually last deployed.
11
12 ## Reference another stage
13
14 `Resource.ref` takes a
15 [Logical ID](/infrastructure-as-code/resource#logical-id); pass
16 `stage` to read that Resource from a different stage of this stack:
17
18 ```typescript
19 const { stage } = yield* Alchemy.Stack;
20
21 const project = stage.startsWith("pr-")
22 ? yield* Neon.Project.ref("app-db", { stage: "staging" })
23 : yield* Neon.Project("app-db", { region: "aws-us-east-1" });
24 ```
25
26 The ref has the same type as `yield* Neon.Project("app-db", { … })`
27 — pass it anywhere the real thing is accepted. Here `staging` owns
28 the database and `pr-*` stages borrow it; destroying a borrower
29 never touches the Resources it references.
30
31 ## Reference another Stack
32
33 Pass `stack` too for a Resource in a different Stack:
34
35 ```typescript
36 const sharedBucket = yield* Storage.Bucket.ref("Assets", {
37 stack: "shared-infra",
38 stage: "prod",
39 });
40 ```
41
42 `{ stack, stage, id }` is the full address; anything you omit
43 defaults to the current stack/stage. Pin `stage` when the stacks'
44 stages don't line up — `pr-147` has no counterpart in
45 `shared-infra`.
46
47 ## Depend on a Stack's outputs
48
49 When the unit you consume is a whole Stack, import its tag and
50 yield it:
51
52 ```typescript
53 // backend/src/Stack.ts
54 export class Backend extends Alchemy.Stack<
55 Backend,
56 { url: string }
57 >()("Backend") {}
58 ```
59
60 ```typescript
61 // inside the frontend Stack's Effect.gen
62 const a = yield* Backend; // current stage
63 const b = yield* Backend.stage.prod; // pinned to "prod"
64 const c = yield* Backend.stage["pr-42"]; // any stage name
65 ```
66
67 Declare the stages as a third type parameter and a misspelled
68 stage becomes a type error:
69
70 ```typescript
71 export class Backend extends Alchemy.Stack<
72 Backend,
73 { url: string },
74 "prod" | `pr-${number}`
75 >()("Backend") {}
76
77 const d = yield* Backend.stage[`pr-${pr}`];
78 ```
79
80 Every successful `apply` persists what the Stack's effect returned
81 as a per-stage output record; `yield* Backend` reads it back as a
82 proxy of typed Outputs, so `(yield* Backend).url` is
83 `Output<string>`. Full two-package walkthrough:
84 [Multiple Stacks](/project-structure/monorepo-multi-stack).
85
86 ## Escape hatches
87
88 When the Resource constructor isn't in scope, `Output.ref` is the
89 same lookup:
90
91 ```typescript
92 const bucket = Output.ref<typeof Bucket>("Bucket", {
93 stack: "shared-infra",
94 stage: "prod",
95 });
96 ```
97
98 When a typed Stack handle isn't in scope, `Output.stackRef` reads
99 the output record directly:
100
101 ```typescript
102 const backend = yield* Output.stackRef<{ url: string }>("Backend", {
103 stage: "prod",
104 });
105 ```
106
107 Prefer `Resource.ref` and `yield* MyStack` — same lookups, real
108 type bindings.
109
110 ## Deploy order
111
112 The upstream must already be deployed to the exact
113 `{ stack, stage }` the reference names, or the plan fails fast
114 with a typed `InvalidReferenceError` — there is no
115 deploy-and-hope path:
116
117 ```sh
118 alchemy deploy --stage staging # creates app-db
119 alchemy deploy --stage pr-147 # borrows staging's app-db
120 ```
121
122 Destroy in reverse order. Resolution itself is the in-stack
123 [Output](/infrastructure-as-code/outputs) flow with one difference: a reference's
124 upstream was reconciled by a previous deploy, so only its persisted
125 attributes participate in this plan.
126
127 ## Where next
128
129 - [Resource Lifecycle](/infrastructure-as-code/resource-lifecycle) — how
130 the referenced state got persisted in the first place. Next page.
131 - [Multiple Stacks](/project-structure/monorepo-multi-stack) — typed Stack
132 handles wiring a monorepo.
133 - [Shared database across stages](/cloudflare/data/shared-database) —
134 the owner/borrower pattern end to end.
135 - [Inputs & Outputs](/infrastructure-as-code/outputs) — the Output model
136 references plug into.
137 - [State Store](/state-store) — where the persisted state
138 that refs read lives.