@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 221 lines 6.2 KB
Raw
1 ---
2 title: Nuxt
3 description: Deploy a Nuxt app to AWS with AWS.Website.Nuxt — the nitro server on a Lambda Web Function, S3 assets behind CloudFront, and Nuxt's own dev server under alchemy dev.
4 sidebar:
5 order: 10
6 ---
7
8 import PackageManagers from "../../../../components/PackageManagers.astro";
9
10 export const devDeps = "@alchemy.run/frontend-frameworks";
11
12 `AWS.Website.Nuxt` deploys a [Nuxt](https://nuxt.com) app to AWS. It
13 builds the app through your project's own `@nuxt/kit` with nitro's
14 `node` preset: the nitro server runs on a
15 [Lambda Web Function](/aws/compute/web-functions) and streams its
16 responses, and client assets plus prerendered pages are served from a
17 private S3 bucket through CloudFront. A CloudFront Function routes each
18 request at the edge — uploaded files go to S3, everything else streams
19 from the server. There is no `nitro.preset`
20 to edit and no build command to run.
21
22 ## Install
23
24 The build integration is not bundled with alchemy. Install
25 `@alchemy.run/frontend-frameworks`; the resource loads its `/nuxt` and
26 `/nuxt/node` exports from your project at deploy time. It is only used
27 at build time, so a dev dependency is enough:
28
29 <PackageManagers dev={devDeps} />
30
31 ## Configure Nuxt
32
33 Your `nuxt.config.ts` loads natively — modules, layers, and all —
34 so configure Nuxt exactly as you would outside Alchemy:
35
36 ```typescript
37 // nuxt.config.ts
38 export default defineNuxtConfig({
39 modules: ["@nuxtjs/tailwindcss"],
40 routeRules: {
41 "/about": { prerender: true },
42 },
43 });
44 ```
45
46 Don't set `nitro.preset` — the deploy target owns the preset (`node`,
47 or `aws-lambda` with streaming enabled for `server: "function"`), and a
48 foreign preset is a hard error.
49
50 ## Deploy-time overrides
51
52 Config that only exists at deploy time — a stage-dependent base URL, a
53 per-environment `runtimeConfig` — goes in the `nuxt` prop. It merges
54 over `nuxt.config.ts` as the highest-priority layer, so a value here
55 wins:
56
57 ```typescript
58 export const Website = AWS.Website.Nuxt("Website", {
59 nuxt: {
60 app: { baseURL: "/docs/" },
61 runtimeConfig: {
62 public: { apiBase: "https://api.example.com" },
63 },
64 },
65 });
66 ```
67
68 The bag must be JSON-serializable — no functions, plugins, or modules;
69 those belong in `nuxt.config.ts`. `nitro.preset` stays owned by the
70 deploy target.
71
72 ## Declare the Website
73
74 Declare the site as a module-level const (rather than inline in the
75 Stack):
76
77 ```typescript
78 // alchemy.run.ts
79 import * as AWS from "@alchemy.run/aws";
80
81 export const Website = AWS.Website.Nuxt("Website");
82 ```
83
84 ## Add it to the Stack
85
86 Yield the site from your Stack and return its URL:
87
88 ```typescript
89 // alchemy.run.ts
90 import * as Alchemy from "alchemy";
91 import * as Effect from "effect/Effect";
92
93 export default Alchemy.Stack(
94 "MyNuxtSite",
95 {
96 providers: AWS.providers(),
97 state: AWS.state(),
98 },
99 Effect.gen(function* () {
100 const site = yield* Website;
101 return { url: site.url };
102 }),
103 );
104 ```
105
106 See
107 [examples/aws-website-nuxt](https://github.com/alchemy-run/alchemy/tree/main/examples/aws-website-nuxt)
108 for the checked-in example.
109
110 ## Add environment variables
111
112 The server function's environment is configured under `env` — plain
113 values, or outputs from other resources in the Stack:
114
115 ```diff lang="typescript"
116 // alchemy.run.ts
117 export const Website = AWS.Website.Nuxt("Website", {
118 + env: {
119 + NUXT_PUBLIC_API_BASE: api.url,
120 + },
121 });
122 ```
123
124 `env` values are set on the server on deploy and injected into
125 the dev server's process environment under `alchemy dev`, so server
126 code reads the same values in both modes. Sibling props tune the
127 server itself (`timeout`, `maxConcurrencyPerEnvironment`,
128 `maxEnvironments`).
129
130 ## Read the environment in server code
131
132 On AWS the nitro server is a plain Node server, so server routes
133 and SSR read the environment from `process.env` — or, the more
134 idiomatic Nuxt way, through `runtimeConfig` overridden by
135 `NUXT_`-prefixed environment variables:
136
137 ```typescript
138 // server/api/hello.ts
139 export default defineEventHandler(() => {
140 return { greeting: process.env.GREETING ?? "hello" };
141 });
142 ```
143
144 ## Prerendering
145
146 Routes marked for prerendering in `routeRules` (or via
147 `nitro.prerender`) render at build time into `.output/public` and are
148 uploaded to S3, served from the edge with no Lambda invocation.
149 Configure them in your project's `nuxt.config.ts`:
150
151 ```typescript
152 // nuxt.config.ts
153 export default defineNuxtConfig({
154 routeRules: {
155 "/about": { prerender: true },
156 },
157 });
158 ```
159
160 Nitro's `isr` route rule is implemented only by the Vercel and
161 Netlify presets. On AWS it is silently ignored at build time,
162 and the route renders on demand on the server like any other SSR
163 route. Use `prerender` for build-time static routes, or `cache` route
164 rules for runtime caching.
165
166 ## Run on a Lambda Function
167
168 Web Functions run in a subset of Regions. Elsewhere, set
169 `server: "function"`: the app builds with nitro's `aws-lambda` preset
170 (from the `/nuxt/aws` export) and runs on a Lambda Function behind a
171 streaming Function URL, tuned with `memorySize`, `architecture`, and
172 `runtime`:
173
174 ```diff lang="typescript"
175 // alchemy.run.ts
176 export const Website = AWS.Website.Nuxt("Website", {
177 + server: "function",
178 + memorySize: 2048,
179 });
180 ```
181
182 ## Local dev
183
184 ```sh
185 bun alchemy dev
186 ```
187
188 `alchemy dev` runs Nuxt's own dev server (nitro dev, full HMR)
189 instead of deploying anything; `site.url` is the dev server's
190 `http://localhost:<port>` address and no AWS resources are created.
191 Wrap the site in `Alchemy.remote()` to deploy the real infrastructure
192 even during dev.
193
194 ## Custom domain
195
196 ```typescript
197 const site = yield* AWS.Website.Nuxt("Web", {
198 domain: { name: "app.example.com" },
199 });
200 ```
201
202 The certificate is created in `us-east-1` (required by CloudFront),
203 DNS validation records and the alias record are managed through
204 Route 53. The hosted zone is inferred from the hostname — pass
205 `hostedZoneId` to pin it when several zones could match.
206
207 ## Share a distribution with Router
208
209 CloudFront distributions take minutes to create. To serve several
210 sites (or a site plus an API) from one distribution, attach the site
211 to an [`AWS.Website.Router`](/aws/frontend/static-site#compose-sites-with-a-router):
212
213 ```typescript
214 const router = yield* AWS.Website.Router("FrontDoor", {
215 domain: { name: "example.com" },
216 });
217
218 const site = yield* AWS.Website.Nuxt("Web", {
219 domain: { router },
220 });
221 ```