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

main
mdx 311 lines 8.82 KB
Raw
1 ---
2 title: Vite
3 description: Deploy a plain Vite app to AWS with AWS.Website.Vite — the vite build output on S3 behind CloudFront, SPA fallback at the edge, and Vite's own dev server under alchemy dev.
4 sidebar:
5 order: 2
6 ---
7
8 import PackageManagers from "../../../../components/PackageManagers.astro";
9
10 export const devDeps = "@alchemy.run/frontend-frameworks";
11
12 `AWS.Website.Vite` deploys a client-only [Vite](https://vite.dev)
13 project to AWS. It runs your project's own `vite build` — your
14 `vite.config.*` loads natively, plugins included — and serves the
15 output from a private S3 bucket through CloudFront. The site is
16 assets-only: no Lambda is created, no CloudFormation to write, no
17 build command to wire up.
18
19 ## Install
20
21 The build integration is not bundled with alchemy. Install
22 `@alchemy.run/frontend-frameworks`; the resource loads its `/vite` and
23 `/vite/aws` exports from your project at deploy time. It is only used
24 at build time, so a dev dependency is enough:
25
26 <PackageManagers dev={devDeps} />
27
28 ## Configure Vite
29
30 There is nothing to configure. Your `vite.config.*` loads natively —
31 plugins, aliases, and any other non-serializable options work exactly
32 as they do outside Alchemy:
33
34 ```typescript
35 // vite.config.ts
36 import { defineConfig } from "vite";
37 import react from "@vitejs/plugin-react";
38
39 export default defineConfig({
40 plugins: [react()],
41 });
42 ```
43
44 A project with no config file at all works too: an `index.html` next
45 to your `alchemy.run.ts` is enough.
46
47 ## Declare the Website
48
49 Declare the site as a module-level const (rather than inline in the
50 Stack):
51
52 ```typescript
53 // alchemy.run.ts
54 import * as AWS from "@alchemy.run/aws";
55
56 export const Website = AWS.Website.Vite("Website");
57 ```
58
59 ## Add it to the Stack
60
61 Yield the site from your Stack and return its URL:
62
63 ```typescript
64 // alchemy.run.ts
65 import * as Alchemy from "alchemy";
66 import * as Effect from "effect/Effect";
67
68 export default Alchemy.Stack(
69 "MyViteSite",
70 {
71 providers: AWS.providers(),
72 state: AWS.state(),
73 },
74 Effect.gen(function* () {
75 const site = yield* Website;
76 return { url: site.url };
77 }),
78 );
79 ```
80
81 Deploying uploads the build output to S3, writes the file manifest to
82 a CloudFront KeyValueStore, and creates the distribution that serves
83 it at the edge.
84
85 ```sh
86 bun alchemy deploy
87 ```
88
89 See
90 [examples/aws-website-vite](https://github.com/alchemy-run/alchemy/tree/main/examples/aws-website-vite)
91 for the checked-in example.
92
93 ## Point at a subdirectory
94
95 `rootDir` is the Vite project root — the directory holding
96 `package.json`, `vite.config.*`, and `index.html`. It defaults to the
97 directory you run `alchemy` from:
98
99 ```typescript
100 export const Website = AWS.Website.Vite("Website", {
101 rootDir: "./web",
102 });
103 ```
104
105 Vite resolves `index.html` relative to its root, so `index.html` must
106 live directly under `rootDir`. See Vite's
107 [project structure docs](https://vite.dev/guide/#index-html-and-project-root).
108
109 ## Deploy-time overrides
110
111 Your `vite.config.*` is the home for Vite configuration. The `vite`
112 bag is for the exception: a value decided by the deployment rather
113 than the project — config files can't consume alchemy `Output`s.
114 Overrides merge *over* the config file, so the deploy-time value wins:
115
116 ```typescript
117 export const Website = AWS.Website.Vite("Docs", {
118 vite: {
119 base: "/docs/",
120 outDir: "build",
121 },
122 });
123 ```
124
125 `base` is the public path the site deploys under; `outDir` is the
126 build output directory, relative to `rootDir`. Leave the bag unset and
127 the resolved values from your `vite.config.*` are used — Vite's own
128 `outDir` default is `dist`. `base` also applies to the dev server
129 under `alchemy dev`.
130
131 To load a different config file entirely, pass `config` (relative to
132 `rootDir`):
133
134 ```typescript
135 export const Website = AWS.Website.Vite("Web", {
136 config: "vite.deploy.config.ts",
137 });
138 ```
139
140 ## SPA fallback and 404 pages
141
142 A miss — a request that matches no uploaded file — can be answered two
143 ways, and they are mutually exclusive. Plain Vite apps are usually
144 single-page apps, so `spa` defaults to `true`: misses serve the index
145 page with a `200` and the client-side router takes over.
146
147 For a multi-page project (an `index.html` per route), turn it off and
148 point at the built error page instead:
149
150 ```diff lang="typescript"
151 export const Website = AWS.Website.Vite("Docs", {
152 + spa: false,
153 + errorPage: "404.html",
154 });
155 ```
156
157 `errorPage` serves that file with a real `404` status. Pretty URLs
158 work in both modes: `/about` serves `about.html` or
159 `about/index.html` when one was uploaded, resolved at the edge from
160 the file manifest.
161
162 ## Environment variables
163
164 There is no server, so everything the app reads is inlined into the
165 bundle at build time — plain Vite semantics. Put `VITE_`-prefixed keys
166 in a `.env` file at `rootDir` and read them from `import.meta.env`:
167
168 ```sh
169 # .env
170 VITE_API_URL=https://api.example.com
171 ```
172
173 ```typescript
174 // src/api.ts
175 const apiUrl = import.meta.env.VITE_API_URL;
176 ```
177
178 Only `VITE_`-prefixed keys reach the bundle. A committed `.env` is
179 hashed with the rest of the project, so editing one re-runs the build
180 on the next deploy.
181
182 The resource takes no `env` prop, so a value that only exists
183 after another resource deploys — an API's Function URL, a bucket name
184 — cannot reach this build. Deploy those apps with
185 [`AWS.Website.StaticSite`](/aws/frontend/static-site) instead, which
186 runs the build as a command and passes `environment` to it.
187
188 ## Rebuilds are content-hashed
189
190 Every non-gitignored file under `rootDir` plus the nearest lockfile is
191 content-hashed. If nothing changed, both the build and the deploy are
192 skipped. Narrow the scope with `memo` when the project holds large
193 directories that don't affect the build output:
194
195 ```typescript
196 export const Website = AWS.Website.Vite("Docs", {
197 memo: {
198 include: ["src/**", "index.html", "package.json"],
199 lockfile: true,
200 },
201 });
202 ```
203
204 Setting `include` flips the lockfile default to `false`, so pair it
205 with `lockfile: true` to keep rebuilding when dependencies change.
206 `memo: false` rebuilds on every deploy. See
207 [Memoization](/command/memoization) for the details.
208
209 ## Cache invalidation on deploy
210
211 Every deploy that changes your files invalidates `/*` and moves on
212 without waiting. Tune it with `invalidation`:
213
214 ```typescript
215 export const Website = AWS.Website.Vite("Website", {
216 invalidation: {
217 paths: "versioned",
218 wait: true,
219 },
220 });
221 ```
222
223 `paths: "versioned"` invalidates only the index page, for builds whose
224 assets are content-hashed and immutable; `invalidation: false` skips
225 it entirely.
226
227 ## Local dev
228
229 ```sh
230 bun alchemy dev
231 ```
232
233 `alchemy dev` runs Vite's own dev server (native HMR) instead of
234 deploying; `site.url` is the local address and no AWS resources are
235 created. Wrap the site in `Alchemy.remote()` to deploy the real
236 infrastructure even during dev.
237
238 The dev server picks an ephemeral port by default. Pin it to keep the
239 local URL stable across runs:
240
241 ```typescript
242 export const Website = AWS.Website.Vite("Website", {
243 dev: { port: 3000 },
244 });
245 ```
246
247 ## Custom domain
248
249 ```typescript
250 // alchemy.run.ts
251 export const Website = AWS.Website.Vite("Website", {
252 domain: { name: "app.example.com" },
253 });
254 ```
255
256 The ACM certificate and Route 53 records are managed for you — the
257 hosted zone is inferred from the hostname, and `hostedZoneId` pins it
258 when several zones could match. A bare string is shorthand for
259 `{ name }`.
260
261 ## Share a CloudFront Router
262
263 Attach the site to an existing
264 [`AWS.Website.Router`](/aws/frontend/static-site#compose-sites-with-a-router)
265 to serve it through one shared distribution instead of its own:
266
267 The site takes the Router's *outputs*, so both are yielded inside the
268 Stack generator:
269
270 ```typescript
271 Effect.gen(function* () {
272 const router = yield* AWS.Website.Router("Router", {
273 domain: { name: "example.com" },
274 });
275
276 const site = yield* AWS.Website.Vite("Docs", {
277 domain: { router, path: "/docs" },
278 });
279
280 return { url: site.url };
281 });
282 ```
283
284 ## Frameworks
285
286 Anything whose whole deployable output is a `vite build` deploys with
287 this resource. Each client-only stack has its own page building on it:
288
289 - [React SPA](/aws/frontend/vite-spa) — from a bare `index.html` to
290 the `create-vite` template.
291 - [Vue](/aws/frontend/vue) — Vue 3 SPAs with `vue-router` deep links.
292 - [Foldkit](/aws/frontend/foldkit) — deploys SPA, SSR, and prerendered apps
293 through `AWS.Website.Foldkit`.
294
295 ## SSR frameworks
296
297 `AWS.Website.Vite` is static-only — it never creates a server
298 function. Frameworks that wrap Vite with a server half deploy through
299 their own resources, which build the SSR bundle and put it on a
300 streaming Lambda Function URL:
301 [Astro](/aws/frontend/astro),
302 [SvelteKit](/aws/frontend/sveltekit),
303 [Octane](/aws/frontend/octane),
304 [Nuxt](/aws/frontend/nuxt),
305 [Next.js](/aws/frontend/nextjs),
306 [TanStack Start](/aws/frontend/tanstack-start),
307 [React Router](/aws/frontend/react-router), and
308 [Waku](/aws/frontend/waku).
309
310 For any other build command that emits a directory of files, use
311 [StaticSite](/aws/frontend/static-site).