@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, 06:00 UTC

main
mdx 233 lines 6.51 KB
Raw
1 ---
2 title: Astro
3 description: Deploy an Astro app to AWS with AWS.Website.Astro — SSR on a Lambda Web Function, static output on S3 + CloudFront, and Astro's own dev server under alchemy dev.
4 sidebar:
5 order: 11
6 ---
7
8 import PackageManagers from "../../../../components/PackageManagers.astro";
9
10 export const devDeps = "@alchemy.run/frontend-frameworks";
11
12 `AWS.Website.Astro` deploys an [Astro](https://astro.build) project
13 to AWS. It runs Astro's programmatic build with a wrangler-free Node
14 adapter: server-rendered pages stream from a
15 [Lambda Web Function](/aws/compute/web-functions), prerendered pages
16 and client assets are served from a private S3
17 bucket through CloudFront, routed at the edge. Your `astro.config.*`
18 loads natively — there is no adapter to install into it and no
19 CloudFormation to write.
20
21 ## Install
22
23 The build integration is not bundled with alchemy. Install
24 `@alchemy.run/frontend-frameworks`; the resource loads its `/astro`
25 and `/astro/node` exports from your project at deploy time. It is only
26 used at build time, so a dev dependency is enough:
27
28 <PackageManagers dev={devDeps} />
29
30 ## Configure Astro
31
32 Your `astro.config.*` file loads natively — integrations, Vite
33 plugins, and any other non-serializable options work exactly as they
34 do outside Alchemy. Alchemy merges a programmatic config *over* it:
35 Alchemy's Node adapter is injected for you (don't declare an
36 `adapter` in your config — that fails the build with an actionable
37 error), and options passed via the `astro` prop override the file's —
38 see [Astro configuration](#astro-configuration) below for the
39 details.
40
41 ## Declare the Website
42
43 Declare the site as a module-level const (rather than inline in the
44 Stack):
45
46 ```typescript
47 // alchemy.run.ts
48 import * as AWS from "@alchemy.run/aws";
49
50 export const Website = AWS.Website.Astro("Website");
51 ```
52
53 ## Add it to the Stack
54
55 Yield the site from your Stack and return its URL:
56
57 ```typescript
58 // alchemy.run.ts
59 import * as Alchemy from "alchemy";
60 import * as Effect from "effect/Effect";
61
62 export default Alchemy.Stack(
63 "MyAstroSite",
64 {
65 providers: AWS.providers(),
66 state: AWS.state(),
67 },
68 Effect.gen(function* () {
69 const site = yield* Website;
70 return { url: site.url };
71 }),
72 );
73 ```
74
75 Pages are server-rendered by default. Pages that
76 `export const prerender = true` are uploaded to S3 and served from
77 the edge without invoking the server.
78
79 See
80 [examples/aws-website-astro](https://github.com/alchemy-run/alchemy/tree/main/examples/aws-website-astro)
81 for the checked-in example.
82
83 ## Add environment variables
84
85 The server function's environment is configured under `env` — plain
86 values, or outputs from other resources in the Stack:
87
88 ```diff lang="typescript"
89 // alchemy.run.ts
90 export const Website = AWS.Website.Astro("Website", {
91 + env: {
92 + GREETING: "Hello from Alchemy!",
93 + API_BASE: api.url,
94 + },
95 });
96 ```
97
98 The values are set on the server at deploy time and injected into the
99 dev server's process environment under `alchemy dev`, so server code
100 reads the same values in both modes.
101
102 ## Read the environment in server code
103
104 The Astro server is a plain Node server, so server-rendered
105 pages and endpoints read the environment from `process.env`:
106
107 ```astro
108 ---
109 // src/pages/index.astro
110 const greeting = process.env.GREETING ?? "hello";
111 ---
112
113 <h1>{greeting}</h1>
114 ```
115
116 ## Fully static sites
117
118 With `astro: { output: "static" }` every page is prerendered at
119 build time and the deploy is assets-only — no Lambda is created, and
120 the S3 + CloudFront asset layer answers every request:
121
122 ```typescript
123 export const Website = AWS.Website.Astro("Website", {
124 astro: { output: "static" },
125 errorPage: "404.html",
126 });
127 ```
128
129 `errorPage` serves the built `404.html` for unmatched routes; `spa`
130 answers misses with the index page (200) instead.
131
132 ## Astro configuration
133
134 Your `astro.config.*` is the primary place to configure Astro —
135 integrations, Vite plugins, and every other option (serializable or
136 not) work as usual:
137
138 ```typescript
139 // astro.config.ts
140 import { defineConfig } from "astro/config";
141 import react from "@astrojs/react";
142 import tailwindcss from "@tailwindcss/vite";
143
144 export default defineConfig({
145 site: "https://blog.example.com",
146 integrations: [react()],
147 vite: {
148 plugins: [tailwindcss()],
149 },
150 });
151 ```
152
153 A config file can't consume Alchemy `Output`s or vary by stage. For
154 those values the `astro` prop is a deploy-time override bag — a
155 serializable subset (`site`, `base`, `output`, `srcDir`, `publicDir`,
156 `outDir`, `trailingSlash`) merged *over* the config file, so a value
157 set here wins:
158
159 ```typescript
160 // alchemy.run.ts
161 import { Stack } from "alchemy/Stack";
162
163 Effect.gen(function* () {
164 const { stage } = yield* Stack;
165
166 const site = yield* AWS.Website.Astro("Website", {
167 astro: {
168 site:
169 stage === "prod"
170 ? "https://blog.example.com"
171 : `https://${stage}.example.com`,
172 },
173 });
174 });
175 ```
176
177 Use `config` to load an alternate config file (relative to
178 `rootDir`) instead of astro's own `astro.config.*` discovery:
179
180 ```typescript
181 export const Website = AWS.Website.Astro("Website", {
182 config: "astro.deploy.config.ts",
183 });
184 ```
185
186 Two options are managed for you regardless of the config file:
187
188 - `adapter` — Alchemy injects its wrangler-free Node adapter.
189 Declaring an adapter in `astro.config.*` fails the build with an
190 actionable error.
191 - `output` — Alchemy defaults it to `"server"` (superseding a
192 file-level `output`), so pages render on demand on the server.
193 Opt into a fully prerendered site with `astro: { output: "static" }`
194 on the resource.
195
196 ## Run on a Lambda Function
197
198 Web Functions run in a subset of Regions. Elsewhere, set
199 `server: "function"`: the app builds with the `/astro/aws` deploy target
200 and runs on a Lambda Function behind a streaming Function URL, tuned with
201 `memorySize`, `architecture`, and `runtime`:
202
203 ```diff lang="typescript"
204 // alchemy.run.ts
205 export const Website = AWS.Website.Astro("Website", {
206 + server: "function",
207 + memorySize: 2048,
208 });
209 ```
210
211 ## Local dev
212
213 `alchemy dev` runs Astro's own dev server (native HMR) instead of
214 deploying; `site.url` is the local address and no AWS resources are
215 created. Wrap the site in `Alchemy.remote()` to deploy the real
216 infrastructure even during dev.
217
218 ## Custom domain
219
220 ```typescript
221 const site = yield* AWS.Website.Astro("Web", {
222 domain: { name: "app.example.com" },
223 });
224 ```
225
226 The hosted zone is inferred from the hostname. Pass `hostedZoneId` to
227 pin it when several zones could match.
228
229 :::note
230 Astro's default image service uses `sharp`. To use Astro image
231 optimization on AWS, add `sharp` as a project dependency so it ships
232 with the server bundle.
233 :::