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

main
mdx 263 lines 7.61 KB
Raw
1 ---
2 title: "Part 1: Your First Stack"
3 description: Install Alchemy, create a Stack with a Cloudflare R2 Bucket, and deploy it.
4 sidebar:
5 order: 1
6 ---
7
8 import Terminal from "../../../../components/Terminal.astro";
9 import StateStoreBootstrap from "../../../../components/marketing-islands/StateStoreBootstrap.tsx";
10 import PackageManagers from "../../../../components/PackageManagers.astro";
11
12 export const pkgs = `alchemy@latest @alchemy.run/cloudflare@latest effect @effect/platform-bun @effect/platform-node`;
13
14 In this first part you'll install Alchemy and Effect, create a Stack
15 with a Cloudflare R2 Bucket, and deploy it, all in under five minutes.
16
17 :::tip
18 Already deployed the Bucket from [Getting started](/getting-started)?
19 That was this part. Skip to [Part 2](/cloudflare/tutorial/part-2).
20 :::
21
22 ## Prerequisites
23
24 - [Bun](https://bun.sh) or Node.js 22+
25 - A [Cloudflare](https://dash.cloudflare.com/sign-up) account
26
27 ## Create a project
28
29 Start with an empty directory and initialize a `package.json`:
30
31 <PackageManagers init dir="my-app" />
32
33 ## Install dependencies
34
35 Install `alchemy@latest`, `@alchemy.run/cloudflare`, and `effect`:
36
37 <PackageManagers add={pkgs} />
38
39 ## Create the Stack
40
41 Every Alchemy program starts with a `Stack` — a collection of
42 Resources managed by Providers with state tracked between deploys.
43
44 Create an `alchemy.run.ts` file:
45
46 ```typescript
47 // alchemy.run.ts
48 import * as Alchemy from "alchemy";
49 import * as Effect from "effect/Effect";
50 import * as Layer from "effect/Layer";
51
52 export default Alchemy.Stack(
53 "MyApp",
54 {
55 // @error: ts(2345) Argument of type '{ providers: Layer.Layer<never, never, never>; }' is not assignable to parameter of type 'StackProps<never>'.
56 // @error: Property 'state' is missing in type '{ providers: Layer.Layer<never, never, never>; }' but required in type 'StackProps<never>'.
57 providers: Layer.empty,
58 },
59 Effect.gen(function* () {
60 // we'll add resources here next
61 }),
62 );
63 ```
64
65 TypeScript is unhappy: the `state` property is required. Every Stack
66 needs a **state store** so Alchemy can persist resource state between
67 deploys and compute diffs against your infrastructure.
68
69 ## Configure state
70
71 For this tutorial we'll use `Cloudflare.state()`, which persists state
72 in a Cloudflare-hosted Worker backed by a Durable Object:
73
74 ```diff lang="typescript"
75 // alchemy.run.ts
76 import * as Alchemy from "alchemy";
77 +import * as Cloudflare from "@alchemy.run/cloudflare";
78 import * as Effect from "effect/Effect";
79 import * as Layer from "effect/Layer";
80
81 export default Alchemy.Stack(
82 "MyApp",
83 {
84 providers: Layer.empty,
85 + state: Cloudflare.state(),
86 },
87 Effect.gen(function* () {
88 // we'll add resources here next
89 }),
90 );
91 ```
92
93 The first time you run `alchemy deploy`, `plan`, or `dev`, Alchemy
94 will prompt for permission and bootstrap the state-store Worker into
95 your Cloudflare account. It looks like this:
96
97 <StateStoreBootstrap client:visible />
98
99 This is a one-time event — the state-store Worker, its Durable
100 Object, and the Secrets Store entries holding its auth token and
101 encryption key are reused across every stack and stage on this
102 Cloudflare account. See [State Store](/state-store) for
103 the full picture.
104
105 :::note[Other state stores]
106 Don't want to deploy a Worker just for state? Swap `Cloudflare.state()`
107 for `State.localState()` from `alchemy/State` to keep state on disk
108 under `.alchemy/`, or [write your own](/state-store).
109 :::
110
111 ## Add a Resource
112
113 Resources represent cloud infrastructure — buckets, queues, functions,
114 databases, and so on. Each resource is `yield*`-ed inside the Stack's
115 Effect generator.
116
117 Let's add a Cloudflare R2 Bucket to our Stack and observe the type error:
118
119 ```diff lang="typescript"
120 // alchemy.run.ts
121 import * as Alchemy from "alchemy";
122 import * as Cloudflare from "@alchemy.run/cloudflare";
123 import * as Effect from "effect/Effect";
124 import * as Layer from "effect/Layer";
125
126 export default Alchemy.Stack(
127 "MyApp",
128 {
129 providers: Layer.empty,
130 // @error: ts(2322) Type 'Layer<never, never, never>' is not assignable to type 'Layer<NoInfer<Providers>, never, StackServices>'.
131 // @error: Type 'Providers' is not assignable to type 'never'.
132 state: Cloudflare.state(),
133 },
134 Effect.gen(function* () {
135 + const bucket = yield* Cloudflare.R2.Bucket("Bucket");
136 }),
137 );
138 ```
139
140 TypeScript is telling us that `Layer.empty` doesn't provide
141 `Cloudflare.Providers` — the layer required by `Bucket`.
142
143 ## Fix the Providers
144
145 Replace `Layer.empty` with `Cloudflare.providers()` to resolve the
146 type error:
147
148 ```diff lang="typescript"
149 // alchemy.run.ts
150 import * as Alchemy from "alchemy";
151 import * as Cloudflare from "@alchemy.run/cloudflare";
152 import * as Effect from "effect/Effect";
153 -import * as Layer from "effect/Layer";
154
155 export default Alchemy.Stack(
156 "MyApp",
157 {
158 + providers: Cloudflare.providers(),
159 state: Cloudflare.state(),
160 },
161 Effect.gen(function* () {
162 const bucket = yield* Cloudflare.R2.Bucket("Bucket");
163 }),
164 );
165 ```
166
167 Now the program type-checks. The providers layer tells Alchemy how to
168 talk to Cloudflare's APIs, and the type system ensures you never
169 forget to wire it up.
170
171 ## Return Stack outputs
172
173 Stack outputs let you see important values after a deploy. Return an
174 object from the generator to expose them:
175
176 ```diff lang="typescript"
177 // alchemy.run.ts
178 import * as Alchemy from "alchemy";
179 import * as Cloudflare from "@alchemy.run/cloudflare";
180 import * as Effect from "effect/Effect";
181
182 export default Alchemy.Stack(
183 "MyApp",
184 {
185 providers: Cloudflare.providers(),
186 state: Cloudflare.state(),
187 },
188 Effect.gen(function* () {
189 const bucket = yield* Cloudflare.R2.Bucket("Bucket");
190
191 + return {
192 + bucketName: bucket.bucketName,
193 };
194 }),
195 );
196 ```
197
198 ## Deploy
199
200 Run `alchemy deploy` to create the Bucket on Cloudflare:
201
202 <PackageManagers run="alchemy deploy" />
203
204 If you haven't connected Cloudflare yet, the deploy fails with the exact
205 `alchemy profile edit` command to run. Use the `profile` command to sign in
206 and save credentials to your
207 **`default`** [profile](/environments/profiles) at
208 `~/.alchemy/profiles.json`. For Cloudflare you can sign in with
209 OAuth in the browser or paste an API token — no environment
210 variables or `wrangler login` required.
211
212 :::tip
213 To re-run the credential prompt later (e.g. to switch from OAuth to
214 an API token), use `alchemy profile edit --reconfigure Cloudflare`.
215 For a separate profile, run `alchemy profile create prod` followed by
216 `alchemy profile edit --profile prod`.
217 :::
218
219 <Terminal content={`[u]Plan[/u]: [g]1 to create[/g]
220 [g]+[/g] [b]Bucket[/b] [d](Cloudflare.R2.Bucket)[/d]
221
222 Proceed?
223 ◉ Yes ○ No
224 [g]✓[/g] [b]Bucket[/b] [d](Cloudflare.R2.Bucket)[/d] [g]created[/g]
225 {
226 [s2]bucketName: "myapp-bucket-a1b2c3d4e5",
227 }`} />
228
229 Alchemy shows a plan, asks for confirmation, creates the resource,
230 and prints the stack outputs. Your bucket is live on Cloudflare.
231
232 :::tip
233 By convention, Alchemy looks for `alchemy.run.ts` at the root of your
234 project. You can specify a different file with
235 `alchemy deploy --config <file>`.
236 :::
237
238 ## Verify it worked
239
240 Your newly created R2 bucket will be listed on the [Cloudflare R2 Object Storage Dashboard](https://dash.cloudflare.com/?to=/:account/r2/overview).
241
242 Run `alchemy deploy` again. Because nothing changed, the bucket shows
243 as a no-op:
244
245 <Terminal content={`[u]Plan[/u]: [d]no changes[/d]
246
247 {
248 [s2]bucketName: "myapp-bucket-a1b2c3d4e5",
249 }`} />
250
251 This is the core loop — declare resources in code, deploy, and
252 Alchemy figures out what changed.
253
254 ## Recap
255
256 You now have:
257
258 - An `alchemy.run.ts` with a Stack and a Cloudflare R2 Bucket
259 - A live bucket deployed to your Cloudflare account
260 - Stack outputs showing the bucket name
261
262 In [Part 2](/cloudflare/tutorial/part-2), you'll add a Cloudflare Worker that
263 uses this bucket to serve HTTP requests.