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

main
mdx 252 lines 6.95 KB
Raw
1 ---
2 title: Vue
3 description: Deploy a Vue single-page app to AWS with AWS.Website.Vite — S3 + CloudFront, deep links that work by default, and Vue's own Vite dev server under alchemy dev.
4 sidebar:
5 order: 6
6 ---
7
8 import { Code, Tabs, TabItem } from "@astrojs/starlight/components";
9 import PackageManagers from "../../../../components/PackageManagers.astro";
10
11 export const devDeps = "@alchemy.run/frontend-frameworks";
12 export const routerDep = "vue-router";
13
14 [Vue](https://vuejs.org) is pure Vite — the whole app builds from
15 `@vitejs/plugin-vue` in your `vite.config.ts`, so
16 [`AWS.Website.Vite`](/aws/frontend/vite) deploys it with a single
17 declaration. The build output goes to a private S3 bucket behind a
18 CloudFront distribution; there is no server function, no build command
19 to wire up, and no 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 `/vite` and
25 `/vite/aws` exports from your project at deploy time. It is only used at
26 build time, so a dev dependency is enough:
27
28 <PackageManagers dev={devDeps} />
29
30 ## Scaffold the app
31
32 Start from Vite's official Vue + TypeScript template:
33
34 <Tabs syncKey="pkgManager">
35 <TabItem label="pnpm" icon="pnpm">
36 <Code code={`pnpm create vite my-vue-app --template vue-ts\ncd my-vue-app && pnpm install`} lang="sh" />
37 </TabItem>
38 <TabItem label="bun" icon="bun">
39 <Code code={`bun create vite@latest my-vue-app -- --template vue-ts\ncd my-vue-app && bun install`} lang="sh" />
40 </TabItem>
41 <TabItem label="npm" icon="npm">
42 <Code code={`npm create vite@latest my-vue-app -- --template vue-ts\ncd my-vue-app && npm install`} lang="sh" />
43 </TabItem>
44 <TabItem label="yarn" icon="seti:yarn">
45 <Code code={`yarn create vite my-vue-app --template vue-ts\ncd my-vue-app && yarn install`} lang="sh" />
46 </TabItem>
47 </Tabs>
48
49 Write `alchemy.run.ts` in that project root, next to `index.html` and
50 `vite.config.ts`. `rootDir` defaults to `"."`, so you only set it when the
51 app lives somewhere else.
52
53 ## Configure Vite
54
55 Your Vite config stays exactly what the template gives you:
56
57 ```typescript
58 // vite.config.ts
59 import { defineConfig } from "vite";
60 import vue from "@vitejs/plugin-vue";
61
62 export default defineConfig({
63 plugins: [vue()],
64 });
65 ```
66
67 Alchemy runs your project's own `vite build` programmatically against this
68 config — plugins, aliases, and the rest of your setup are preserved as-is.
69
70 ## Declare the Website
71
72 Declare the site as a module-level const (rather than inline in the
73 Stack) — every prop is optional, so the minimal declaration is just a
74 name:
75
76 ```typescript
77 // alchemy.run.ts
78 import * as AWS from "@alchemy.run/aws";
79
80 export const Website = AWS.Website.Vite("Vue");
81 ```
82
83 ## Add it to the Stack
84
85 Yield the site from your Stack and return its URL:
86
87 ```typescript
88 // alchemy.run.ts
89 import * as Alchemy from "alchemy";
90 import * as Effect from "effect/Effect";
91
92 export default Alchemy.Stack(
93 "MyVueSite",
94 {
95 providers: AWS.providers(),
96 state: AWS.state(),
97 },
98 Effect.gen(function* () {
99 const site = yield* Website;
100 return { url: site.url };
101 }),
102 );
103 ```
104
105 ```sh
106 bun alchemy deploy
107 ```
108
109 Alchemy runs `vite build`, uploads `dist` to S3, and serves it from
110 CloudFront at the returned `url`. Input files are content-hashed, so a
111 deploy that changes nothing skips the build and the upload.
112
113 ## Deep links with vue-router
114
115 `vue-router` in history mode (`createWebHistory`) sends a deep link like
116 `/about` to the server as a request for a file that doesn't exist.
117 `AWS.Website.Vite` answers those misses with the index page and a `200`,
118 so the router resolves the route on the client — that is the `spa`
119 default and there is nothing to configure.
120
121 <PackageManagers add={routerDep} />
122
123 ```typescript
124 // src/main.ts
125 import { createApp } from "vue";
126 import { createRouter, createWebHistory } from "vue-router";
127 import App from "./App.vue";
128 import About from "./About.vue";
129 import Home from "./Home.vue";
130
131 const router = createRouter({
132 history: createWebHistory(),
133 routes: [
134 { path: "/", component: Home },
135 { path: "/about", component: About },
136 ],
137 });
138
139 createApp(App).use(router).mount("#app");
140 ```
141
142 Loading `https://<your-site>/about` directly serves the index page and
143 vue-router renders the About view. Pretty URLs still win over the
144 fallback: `/about` serves `about.html` or `about/index.html` when the
145 build produced one.
146
147 For a multi-page project (one `index.html` per route), turn the fallback
148 off and serve a real 404 instead:
149
150 ```diff lang="typescript"
151 // alchemy.run.ts
152 export const Website = AWS.Website.Vite("Vue", {
153 + spa: false,
154 + errorPage: "404.html",
155 });
156 ```
157
158 `spa` and `errorPage` are mutually exclusive: one answers misses with the
159 index page at `200`, the other with your built error page at `404`.
160
161 ## Add environment variables
162
163 A pure SPA has no server, so anything the app needs is baked into the
164 bundle at build time. Vite inlines `VITE_`-prefixed variables from your
165 project's `.env` files and from the environment the deploy runs in:
166
167 ```sh
168 # .env.production
169 VITE_API_URL=https://api.example.com
170 ```
171
172 Type it for your Vue code with Vite's standard `ImportMetaEnv`
173 augmentation:
174
175 ```typescript
176 // src/vite-env.d.ts
177 /// <reference types="vite/client" />
178
179 interface ImportMetaEnv {
180 readonly VITE_API_URL: string;
181 }
182 ```
183
184 Client code reads it as `import.meta.env.VITE_API_URL`.
185
186 ## Bake a Stack output into the bundle
187
188 To inline a value that only exists after another resource deploys — an
189 API's URL, a bucket name — build the site with
190 [`AWS.Website.StaticSite`](/aws/frontend/static-site), whose
191 `build.env` is passed to the build command:
192
193 ```typescript
194 // alchemy.run.ts
195 export default Alchemy.Stack(
196 "MyVueSite",
197 {
198 providers: AWS.providers(),
199 state: AWS.state(),
200 },
201 Effect.gen(function* () {
202 const api = yield* Api;
203
204 const site = yield* AWS.Website.StaticSite("Vue", {
205 build: {
206 command: "vite build",
207 output: "dist",
208 env: {
209 VITE_API_URL: api.url,
210 },
211 },
212 spa: true,
213 });
214
215 return { url: site.url };
216 }),
217 );
218 ```
219
220 The build re-runs when the inputs change and the output deploys to the
221 same S3 + CloudFront stack.
222
223 ## Local dev
224
225 ```sh
226 bun alchemy dev
227 ```
228
229 `alchemy dev` runs Vue's own Vite dev server with native HMR instead of
230 deploying; `site.url` is the local address and no AWS resources are
231 created. Wrap the site in `Alchemy.remote()` to deploy the real
232 infrastructure even during dev.
233
234 ## Custom domain
235
236 ```typescript
237 // alchemy.run.ts
238 export const Website = AWS.Website.Vite("Vue", {
239 domain: { name: "app.example.com" },
240 });
241 ```
242
243 The ACM certificate and the Route 53 records are created for you, and
244 `site.url` becomes `https://app.example.com`. The hosted zone is
245 inferred from the hostname — pass `hostedZoneId` to pin it when
246 several zones could match.
247
248 ## Where next
249
250 - [Vite on AWS](/aws/frontend/vite) — every prop the resource takes,
251 including `vite.outDir`, `vite.base`, and Router composition
252 - [Websites on AWS](/aws/frontend/websites) — the full websites surface