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

main
mdx 309 lines 8.67 KB
Raw
1 ---
2 title: "Part 1: Your First Service"
3 description: Install Alchemy, create a Stack, and deploy an Effect HTTP Service to Fly on its own fly.dev hostname.
4 sidebar:
5 order: 1
6 ---
7
8 import Terminal from "../../../../components/Terminal.astro";
9 import PackageManagers from "../../../../components/PackageManagers.astro";
10
11 export const pkgs = `alchemy@latest @alchemy.run/fly@latest effect @effect/platform-bun @effect/platform-node`;
12
13 Install Alchemy and Effect, create a Stack, and deploy a
14 `Fly.Service`: an Effect program running in a Fly Machine. The
15 Service creates its own Fly App, so it gets its own public
16 `https://{name}.fly.dev` URL. Alchemy bundles it, builds a Docker
17 image, and pushes it to `registry.fly.io`. No Dockerfile. No
18 `fly.toml`.
19
20 ## Prerequisites
21
22 - [Bun](https://bun.sh) or Node.js 22+
23 - A Fly organization and an API token — see [Setup](/fly/setup) if
24 you haven't created those yet
25 - Docker running locally. Alchemy builds `linux/amd64` images and
26 pushes them with an App deploy token.
27
28 :::note[Costs]
29 The Service's App and addresses are free. Its Machine (shared-cpu,
30 256 MB) is billed by the second. `alchemy destroy` tears everything
31 down when you're done.
32 :::
33
34 ## Create a project
35
36 Start with an empty directory and initialize a `package.json`:
37
38 <PackageManagers init dir="my-app" />
39
40 ## Install dependencies
41
42 Install `alchemy@latest`, `@alchemy.run/fly`, and `effect`:
43
44 <PackageManagers add={pkgs} />
45
46 ## Create the Stack
47
48 Every Alchemy program starts with a `Stack` — a collection of
49 Resources managed by Providers with state tracked between deploys.
50
51 Create an `alchemy.run.ts` file:
52
53 ```typescript
54 // alchemy.run.ts
55 import * as Alchemy from "alchemy";
56 import * as Effect from "effect/Effect";
57 import * as Layer from "effect/Layer";
58
59 export default Alchemy.Stack(
60 "MyApp",
61 {
62 // @error: ts(2345) Argument of type '{ providers: Layer.Layer<never, never, never>; }' is not assignable to parameter of type 'StackProps<never>'.
63 // @error: Property 'state' is missing in type '{ providers: Layer.Layer<never, never, never>; }' but required in type 'StackProps<never>'.
64 providers: Layer.empty,
65 },
66 Effect.gen(function* () {
67 // we'll add resources here next
68 }),
69 );
70 ```
71
72 TypeScript is unhappy: the `state` property is required. Every Stack
73 needs a **state store** so Alchemy can persist resource state between
74 deploys and compute diffs against your infrastructure.
75
76 ## Configure state
77
78 Fly has no state backend of its own, so we'll keep state on disk
79 with `Alchemy.localState()` — it writes to `.alchemy/` next to your
80 code, no setup required:
81
82 ```diff lang="typescript"
83 // alchemy.run.ts
84 import * as Alchemy from "alchemy";
85 import * as Effect from "effect/Effect";
86 import * as Layer from "effect/Layer";
87
88 export default Alchemy.Stack(
89 "MyApp",
90 {
91 providers: Layer.empty,
92 + state: Alchemy.localState(),
93 },
94 Effect.gen(function* () {
95 // we'll add resources here next
96 }),
97 );
98 ```
99
100 :::note[Other state stores]
101 Local state is perfect for a solo project. When you need state your
102 team and CI can share, swap in `Cloudflare.state()` or `AWS.state()`
103 — see [State Store](/state-store).
104 :::
105
106 ## Create the Service file
107
108 A Service in Alchemy is a class — it has both an infrastructure
109 definition and a runtime implementation expressed as an Effect.
110 Create `src/api.ts` with the smallest possible declaration:
111
112 ```typescript
113 // src/api.ts
114 import * as Fly from "@alchemy.run/fly";
115 import * as Effect from "effect/Effect";
116
117 export default class Api extends Fly.Service<Api>()(
118 "Api",
119 { main: import.meta.url },
120 Effect.gen(function* () {
121 return {};
122 }),
123 ) {}
124 ```
125
126 The `<Api>` type argument plus the empty `()` is a one-time bit of
127 ceremony — it lets TypeScript reason about `Api` as a typed handle.
128 `main: import.meta.url` tells Alchemy this same file is the bundle
129 entrypoint. The Service creates and manages its own Fly App; you
130 don't declare one.
131
132 ## Serve HTTP with `fetch`
133
134 Add a `fetch` field — Alchemy treats anything returned from the
135 `Effect.gen` block as the runtime API, and `fetch` specifically is
136 wired to an HTTP server listening on the Service's port:
137
138 ```diff lang="typescript"
139 // src/api.ts
140 import * as Fly from "@alchemy.run/fly";
141 import * as Effect from "effect/Effect";
142 +import * as HttpServerResponse from "effect/http/HttpServerResponse";
143
144 export default class Api extends Fly.Service<Api>()(
145 "Api",
146 { main: import.meta.url },
147 Effect.gen(function* () {
148 - return {};
149 + return {
150 + fetch: Effect.succeed(HttpServerResponse.text("Hello from Fly!")),
151 + };
152 }),
153 ) {}
154 ```
155
156 `HttpServerResponse` is the same `effect/http` API used on
157 every other Alchemy runtime — the handler you write here would run
158 unchanged on Cloudflare Workers or AWS Lambda.
159
160 :::note
161 Notice the "Effect returning an Effect" pattern. The outer generator
162 is the **Construction phase** — it runs at deploy time and at process
163 startup. The inner `fetch` generator is the **Runtime phase** — it
164 runs per request.
165 :::
166
167 ## Add the Service to the Stack
168
169 The `Api` class is just a typed identifier — yielding it inside the
170 Stack's Effect is what registers the resource. Yield it and observe
171 the type error:
172
173 ```diff lang="typescript"
174 // alchemy.run.ts
175 import * as Alchemy from "alchemy";
176 import * as Effect from "effect/Effect";
177 import * as Layer from "effect/Layer";
178 +import Api from "./src/api.ts";
179
180 export default Alchemy.Stack(
181 "MyApp",
182 {
183 providers: Layer.empty,
184 // @error: ts(2322) Type 'Layer<never, never, never>' is not assignable to type 'Layer<NoInfer<Providers>, never, StackServices>'.
185 // @error: Type 'Providers' is not assignable to type 'never'.
186 state: Alchemy.localState(),
187 },
188 Effect.gen(function* () {
189 - // we'll add resources here next
190 + const api = yield* Api;
191 }),
192 );
193 ```
194
195 TypeScript is telling us that `Layer.empty` doesn't provide
196 `Fly.Providers` — the layer required by `Service`.
197
198 ## Fix the Providers
199
200 Replace `Layer.empty` with `Fly.providers()` to resolve the type
201 error:
202
203 ```diff lang="typescript"
204 // alchemy.run.ts
205 import * as Alchemy from "alchemy";
206 +import * as Fly from "@alchemy.run/fly";
207 import * as Effect from "effect/Effect";
208 -import * as Layer from "effect/Layer";
209 import Api from "./src/api.ts";
210
211 export default Alchemy.Stack(
212 "MyApp",
213 {
214 + providers: Fly.providers(),
215 state: Alchemy.localState(),
216 },
217 Effect.gen(function* () {
218 const api = yield* Api;
219 }),
220 );
221 ```
222
223 Now the program type-checks. The providers layer tells Alchemy how to
224 talk to the Fly Machines API, and the type system ensures you never
225 forget to wire it up.
226
227 ## Return Stack outputs
228
229 Stack outputs let you see important values after a deploy. Return the
230 Service's App name and public URL:
231
232 ```diff lang="typescript"
233 Effect.gen(function* () {
234 const api = yield* Api;
235 +
236 + return {
237 + appName: api.appName,
238 + url: api.url,
239 + };
240 }),
241 ```
242
243 Omit `name` and Alchemy generates a globally unique, DNS-safe App
244 name from the stack, stage, and logical ID. A Service is public by
245 default: Alchemy allocates a free shared IPv4 and IPv6 on its App,
246 and `url` is `https://{appName}.fly.dev`.
247
248 ## Deploy
249
250 Run `alchemy deploy`:
251
252 <PackageManagers run="alchemy deploy" />
253
254 The first time you deploy, Alchemy prompts for Fly credentials —
255 paste the API token you generated in [Setup](/fly/setup). The token
256 is verified and saved to your **`default`**
257 [profile](/environments/profiles), so you won't be asked again.
258
259 <Terminal content={`[u]Plan[/u]: [g]1 to create[/g]
260
261 [g]+[/g] [b]Api[/b] [d](Fly.Service)[/d]
262
263 Proceed?
264 ◉ Yes ○ No
265 [g]✓[/g] [b]Api[/b] [d](Fly.Service)[/d] [g]created[/g]
266 {
267 [s2]appName: "myapp-api-dev-a1b2c3d4",
268 [s2]url: "https://myapp-api-dev-a1b2c3d4.fly.dev",
269 }`} />
270
271 Alchemy created the Service's App and its addresses, bundled
272 `src/api.ts` with Rolldown, built a `linux/amd64` image, and pushed
273 it to `registry.fly.io/{app}:{id}-{hash}`. It then created a Machine
274 in `iad`, waited until it was `started`, and pointed the Fly proxy
275 at the Service's port.
276
277 ## Try it out
278
279 ```sh
280 curl https://myapp-api-dev-a1b2c3d4.fly.dev
281 # → Hello from Fly!
282 ```
283
284 ## Verify it worked
285
286 The App is listed in your org in the
287 [Fly dashboard](https://fly.io/dashboard). Run `alchemy deploy`
288 again. Because nothing changed, the Service shows as a no-op:
289
290 <Terminal content={`[u]Plan[/u]: [d]no changes[/d]
291
292 {
293 [s2]appName: "myapp-api-dev-a1b2c3d4",
294 [s2]url: "https://myapp-api-dev-a1b2c3d4.fly.dev",
295 }`} />
296
297 This is the core loop — declare resources in code, deploy, and
298 Alchemy figures out what changed.
299
300 ## Recap
301
302 You now have:
303
304 - An `alchemy.run.ts` with a Stack and a `Fly.Service`
305 - A live Service in its own App with a generated globally unique name
306 - A public `https://{appName}.fly.dev` URL answering HTTP
307
308 In [Part 2](/fly/tutorial/part-2), you'll pin the Service's region
309 and port, add a health route, and ship a code change.