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

main
mdx 243 lines 6.85 KB
Raw
1 ---
2 title: "Part 1: Your First Project"
3 description: Install Alchemy, create a Stack with a Railway Project, and deploy it.
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/railway@latest effect @effect/platform-bun @effect/platform-node`;
12
13 Install Alchemy and Effect, create a Stack with a Railway Project, and
14 deploy it. A Project is the parent for Services, Environments,
15 Variables, and disks.
16
17 ## Prerequisites
18
19 - [Bun](https://bun.sh) or Node.js 22+
20 - A Railway workspace and an account API token — see
21 [Setup](/railway/setup) if you haven't created those yet
22
23 :::note[Costs]
24 A Railway Project is free. Compute (Services) is billed starting in
25 [Part 2](/railway/tutorial/part-2). `alchemy destroy` tears
26 everything down when you're done.
27 :::
28
29 ## Create a project
30
31 Start with an empty directory and initialize a `package.json`:
32
33 <PackageManagers init dir="my-app" />
34
35 ## Install dependencies
36
37 Install `alchemy@latest`, `@alchemy.run/railway`, and `effect`:
38
39 <PackageManagers add={pkgs} />
40
41 ## Create the Stack
42
43 Every Alchemy program starts with a `Stack` — a collection of
44 Resources managed by Providers with state tracked between deploys.
45
46 Create an `alchemy.run.ts` file:
47
48 ```typescript
49 // alchemy.run.ts
50 import * as Alchemy from "alchemy";
51 import * as Effect from "effect/Effect";
52 import * as Layer from "effect/Layer";
53
54 export default Alchemy.Stack(
55 "MyApp",
56 {
57 // @error: ts(2345) Argument of type '{ providers: Layer.Layer<never, never, never>; }' is not assignable to parameter of type 'StackProps<never>'.
58 // @error: Property 'state' is missing in type '{ providers: Layer.Layer<never, never, never>; }' but required in type 'StackProps<never>'.
59 providers: Layer.empty,
60 },
61 Effect.gen(function* () {
62 // we'll add resources here next
63 }),
64 );
65 ```
66
67 TypeScript is unhappy: the `state` property is required. Every Stack
68 needs a **state store** so Alchemy can persist resource state between
69 deploys and compute diffs against your infrastructure.
70
71 ## Configure state
72
73 Railway has no state backend of its own, so we'll keep state on disk
74 with `Alchemy.localState()` — it writes to `.alchemy/` next to your
75 code, no setup required:
76
77 ```diff lang="typescript"
78 // alchemy.run.ts
79 import * as Alchemy from "alchemy";
80 import * as Effect from "effect/Effect";
81 import * as Layer from "effect/Layer";
82
83 export default Alchemy.Stack(
84 "MyApp",
85 {
86 providers: Layer.empty,
87 + state: Alchemy.localState(),
88 },
89 Effect.gen(function* () {
90 // we'll add resources here next
91 }),
92 );
93 ```
94
95 :::note[Other state stores]
96 Local state is perfect for a solo project. When you need state your
97 team and CI can share, swap in `Cloudflare.state()` or `AWS.state()`
98 — see [State Store](/state-store).
99 :::
100
101 ## Add a Project
102
103 Resources represent cloud infrastructure. Each resource is
104 `yield*`-ed inside the Stack's Effect generator.
105
106 Let's declare a Railway Project and observe the type error:
107
108 ```diff lang="typescript"
109 // alchemy.run.ts
110 import * as Alchemy from "alchemy";
111 +import * as Railway from "@alchemy.run/railway";
112 import * as Effect from "effect/Effect";
113 import * as Layer from "effect/Layer";
114
115 export default Alchemy.Stack(
116 "MyApp",
117 {
118 providers: Layer.empty,
119 // @error: ts(2322) Type 'Layer<never, never, never>' is not assignable to type 'Layer<NoInfer<Providers>, never, StackServices>'.
120 // @error: Type 'Providers' is not assignable to type 'never'.
121 state: Alchemy.localState(),
122 },
123 Effect.gen(function* () {
124 + const site = yield* Railway.Project("Site");
125 }),
126 );
127 ```
128
129 Omit `name` and Alchemy generates a unique, DNS-safe Project name
130 (max 32 characters, leading letter). The workspace defaults to
131 whatever workspace your token belongs to. A production environment
132 is created with the Project.
133
134 TypeScript is telling us that `Layer.empty` doesn't provide
135 `Railway.Providers` — the layer required by `Project`.
136
137 ## Fix the Providers
138
139 Replace `Layer.empty` with `Railway.providers()` to resolve the type
140 error:
141
142 ```diff lang="typescript"
143 // alchemy.run.ts
144 import * as Alchemy from "alchemy";
145 import * as Railway from "@alchemy.run/railway";
146 import * as Effect from "effect/Effect";
147 -import * as Layer from "effect/Layer";
148
149 export default Alchemy.Stack(
150 "MyApp",
151 {
152 + providers: Railway.providers(),
153 state: Alchemy.localState(),
154 },
155 Effect.gen(function* () {
156 const site = yield* Railway.Project("Site");
157 }),
158 );
159 ```
160
161 Now the program type-checks. The providers layer tells Alchemy how to
162 talk to the Railway GraphQL API, and the type system ensures you
163 never forget to wire it up.
164
165 ## Return Stack outputs
166
167 Stack outputs let you see important values after a deploy. Return an
168 object from the generator to expose the Project's name, id, and
169 dashboard URL:
170
171 ```typescript
172 Effect.gen(function* () {
173 const site = yield* Railway.Project("Site");
174
175 return {
176 name: site.name,
177 projectId: site.projectId,
178 url: site.url,
179 };
180 }),
181 ```
182
183 `url` is `https://railway.com/project/{projectId}`. Nothing is
184 listening on the public internet yet — that's
185 [Part 2](/railway/tutorial/part-2).
186
187 ## Deploy
188
189 Run `alchemy deploy` to create the Project:
190
191 <PackageManagers run="alchemy deploy" />
192
193 The first time you deploy, Alchemy prompts for Railway credentials —
194 paste the account token you generated in [Setup](/railway/setup).
195 The token is verified and saved to your **`default`**
196 [profile](/environments/profiles), so you won't be asked again.
197
198 <Terminal content={`[u]Plan[/u]: [g]1 to create[/g]
199
200 [g]+[/g] [b]Site[/b] [d](Railway.Project)[/d]
201
202 Proceed?
203 ◉ Yes ○ No
204 [g]✓[/g] [b]Site[/b] [d](Railway.Project)[/d] [g]created[/g]
205 {
206 [s2]name: "myapp-site-dev-a1b2c3d4",
207 [s2]projectId: "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
208 [s2]url: "https://railway.com/project/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
209 }`} />
210
211 Alchemy shows a plan, asks for confirmation, creates the Project, and
212 prints the stack outputs.
213
214 ## Verify it worked
215
216 The Project is listed in your workspace in the
217 [Railway dashboard](https://railway.com/dashboard). Run
218 `alchemy deploy` again. Because nothing changed, the Project shows
219 as a no-op:
220
221 <Terminal content={`[u]Plan[/u]: [d]no changes[/d]
222
223 {
224 [s2]name: "myapp-site-dev-a1b2c3d4",
225 [s2]projectId: "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
226 [s2]url: "https://railway.com/project/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
227 }`} />
228
229 This is the core loop — declare resources in code, deploy, and
230 Alchemy figures out what changed.
231
232 ## Recap
233
234 You now have:
235
236 - An `alchemy.run.ts` with a Stack and a Railway Project
237 - A live Project in your workspace with a generated unique name
238 - A production environment created with the Project
239 - Stack outputs showing `name`, `projectId`, and the dashboard URL
240
241 In [Part 2](/railway/tutorial/part-2), you'll deploy code to this
242 Project — a `Railway.Service` that bundles an Effect HTTP handler
243 into a container.