@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 214 lines 6.05 KB
Raw
1 ---
2 title: "Part 1: Your First Stack"
3 description: Install Alchemy, create a Stack with an AWS S3 Bucket, 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/aws@latest effect @effect/platform-bun @effect/platform-node`;
12
13 In this first part you'll install Alchemy and Effect, create a Stack
14 with an AWS S3 Bucket, and deploy it — all in under five minutes.
15
16 ## Prerequisites
17
18 - [Bun](https://bun.sh) or Node.js 24.11.1+
19 - An AWS account and an IAM identity with permission to create the
20 resources you plan to deploy
21
22 ## Create a project
23
24 Start with an empty directory and initialize a `package.json`:
25
26 <PackageManagers init dir="my-app" />
27
28 ## Install dependencies
29
30 Install `alchemy@latest`, `@alchemy.run/aws`, and `effect`:
31
32 <PackageManagers add={pkgs} />
33
34 ## Create the Stack
35
36 Every Alchemy program starts with a `Stack` — a collection of
37 Resources managed by Providers with state tracked between deploys.
38
39 Create an `alchemy.run.ts` file:
40
41 ```typescript
42 // alchemy.run.ts
43 import * as Alchemy from "alchemy";
44 import * as AWS from "@alchemy.run/aws";
45 import * as Effect from "effect/Effect";
46
47 export default Alchemy.Stack(
48 "MyApp",
49 {
50 providers: AWS.providers(),
51 state: AWS.state(),
52 },
53 Effect.gen(function* () {
54 // we'll add resources here next
55 }),
56 );
57 ```
58
59 `Alchemy.Stack` is the root of every app. The first argument
60 (`"MyApp"`) doubles as a logical id and as the prefix Alchemy uses
61 when AWS asks for physical resource names.
62
63 ## How credentials resolve
64
65 `providers: AWS.providers()` registers every AWS resource and IAM
66 policy binding that ships with Alchemy, and resolves credentials from
67 your Alchemy [profile](/environments/profiles). Connect SSO or stored access
68 keys with `alchemy profile edit --add AWS`. See
69 [Setup](/aws/setup) for the details of each method.
70
71 ## Where state lives
72
73 `state: AWS.state()` stores deploy state in an account-regional S3
74 bucket (`alchemy-state-{accountId}-{region}-an`), created lazily on
75 the first deploy. Because the state lives in your AWS account rather
76 than on disk, the same configuration works locally and in CI with no
77 extra setup.
78
79 :::note[Other state stores]
80 For purely local iteration you can use `Alchemy.localState()`
81 instead, which writes state under `.alchemy/` next to your code — or
82 [write your own](/state-store).
83 :::
84
85 ## Add a Resource
86
87 Resources represent cloud infrastructure — buckets, tables, queues,
88 functions, and so on. Each resource is `yield*`-ed inside the Stack's
89 Effect generator.
90
91 Add an S3 Bucket:
92
93 ```diff lang="typescript"
94 // alchemy.run.ts
95 import * as Alchemy from "alchemy";
96 import * as AWS from "@alchemy.run/aws";
97 import * as Effect from "effect/Effect";
98
99 export default Alchemy.Stack(
100 "MyApp",
101 {
102 providers: AWS.providers(),
103 state: AWS.state(),
104 },
105 Effect.gen(function* () {
106 + const bucket = yield* AWS.S3.Bucket("Bucket");
107 }),
108 );
109 ```
110
111 `yield* AWS.S3.Bucket("Bucket")` registers the resource with the
112 Stack under the logical id `Bucket` and returns a typed `Bucket`
113 handle. We didn't pass a `bucketName`, so Alchemy generates a unique
114 physical name from the app, stage, and logical id.
115
116 ## Return Stack outputs
117
118 Stack outputs let you see important values after a deploy. Return an
119 object from the generator to expose them:
120
121 ```diff lang="typescript"
122 Effect.gen(function* () {
123 const bucket = yield* AWS.S3.Bucket("Bucket");
124 +
125 + return {
126 + bucketName: bucket.bucketName,
127 + };
128 }),
129 ```
130
131 `bucket.bucketName` is an Output — a typed reference to an attribute
132 the cloud will produce. It resolves during deploy and prints with the
133 rest of the stack outputs.
134
135 ## Deploy
136
137 Run `alchemy deploy` to create the Bucket on AWS:
138
139 <PackageManagers run="alchemy deploy" />
140
141 Connect AWS first with `alchemy profile edit --add AWS` and pick a
142 local authentication method: **SSO** (recommended), **console login**
143 (`aws login`), or **stored access keys**. The choice is saved to your
144 **`default`** [profile](/environments/profiles); the region and account
145 come from whichever method you pick, and a deploy with nothing
146 configured fails with that exact command to run. CI instead reads AWS
147 environment credentials directly. See [Setup](/aws/setup) for the full
148 walkthrough.
149
150 :::tip
151 To re-run the credential prompt later (e.g. to switch from stored
152 keys to SSO or console login), use `alchemy profile edit --reconfigure AWS`. For a
153 separate profile, run `alchemy profile create prod` followed by
154 `alchemy profile edit --profile prod`.
155 :::
156
157 <Terminal content={`[u]Plan[/u]: [g]1 to create[/g]
158 [g]+[/g] [b]Bucket[/b] [d](AWS.S3.Bucket)[/d]
159
160 Proceed?
161 ◉ Yes ○ No
162 [g]✓[/g] [b]Bucket[/b] [d](AWS.S3.Bucket)[/d] [g]created[/g]
163 {
164 [s2]bucketName: "myapp-bucket-a1b2c3d4e5",
165 }`} />
166
167 Alchemy shows a plan, asks for confirmation, creates the resource,
168 and prints the stack outputs. Your bucket is live on AWS.
169
170 :::tip
171 By convention, Alchemy looks for `alchemy.run.ts` at the root of your
172 project. You can specify a different file with
173 `alchemy deploy --config <file>`.
174 :::
175
176 ## Verify it worked
177
178 Your newly created bucket will be listed in the S3 section of the AWS
179 Console (or via `aws s3 ls` if you have the AWS CLI installed).
180
181 Run `alchemy deploy` again. Because nothing changed, the bucket shows
182 as a no-op:
183
184 <Terminal content={`[u]Plan[/u]: [d]no changes[/d]
185
186 {
187 [s2]bucketName: "myapp-bucket-a1b2c3d4e5",
188 }`} />
189
190 This is the core loop — declare resources in code, deploy, and
191 Alchemy figures out what changed.
192
193 ## Destroy (optional)
194
195 The inverse of `deploy` is `destroy` — it plans against an empty
196 desired state and deletes everything the stack created:
197
198 ```sh
199 bun alchemy destroy
200 ```
201
202 Try it if you like, then run `bun alchemy deploy` again to bring the
203 bucket back — we'll build on it in Part 2.
204
205 ## Recap
206
207 You now have:
208
209 - An `alchemy.run.ts` with a Stack and an AWS S3 Bucket
210 - A live bucket deployed to your AWS account
211 - Stack outputs showing the bucket name
212
213 In [Part 2](/aws/tutorial/part-2), you'll add a Lambda Function with
214 a public URL that reads and writes objects in this bucket.