@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 226 lines 7.58 KB
Raw
1 ---
2 title: Static sites
3 description: Ship a static site to S3 + CloudFront with AWS.Website.StaticSite — build-step support, Router composition, and cache invalidation on deploy.
4 sidebar:
5 order: 4
6 ---
7
8 `AWS.Website.StaticSite` deploys a directory of files as a website: it uploads
9 the files to a private S3 bucket, creates a CloudFront distribution with a
10 CloudFront Function that routes requests at the edge via a KeyValueStore file
11 manifest, and invalidates the cache when your assets change. Use it whenever
12 the output is plain files — docs, marketing pages, or a built SPA.
13
14 ## Deploy a directory
15
16 Point `path` at a directory of files and return the site's `url` as a stack
17 output:
18
19 ```typescript
20 // alchemy.run.ts
21 import * as Alchemy from "alchemy";
22 import * as AWS from "@alchemy.run/aws";
23 import * as Effect from "effect/Effect";
24
25 export default Alchemy.Stack(
26 "MyStaticSite",
27 {
28 providers: AWS.providers(),
29 state: AWS.state(),
30 },
31 Effect.gen(function* () {
32 const site = yield* AWS.Website.StaticSite("MarketingSite", {
33 path: "./site",
34 forceDestroy: true,
35 });
36
37 return {
38 url: site.url,
39 };
40 }),
41 );
42 ```
43
44 One `StaticSite` expands into the whole stack — an S3 bucket, the asset
45 upload, a CloudFront KeyValueStore holding the file manifest, a viewer-request
46 CloudFront Function, and the distribution itself. `forceDestroy: true` lets
47 `destroy` empty the bucket before deleting it; `site.url` resolves to the
48 CloudFront domain (or `https://<your-domain>` when you pass `domain`).
49
50 ```sh
51 bun alchemy deploy
52 ```
53
54 The deployed example lives at
55 [`examples/aws-static-site`](https://github.com/alchemy-run/alchemy/tree/main/examples/aws-static-site)
56 if you want a runnable starting point.
57
58 ## Run a build step first
59
60 For framework sites (Vite, Astro, etc.), add `build` so the framework's build
61 runs before upload and the `output` directory is what gets deployed:
62
63 ```typescript
64 const site = yield* AWS.Website.StaticSite("Web", {
65 path: "./frontend",
66 build: {
67 command: "bun run build",
68 output: "dist",
69 env: {
70 VITE_API_URL: api.url,
71 },
72 },
73 });
74 ```
75
76 The build step is a [Command.Build](/providers/command/build) resource —
77 memoized, so unchanged inputs skip the build
78 ([details](/command/memoization)). The input hash covers, by default, all
79 files under `path` (filtered by your gitignore rules) plus the nearest
80 package-manager lockfile. Tune the hash with `build.include`, `build.exclude`, and
81 `build.lockfile` — e.g. `include: ["src/**", "package.json"]` to re-run only
82 when source files change. `build.env` variables are passed to the build
83 command, so outputs from other resources (like an API URL) flow straight into
84 the frontend bundle.
85
86 ## SPAs and 404 pages
87
88 A miss — a request that matches no uploaded file — can be answered two ways,
89 and they are mutually exclusive:
90
91 ```typescript
92 // Single-page app: misses serve index.html with a 200 so the
93 // client-side router takes over.
94 const app = yield* AWS.Website.StaticSite("App", {
95 path: "./app",
96 build: { command: "bun run build", output: "dist" },
97 spa: true,
98 });
99
100 // Static site: misses return a real 404 status with your error page.
101 const docs = yield* AWS.Website.StaticSite("Docs", {
102 path: "./docs/dist",
103 errorPage: "404.html",
104 });
105 ```
106
107 Pretty URLs work in both modes: `/about` serves `about.html` or
108 `about/index.html` when one was uploaded, resolved at the edge from the file
109 manifest.
110
111 ## Compose sites with a Router
112
113 `AWS.Website.Router` is a shared CloudFront front door: one distribution whose
114 routes live in a KeyValueStore, matched at the edge by a CloudFront Function.
115 Create the router, then attach sites to it instead of giving each site its own
116 distribution:
117
118 ```typescript
119 const router = yield* AWS.Website.Router("WebsiteRouter", {
120 // hosted zone inferred from the hostname; pass hostedZoneId to pin it, or
121 // dns: Cloudflare.DNS.Adapter() for a domain on Cloudflare DNS
122 // (see /infrastructure-as-code/dns-adapters)
123 domain: { name: "example.com" },
124 });
125
126 const site = yield* AWS.Website.StaticSite("Docs", {
127 path: "./docs",
128 domain: {
129 router,
130 path: "/docs",
131 },
132 });
133 ```
134
135 The site registers itself by writing its file manifest and metadata into the
136 router's KV store — no distribution redeploy is needed to add or remove a
137 site. In router mode, `domain.name` is an optional host pattern (exact
138 hostname or `*.example.com`) matched at the edge; the hostname must also be
139 covered by the Router's own `domain`. `edge` and `cloudfrontUrl` live on the
140 `Router` — setting them on an attached site is an error.
141
142 ## Route to non-site origins
143
144 The router also takes inline `routes` for origins that aren't managed by
145 `StaticSite`, keyed by path pattern:
146
147 ```typescript
148 const router = yield* AWS.Website.Router("WebsiteRouter", {
149 routes: {
150 "/*": { url: api.functionUrl },
151 },
152 });
153 ```
154
155 A route value can be a URL (proxied as a custom origin) or a
156 `{ bucket }` route serving straight from S3, optionally with a
157 `rewrite: { regex, to }` applied to the URI before forwarding. Longest
158 host-then-path match wins, so a `StaticSite` mounted at `/docs` takes
159 precedence over a `/*` fallback route.
160
161 ## Cache invalidation on deploy
162
163 By default every deploy that changes your files creates a CloudFront
164 invalidation for `/*` and moves on without waiting
165 (`{ paths: "all", wait: false }`). The invalidation is keyed to a content hash
166 of the uploaded assets, so deploys that change nothing don't invalidate
167 anything. Tune it with `invalidation`:
168
169 ```typescript
170 const site = yield* AWS.Website.StaticSite("MarketingSite", {
171 path: "./site",
172 invalidation: {
173 paths: "all",
174 wait: true,
175 },
176 });
177 ```
178
179 - `paths: "all"` — invalidate `/*` (the default)
180 - `paths: "versioned"` — invalidate only the index page, for sites whose
181 assets are content-hashed and immutable
182 - `paths: [...]` — an explicit list of paths
183 - `wait: true` — block the deploy until CloudFront reports the invalidation
184 complete
185 - `invalidation: false` — skip invalidation entirely
186
187 ## Local dev
188
189 During `alchemy dev`, the `dev` prop replaces the build (and the whole
190 S3 + CloudFront deployment) with your framework's own dev server:
191
192 ```typescript
193 const site = yield* AWS.Website.StaticSite("Web", {
194 path: "./frontend",
195 build: { command: "bun run build", output: "dist" },
196 dev: { command: "bun run dev" },
197 });
198 ```
199
200 `dev.command` is spawned as a long-lived sidecar process tied to the
201 stack's scope — the build is skipped, no AWS resources are created, and
202 `site.url` is the dev server's local address, detected from the
203 command's stdout. `dev` also accepts `cwd` and `env` overrides for the
204 dev process, and `dev.url` to pin the URL explicitly when stdout
205 detection fails. Wrap the site in `Alchemy.remote()` to deploy the real
206 infrastructure even during dev.
207
208 ## When to use a framework resource instead
209
210 `StaticSite` is the general fallback for any directory of files (with or
211 without a build command). Frameworks with dedicated resources have a
212 better path: [Astro](/aws/frontend/astro),
213 [Next.js](/aws/frontend/nextjs), [Nuxt](/aws/frontend/nuxt),
214 [SvelteKit](/aws/frontend/sveltekit), and [Waku](/aws/frontend/waku)
215 run the framework's own programmatic build, deploy server-rendered
216 routes on a streaming Lambda, and skip the build contract entirely.
217 Reach for `StaticSite` when there is no dedicated resource — Zola,
218 Hugo, or any other generator, or a pre-built SPA.
219
220 ## Where next
221
222 - [Websites on AWS](/aws/frontend/websites) — the full websites surface, including
223 server-side rendering
224 - [StaticSite reference](/providers/aws/website/staticsite) and
225 [Router reference](/providers/aws/website/router) — every prop and attribute
226 - [AWS on Alchemy](/aws) — the AWS provider hub