@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 246 lines 6.92 KB
Raw
1 ---
2 title: File layout
3 description: How to organize an Alchemy project — one file per Resource or Layer, group Resources that travel together by concern, and keep alchemy.run.ts as the composition root.
4 ---
5
6 A typical alchemy app ([`examples/cloudflare-neon-drizzle`](https://github.com/alchemy-run/alchemy/tree/main/examples/cloudflare-neon-drizzle)):
7
8 ```sh
9 .
10 ├── alchemy.run.ts # composition root — export default the Stack
11 ├── src/
12 │ ├── Api.ts # the Worker (Function/Server + its runtime code)
13 │ ├── Db.ts # Database + Branch + Hyperdrive — one concern
14 │ └── schema.ts # Drizzle schema shared by Db.ts and Api.ts
15 └── test/
16 └── integ.test.ts # deploys the Stack, hits the live URL
17 ```
18
19 Three rules produce this shape: one file per Resource or Layer,
20 group Resources that travel together, and keep `alchemy.run.ts`
21 as the composition root. This page walks a project from one file
22 to that shape.
23
24 ## Start with one file
25
26 Everything in `alchemy.run.ts` is a perfectly good starting
27 point:
28
29 ```typescript
30 // alchemy.run.ts
31 import * as Alchemy from "alchemy";
32 import * as Cloudflare from "@alchemy.run/cloudflare";
33 import * as Effect from "effect/Effect";
34
35 export const DB = Cloudflare.D1.Database("DB");
36
37 export const Bucket = Cloudflare.R2.Bucket("Bucket");
38
39 export const Worker = Cloudflare.Worker("Worker", {
40 main: "./src/worker.ts",
41 env: { DB, Bucket },
42 });
43
44 export default Alchemy.Stack(
45 "CloudflareWorker",
46 {
47 providers: Cloudflare.providers(),
48 state: Cloudflare.state(),
49 },
50 Effect.gen(function* () {
51 const worker = yield* Worker;
52 return { url: worker.url.as<string>() };
53 }),
54 );
55 ```
56
57 This is fine until the file accumulates runtime code, stage
58 logic, and a dozen Resources — then split.
59
60 ## One file per Resource
61
62 A Resource declaration is a value; give it its own module:
63
64 ```typescript
65 // src/Photos.ts
66 import * as Cloudflare from "@alchemy.run/cloudflare";
67
68 export const Photos = Cloudflare.R2.Bucket("Photos");
69 ```
70
71 A declaration is inert until a Stack yields it — importing this
72 file deploys nothing.
73
74 Workers get the same treatment, with `main: import.meta.url`
75 making the file its own entrypoint:
76
77 ```typescript
78 // src/Api.ts
79 import * as Cloudflare from "@alchemy.run/cloudflare";
80 import * as Effect from "effect/Effect";
81
82 export default class Api extends Cloudflare.Worker<Api>()(
83 "Api",
84 { main: import.meta.url },
85 Effect.gen(function* () {
86 return {
87 fetch: Effect.gen(function* () {
88 // handle requests
89 }),
90 };
91 }),
92 ) {}
93 ```
94
95 The Worker's declaration and its runtime code live in one file —
96 there is no separate `wrangler.toml` pointing at a script.
97
98 Layers follow the same rule — the `SandboxLive` Layer lives in
99 `src/Sandbox.ts` (see
100 [Layers](/infrastructure-as-effects/layers)).
101
102 ## Group by concern
103
104 Resources that change together share a file:
105
106 ```typescript
107 // src/Db.ts
108 import * as Drizzle from "@alchemy.run/drizzle";
109 import * as Neon from "@alchemy.run/neon";
110 import * as Effect from "effect/Effect";
111
112 export const NeonDb = Effect.gen(function* () {
113 const schema = yield* Drizzle.Schema("app-schema", {
114 schema: "./src/schema.ts",
115 out: "./migrations",
116 });
117
118 const project = yield* Neon.Project("app-db", {
119 region: "aws-us-east-1",
120 });
121
122 const branch = yield* Neon.Branch("app-branch", {
123 project,
124 migrations: schema,
125 });
126
127 return { project, branch, schema };
128 });
129 ```
130
131 A migration touches all three — Schema regenerates the SQL,
132 Branch applies it — so they share a file. The heuristic: group
133 Resources when they share a lifecycle.
134
135 ## Wrap units in Effects, not in the Stack
136
137 `NeonDb` above is an exported `Effect.gen` — a unit of
138 composition anything can build on:
139
140 ```typescript
141 // src/Db.ts
142 export const Hyperdrive = Effect.gen(function* () {
143 const { branch } = yield* NeonDb;
144 return yield* Cloudflare.Hyperdrive.Connection("app-hyperdrive", {
145 origin: branch.origin,
146 });
147 });
148 ```
149
150 Both `Hyperdrive` and `alchemy.run.ts` yield `NeonDb`, but each
151 Resource is memoized by its logical ID — the database is
152 provisioned once no matter how many units yield it.
153
154 ## Stage-conditional config
155
156 When a Resource's props differ by stage, read the stage where the
157 Resource is declared:
158
159 ```typescript
160 const { stage } = yield* Alchemy.Stack;
161
162 const sandbox = yield* Cloudflare.Container("Sandbox", {
163 instanceType: stage === "prod" ? "standard-1" : "dev",
164 });
165 ```
166
167 The decision lives next to the Resource it affects, not in
168 `alchemy.run.ts`. The most common case — `pr-*` stages borrowing
169 staging's database via `.ref` — is covered in
170 [References](/infrastructure-as-code/references).
171
172 ## alchemy.run.ts is the composition root
173
174 With the units in `src/`, the root file shrinks to wiring:
175
176 ```typescript
177 // alchemy.run.ts
178 import * as Alchemy from "alchemy";
179 import * as Cloudflare from "@alchemy.run/cloudflare";
180 import * as Drizzle from "@alchemy.run/drizzle";
181 import * as Neon from "@alchemy.run/neon";
182 import * as Effect from "effect/Effect";
183 import * as Layer from "effect/Layer";
184
185 import Api from "./src/Api.ts";
186 import { Hyperdrive, NeonDb } from "./src/Db.ts";
187
188 export default Alchemy.Stack(
189 "CloudflareNeonDrizzleExample",
190 {
191 providers: Layer.mergeAll(
192 Cloudflare.providers(),
193 Drizzle.providers(),
194 Neon.providers(),
195 ),
196 state: Alchemy.localState(),
197 },
198 Effect.gen(function* () {
199 const { branch } = yield* NeonDb;
200 const hd = yield* Hyperdrive;
201 const api = yield* Api;
202
203 return {
204 url: api.url.as<string>(),
205 branchId: branch.branchId,
206 hyperdriveId: hd.hyperdriveId,
207 };
208 }),
209 );
210 ```
211
212 It has four jobs: name the Stack, merge Providers, pick a State
213 Store, wire units into outputs. The CLI discovers
214 `alchemy.run.ts` at the project root automatically; pass a path
215 to override (`alchemy deploy --config ./infra/app.ts`).
216
217 If `alchemy.run.ts` is growing, something is missing a home in
218 `src/`.
219
220 ## The shape
221
222 ```
223 .
224 ├── alchemy.run.ts # composition root — Stack, Providers, State Store, outputs
225 ├── .alchemy/ # local state — gitignore it
226 └── src/
227 ├── Api.ts # Worker — declaration + runtime code
228 ├── Db.ts # database unit — Schema + Project + Branch + Hyperdrive
229 ├── Photos.ts # one-line Resource
230 ├── Sandbox.ts # Container Layer
231 └── schema.ts # plain application code (Drizzle schema)
232 ```
233
234 Tests mirror the tree under `test/`; the tutorial builds this
235 shape step by step ([Part 2](/cloudflare/tutorial/part-2)).
236
237 ## Where next
238
239 - [Monorepo](/project-structure/monorepo) — the workspace-level version of
240 this question: one Stack or one per package.
241 - [References](/infrastructure-as-code/references) — when the split
242 crosses Stack boundaries.
243 - [Layers](/infrastructure-as-effects/layers) — promote
244 a multi-Resource unit into a swappable Layer.
245 - [Stacks](/infrastructure-as-code/stack) — the Stack service, stages, and
246 outputs used by the composition root.