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

main
md 321 lines 11 KB
Rendered Raw
1 ---
2 title: Actions — run an Effect on deploy, skip when nothing changed
3 date: 2026-05-13
4 draft: true
5 excerpt: A node in the dependency graph that isn't a Resource. Runs at deploy time, gets typed inputs from upstream resources, returns an Output downstream nodes can consume, and skips when its input hash hasn't moved.
6 ---
7
8 You finish deploying a stack. The Worker URL changes
9 because you switched to a custom domain. Now you want to:
10
11 - ping Slack with the new URL,
12 - invalidate a CDN cache that lives outside this stack,
13 - seed a database with the latest schema version.
14
15 None of these are *resources* — they don't reconcile a
16 cloud entity, they don't have a lifecycle, they don't need
17 to track drift. They're one-shot Effects you want the deploy
18 pipeline to run when the inputs change, and skip when they
19 haven't.
20
21 You can hack this with an exec resource that runs a shell
22 command on every apply. Or a CloudFormation custom resource
23 that pretends to be CRUD-shaped just so the engine will call
24 it. Neither is what you actually want.
25
26 What you want is a node in the same dependency graph as
27 your resources, with the same typed Output references, but
28 without the lifecycle machinery — just a function that runs
29 when its input changes.
30
31 Alchemy has one. It's called an **Action**.
32
33 ## The shape
34
35 Define the Action with its type name and a body:
36
37 ```typescript
38 const Sync = Action("Sync", Effect.fn(function* (input: { table: string }) {
39 yield* Effect.log(`syncing ${input.table}`);
40 return { rows: 42 };
41 }));
42 ```
43
44 Call it inside a stack to register an instance:
45
46 ```typescript
47 const rows = yield* Sync({ table: bucket.name });
48 // ^ Output<{ rows: number }>
49 rows.rows // Output<number>
50 ```
51
52 That's the whole API. The yield does four things:
53
54 - registers an Action instance on the stack under the
55 logical id `"Sync"` (or an explicit id if you pass one)
56 - captures the input as an `Output<…>` expression — any
57 upstream resource references get resolved during apply
58 - arranges for the body to run when the resolved input
59 hash differs from what we persisted last time
60 - returns the body's return value as an `Output<…>` for
61 downstream resources or other Actions to consume
62
63 The body is just an Effect. It can `yield*` whatever
64 services it needs — log, fetch, Slack, anything. Inputs are
65 typed. The output is typed. The graph is the same graph
66 your resources live in.
67
68 ## What `Sync(...)` actually returns
69
70 Look closely at the call site:
71
72 ```typescript
73 const rows = yield* Sync({ table: bucket.name });
74 ```
75
76 `rows` is not a Task object with a `.output` field. It's an
77 `Output` directly. You can pass it as input to another
78 resource, project a field out of it (`rows.rows` →
79 `Output<number>`), or yield it inside a Worker to materialize
80 the value at runtime.
81
82 ```typescript
83 const Worker = yield* Cloudflare.Worker("Api", { main: "./src/api.ts" },
84 Effect.gen(function* () {
85 return {
86 fetch: Effect.gen(function* () {
87 const r = yield* rows; // Accessor<{ rows: number }>
88 const n = (yield* r).rows;
89 return HttpServerResponse.text(`${n} rows synced`);
90 }),
91 };
92 }),
93 );
94 ```
95
96 There is no separate concept to learn. An Action's output
97 is an Output. It composes with everything else.
98
99 ## The diff is a hash
100
101 Resources reconcile against observed cloud state. Actions
102 don't — there's no cloud state to read. So how do we know
103 whether the body should run?
104
105 We hash the resolved input.
106
107 When the plan walks the stack, it evaluates the Action's
108 input expression against the current attribute values of any
109 upstream resources, computes a SHA-256 over the resolved
110 JSON, and compares it to the hash we stored on the previous
111 deploy. Match → skip. Mismatch → run. No prior state → run.
112
113 ```typescript
114 const sameInput =
115 prior?.status === "ran" && prior.inputHash === inputHash;
116 if (sameInput && !options.force) {
117 return { action: "noop", /* ... skip the body ... */ };
118 }
119 return { action: "run", /* ... run the body ... */ };
120 ```
121
122 `--force` flips skip→run for actions, the same flag that
123 flips noop→update for resources.
124
125 The state row that records all this is tiny — there are no
126 provider props to track, no attributes to drift against. Just
127 the input hash, the input we ran with, and the output:
128
129 ```typescript
130 type ActionState =
131 | { kind: "action"; status: "running"; inputHash; input; … }
132 | { kind: "action"; status: "ran"; inputHash; input; output; … };
133 ```
134
135 Remove the Action from the stack, and the row gets dropped
136 on the next deploy. No body invoked. No lifecycle.
137
138 ## Wait for the *terminal* upstream, not the stub
139
140 The interesting bit, the one we got wrong on the first try.
141
142 Resources have a `precreate` hook that lets cyclic resources
143 publish a stub identifier — a placeholder Worker script with
144 a reserved name — before the real `reconcile` runs. That's
145 what makes Worker A ↔ Worker B cycles work
146 ([see the cycles post](/blog/2026-04-25-circular-references)).
147 Other resources can use that stub identifier early because
148 they only need the name or ARN, not the configured resource.
149
150 Actions can't. If an Action body runs against an upstream's
151 precreate stub, it sees a placeholder URL, hashes that, and
152 records "I ran with this URL." Then the real reconcile fills
153 in the actual URL, the converge phase notices the input
154 drifted, and re-runs the body. You've now invoked the body
155 twice — once against bad data, once against good — and
156 emitted "running" before either of them was really running.
157
158 The fix is a separate signal per node: `readyStable`. It
159 fires *only* after the real reconcile completes. Resources
160 keep both signals (so they can still consume each other's
161 precreate stubs); Actions wait on `readyStable` only. The
162 body never runs against placeholder data.
163
164 ```typescript
165 // resources.ts — keeps two signals
166 yield* signalReady; // fires after precreate (early)
167 // ... reconcile ...
168 yield* signalReadyStable; // fires only after reconcile (terminal)
169
170 // actions.ts — only waits on terminal
171 yield* waitForStableDeps(upstreamFqns);
172 ```
173
174 The plan log lines up with what actually happened:
175
176 ```text
177 [Bucket] creating
178 [Api] creating
179 [Api] Uploading worker (280.32 KB) ...
180 [Api] Enabling workers.dev subdomain...
181 [AnnounceDeploy] running ← only here, after Api's reconcile
182 [AnnounceDeploy] ran
183 ```
184
185 ## Pulling in dependencies
186
187 The runner signature so far is plain: `(input) => Effect<Out, _, _>`.
188 But sometimes the runner itself needs a service — a database
189 handle, a logger, an HTTP client. You don't want to construct
190 those every time the body runs.
191
192 `Action` accepts a *constructor* form. The second argument
193 is an Effect that yields its dependencies and returns the
194 runner:
195
196 ```typescript
197 const Sync = Action("Sync", Effect.gen(function* () {
198 const db = yield* Database;
199 const logger = yield* Logger;
200 return Effect.fn(function* (input: { table: string }) {
201 yield* logger.info(`syncing ${input.table}`);
202 return { rows: yield* db.count(input.table) };
203 });
204 }));
205 ```
206
207 The init Effect's `Req` bubbles to the call site:
208
209 ```typescript
210 const rows = yield* Sync({ table: bucket.name });
211 // ^ Effect.Effect<Output<…>, never, Database | Logger | Stack>
212 ```
213
214 The init runs once per process — `Effect.cached` memoizes
215 it — and every Action instance reuses the resolved runner.
216 Dependencies show up in your stack's `R`, your stack's
217 providers satisfy them, the body gets a fully-constructed
218 closure to call.
219
220 This is the same pattern as Effect's `Layer` construction.
221 You yield what you need, return what you produce. Most
222 Alchemy features follow it; Actions are no different.
223
224 ## Tag form for splitting contract and implementation
225
226 If you want the contract — "there is an Action called Sync
227 with this input shape and this output shape" — to live in a
228 different file from the implementation, use the class form:
229
230 ```typescript
231 class Sync extends Action<Sync, { table: string }, { rows: number }>()
232 ("Sync") {}
233
234 const SyncLive = Sync.make(
235 Effect.gen(function* () {
236 const db = yield* Database;
237 return Effect.fn(function* (input) {
238 return { rows: yield* db.count(input.table) };
239 });
240 }),
241 );
242 ```
243
244 Same pattern as
245 [Cloudflare.Worker's class form](/blog/2026-04-25-circular-references) —
246 the class is a Tag carrying the input/output types; `.make()`
247 binds an implementation Layer that resolves the Tag. Stack
248 providers include `SyncLive`, the constructor's `Req` picks
249 up `Sync`, the planner has a runner to call.
250
251 `.make()` accepts either a direct runner or an init Effect.
252
253 ## In the plan
254
255 In the terraform-style preview, Actions get their own
256 symbol — `λ` for a run, `·` for a skip:
257
258 ```text
259 Plan: 1 to create | 1 to update | 1 to run
260
261 ~ Api (Cloudflare.Worker)
262 + BucketA (Cloudflare.R2.Bucket)
263 λ AnnounceDeploy (AnnounceDeploy) [action]
264 · DbMigrate (DbMigrate) [action]
265 ```
266
267 The `[action]` tag distinguishes them from resources without
268 moving them out of the namespace tree — they sort
269 alongside the resources they're related to. During apply
270 `λ` swaps in a spinner; on success it switches to `✓` (cyan).
271
272 ## What this is not
273
274 An Action is not a runtime function. To run code from inside
275 a deployed Worker or Lambda, use a
276 [Platform](/infrastructure-as-effects/runtime). Actions run at deploy time,
277 once per input change, never on a request.
278
279 An Action is not a Resource. It has no `read`, no
280 `reconcile`, no drift detection. If you need lifecycle
281 management of a cloud entity, model that entity as a
282 Resource.
283
284 An Action is not idempotent for free. The engine guarantees
285 the body runs only when the input hash changes, but the
286 body itself has to be safe to retry if the run is
287 interrupted before it commits — its `running` state is
288 persisted, the side effect inside the body is your
289 responsibility.
290
291 ## Where this fits
292
293 Resources are the right shape when you're modeling a cloud
294 entity that needs to converge to a desired state. Actions
295 are the right shape for everything else that wants to
296 participate in the same graph — deploy-time scripts,
297 notifications, one-shot migrations, derived values
298 computed from resource outputs.
299
300 The same graph means: upstream Outputs flow in as typed
301 inputs, downstream resources can read outputs back, cycles
302 are detected at plan time, `--force` works, removal drops
303 state cleanly. The same graph means: Actions don't sit
304 alongside your stack — they live *inside* it, one node
305 among the others.
306
307 ## Where to go next
308
309 - [Concepts › Action](/infrastructure-as-code/action) — the full reference
310 for the inline, init-effect, and tagged forms, plus the
311 state model and lifecycle table.
312 - [`packages/alchemy/src/Action.ts`](https://github.com/alchemy-run/alchemy/blob/main/packages/alchemy/src/Action.ts)
313 — the source. Around 270 lines including JSDoc.
314 - [Bindings — one line, two phases](/blog/2026-04-30-bindings) —
315 the deploy-vs-runtime split that Actions also follow at
316 the type level (Stack `Req` picks up the runner Tag, the
317 runtime bundle excludes deploy-time code).
318 - [Circular references, without the deadlock](/blog/2026-04-25-circular-references) —
319 the cycle-aware planner that Actions participate in too,
320 including the `readyStable` signal that keeps action
321 bodies off of precreate stubs.