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

main
mdx 243 lines 6.93 KB
Raw
1 ---
2 title: Nuxt
3 description: Deploy a Nuxt app to Cloudflare Workers with Cloudflare.Website.Nuxt — nitro's cloudflare_module preset, native nuxt.config.ts loading, and wrangler-free local 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 `Cloudflare.Website.Nuxt` deploys a [Nuxt](https://nuxt.com) app as
13 a Cloudflare Worker. It builds the app through your project's own
14 `@nuxt/kit` with nitro's `cloudflare_module` preset: the nitro server
15 bundle deploys as the Worker script, and client assets plus
16 prerendered pages deploy as Worker static assets. There is no
17 `nitro.preset` to edit, no Wrangler file, and no build command to
18 run.
19
20 ## Install
21
22 The build integration is not bundled with alchemy. Install
23 `@alchemy.run/frontend-frameworks`; the resource loads its `/nuxt`
24 export from your project at deploy time. It is only used at build time,
25 so a dev dependency is enough:
26
27 <PackageManagers dev={devDeps} />
28
29 ## Configure Nuxt
30
31 Your `nuxt.config.ts` loads natively — modules, layers, and all —
32 so configure Nuxt exactly as you would outside Alchemy:
33
34 ```typescript
35 // nuxt.config.ts
36 export default defineNuxtConfig({
37 modules: ["@nuxtjs/tailwindcss"],
38 routeRules: {
39 "/about": { prerender: true },
40 },
41 });
42 ```
43
44 Don't set `nitro.preset` — the Cloudflare deploy target owns the
45 preset, and a foreign preset is a hard error.
46
47 ## Deploy-time overrides
48
49 Config that only exists at deploy time — a stage-dependent base URL, a
50 per-environment `runtimeConfig` — goes in the `nuxt` prop. It merges
51 over `nuxt.config.ts` as the highest-priority layer, so a value here
52 wins:
53
54 ```typescript
55 export const Website = Cloudflare.Website.Nuxt("Website", {
56 nuxt: {
57 app: { baseURL: "/docs/" },
58 runtimeConfig: {
59 public: { apiBase: "https://api.example.com" },
60 },
61 },
62 });
63 ```
64
65 The bag must be JSON-serializable — no functions, plugins, or modules;
66 those belong in `nuxt.config.ts`. `nitro.preset` stays owned by the
67 deploy target.
68
69 ## Declare the Website
70
71 Declare the site as a module-level const (rather than inline in the
72 Stack) and derive the typed shape of its bindings from it:
73
74 ```typescript
75 // alchemy.run.ts
76 import * as Cloudflare from "@alchemy.run/cloudflare";
77
78 export const Website = Cloudflare.Website.Nuxt("Website");
79
80 export type WebsiteEnv = Cloudflare.InferEnv<typeof Website>;
81 ```
82
83 `WebsiteEnv` is the typed shape of the Worker's bindings, derived
84 from the class — you'll import it into your Nuxt code in
85 [Read bindings in server code](#read-bindings-in-server-code).
86
87 ## Add it to the Stack
88
89 Yield the class from your Stack and return its URL:
90
91 ```typescript
92 // alchemy.run.ts
93 import * as Alchemy from "alchemy";
94 import * as Effect from "effect/Effect";
95
96 export default Alchemy.Stack(
97 "MyNuxtSite",
98 {
99 providers: Cloudflare.providers(),
100 state: Cloudflare.state(),
101 },
102 Effect.gen(function* () {
103 const site = yield* Website;
104 return { url: site.url };
105 }),
106 );
107 ```
108
109 The server build uses nitro's hybrid workerd Node compatibility, so
110 the `nodejs_compat` compatibility flag is added automatically — you
111 don't need to pass it.
112
113 See
114 [examples/cloudflare-website-nuxt](https://github.com/alchemy-run/alchemy/tree/main/examples/cloudflare-website-nuxt)
115 for the checked-in example.
116
117 ## Add bindings
118
119 The resource returns a plain `Worker`, so `env` accepts the full
120 binding vocabulary — KV namespaces, R2 buckets, Durable Objects,
121 secrets:
122
123 ```diff lang="typescript"
124 // alchemy.run.ts
125 +import * as Config from "effect/Config";
126
127 +export const Uploads = Cloudflare.R2.Bucket("Uploads");
128
129 export const Website = Cloudflare.Website.Nuxt("Website", {
130 + env: {
131 + UPLOADS: Uploads,
132 + API_KEY: Config.Redacted("API_KEY"),
133 + },
134 });
135 ```
136
137 `Uploads` is a description, not a deploy — Alchemy provisions the
138 real bucket because the Website binds it. `Config.Redacted` reads
139 `API_KEY` from your environment at deploy time and binds it as a
140 Worker secret — see [Secrets & env](/cloudflare/security/secrets-env).
141
142 ## Read bindings in server code
143
144 Server routes and SSR read bindings through nitro's Cloudflare
145 runtime contract, `event.context.cloudflare.env`. Type it once by
146 augmenting h3's event context with the inferred env type:
147
148 ```typescript
149 // server/types.d.ts
150 import type { WebsiteEnv } from "../alchemy.run.ts";
151
152 declare module "h3" {
153 interface H3EventContext {
154 cloudflare: {
155 env: WebsiteEnv;
156 };
157 }
158 }
159 ```
160
161 Every server route now gets fully typed bindings:
162
163 ```typescript
164 // server/api/upload.ts
165 export default defineEventHandler(async (event) => {
166 const uploads = event.context.cloudflare.env.UPLOADS;
167 await uploads.put("hello.txt", "Hello!");
168 return { ok: true };
169 });
170 ```
171
172 `event.context.cloudflare.env.UPLOADS` is typed as an R2 bucket and
173 `.API_KEY` as a string — renaming a binding in `alchemy.run.ts` is a
174 type error in your routes. `event.context.cf` and
175 `event.context.cloudflare.context.waitUntil` are available the same
176 way.
177
178 ## Prerendering
179
180 Routes marked for prerendering in `routeRules` (or via
181 `nitro.prerender`) render at build time into `.output/public` and are
182 served as static assets, with no Worker invocation. Configure them in
183 your `nuxt.config.ts`, which loads natively:
184
185 ```typescript
186 // nuxt.config.ts
187 export default defineNuxtConfig({
188 routeRules: {
189 "/about": { prerender: true },
190 },
191 });
192 ```
193
194 Nitro's `isr` route rule is implemented only by the Vercel and
195 Netlify presets. On Cloudflare it is silently ignored at build time,
196 and the route renders on demand in the Worker like any other SSR
197 route. Use `prerender` for build-time static routes, or `cache` route
198 rules for runtime caching.
199
200 ## Custom Worker exports (Durable Objects)
201
202 Nitro's entry module is the Worker's exports seam. Point `main` at
203 your own module that re-exports nitro's runtime handler and adds
204 extra exports — Durable Object classes must live on the deployed
205 Worker for their namespace bindings to resolve:
206
207 ```typescript
208 // worker-entry.ts
209 import nitroHandler from "nitropack/presets/cloudflare/runtime/cloudflare-module";
210 export class Counter extends DurableObject {}
211 export default nitroHandler;
212 ```
213
214 ```typescript
215 export const Website = Cloudflare.Website.Nuxt("Website", {
216 main: "worker-entry.ts",
217 env: {
218 COUNTER: Cloudflare.DurableObject("Counter", {
219 className: "Counter",
220 }),
221 },
222 });
223 ```
224
225 Every framework route keeps working through the re-exported handler.
226
227 ## Local dev
228
229 ```sh
230 bun alchemy dev
231 ```
232
233 `alchemy dev` runs Nuxt's own dev server (nitro dev, full HMR) with
234 the Worker's real bindings served on `event.context.cloudflare` —
235 wrangler-free, through the cloudflare-runtime platform proxy.
236 Resource bindings (KV, R2, D1) round-trip to a local workerd
237 instance, so dev state is live and shared; literal `env` values
238 overlay the proxied bindings. Your server code is identical in dev
239 and production.
240
241 One limitation: Durable Object classes declared via a custom `main`
242 entry only exist in the production build, so they are not servable in
243 dev yet.