@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 202 lines 5.59 KB
Raw
1 ---
2 title: Nuxt
3 description: Deploy a Nuxt app to Hetzner with Hetzner.Website.Nuxt — nitro's node preset as a systemd unit on port 3000, 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 `Hetzner.Website.Nuxt` deploys a [Nuxt](https://nuxt.com) app to a
13 Hetzner Cloud Server. It builds the app through your project's own
14 `@nuxt/kit` with nitro's `node` preset: the nitro Node server runs
15 as a systemd unit on port 3000, and client assets plus prerendered
16 pages are baked into the unit. Omit `server` to get a `cpx12` /
17 `ubuntu-24.04` VM in `fsn1`. The live URL is `http://{ipv4}:3000` —
18 the Service has no TLS. There is no `nitro.preset` to edit and no
19 build command to run.
20
21 ## Install
22
23 The build integration is not bundled with alchemy. Install
24 `@alchemy.run/frontend-frameworks`; the resource loads its `/nuxt`
25 and `/nuxt/node` exports from your project at deploy time. It is
26 only used at build time, so a dev dependency is enough:
27
28 <PackageManagers dev={devDeps} />
29
30 ## Configure Nuxt
31
32 Your `nuxt.config.ts` loads natively — modules, layers, and all —
33 so configure Nuxt exactly as you would outside Alchemy:
34
35 ```typescript
36 // nuxt.config.ts
37 export default defineNuxtConfig({
38 modules: ["@nuxtjs/tailwindcss"],
39 routeRules: {
40 "/about": { prerender: true },
41 },
42 });
43 ```
44
45 Deploy-specific overrides are merged over it via the `nuxt` prop
46 (the override wins) — see [Prerendering](#prerendering) below for an
47 example.
48
49 Don't set `nitro.preset` — the Node deploy target owns the preset
50 (`"node"`), and a foreign preset is a hard error.
51
52 ## Declare the Website
53
54 Declare the site as a module-level const (rather than inline in the
55 Stack):
56
57 ```typescript
58 // alchemy.run.ts
59 import * as Hetzner from "@alchemy.run/hetzner";
60
61 export const Website = Hetzner.Website.Nuxt("Website");
62 ```
63
64 Pass `rootDir` if `package.json` is not at `.`. Pass `server` to
65 run the unit on a Server you already declared — several sites and
66 APIs can share one VM. Otherwise the site creates a `cpx12` /
67 `ubuntu-24.04` Server in `fsn1`.
68
69 ```typescript
70 export const Box = Hetzner.Server("Box", {
71 serverType: "cpx12",
72 image: "ubuntu-24.04",
73 location: "fsn1",
74 });
75
76 export const Website = Hetzner.Website.Nuxt("Website", {
77 server: Box,
78 });
79 ```
80
81 ## Add it to the Stack
82
83 Yield the site from your Stack and return its URL:
84
85 ```typescript
86 // alchemy.run.ts
87 import * as Alchemy from "alchemy";
88 import * as Effect from "effect/Effect";
89
90 export default Alchemy.Stack(
91 "MyNuxtSite",
92 {
93 providers: Hetzner.providers(),
94 state: Alchemy.localState(),
95 },
96 Effect.gen(function* () {
97 const site = yield* Website;
98 return { url: site.url };
99 }),
100 );
101 ```
102
103 On deploy `site.url` is `http://{ipv4}:3000` (or
104 `http://{domain}:3000` when you set `domain`). `site.server` and
105 `site.service` are undefined under `alchemy dev`.
106
107 ## Add environment variables
108
109 Process environment is the top-level `env` prop — plain strings, or
110 `Redacted` values. They are copied onto `process.env` before build
111 and `alchemy dev`, and onto the systemd unit at deploy:
112
113 ```diff lang="typescript"
114 // alchemy.run.ts
115 export const Website = Hetzner.Website.Nuxt("Website", {
116 + env: {
117 + GREETING: "Hello from Alchemy!",
118 + NUXT_PUBLIC_API_BASE: "https://api.example.com",
119 + },
120 });
121 ```
122
123 This is the hosted Node process, not Worker bindings.
124 `NUXT_`-prefixed keys override Nuxt `runtimeConfig` the usual way;
125 `NUXT_PUBLIC_` values are inlined into the client at build time.
126
127 ## Read the environment in server code
128
129 The nitro server is a plain Node process, so server routes and SSR
130 read the environment from `process.env`:
131
132 ```typescript
133 // server/api/hello.ts
134 export default defineEventHandler(() => {
135 return { greeting: process.env.GREETING ?? "hello" };
136 });
137 ```
138
139 ## Prerendering
140
141 Routes marked for prerendering in `routeRules` (or via
142 `nitro.prerender`) render at build time into `.output/public` and
143 are baked into the unit, served as static files before the nitro
144 handler:
145
146 ```typescript
147 export const Website = Hetzner.Website.Nuxt("Website", {
148 nuxt: {
149 routeRules: {
150 "/about": { prerender: true },
151 },
152 },
153 });
154 ```
155
156 Nitro's `isr` route rule is implemented only by the Vercel and
157 Netlify presets. On the Node preset it is silently ignored at build
158 time, and the route renders on demand like any other SSR route. Use
159 `prerender` for build-time static routes, or `cache` route rules for
160 runtime caching.
161
162 ## Local dev
163
164 ```sh
165 bun alchemy dev
166 ```
167
168 `alchemy dev` runs Nuxt's own dev server (nitro dev, full HMR)
169 instead of deploying; `site.url` is the local address and no
170 Hetzner resources are created. Wrap the site in `Alchemy.remote()`
171 to deploy the live Server and Service even during dev.
172
173 ## Custom domain
174
175 `domain` requires an existing [`Hetzner.Zone`](/hetzner/networking/dns)
176 — the Website does not create a zone. It adds an A RecordSet
177 pointing at the Server's public IPv4, and `url` becomes
178 `http://{domain}:3000`. There is no TLS on the Service:
179
180 ```typescript
181 export const Dns = Hetzner.Zone("Dns", {
182 name: "example.com",
183 });
184
185 export const Website = Hetzner.Website.Nuxt("Website", {
186 domain: "app.example.com",
187 zone: Dns,
188 });
189 ```
190
191 Passing `domain` without `zone` fails.
192
193 ## Where next
194
195 - [`Hetzner.Website.Nuxt` reference](/providers/hetzner/website/nuxt)
196 — every prop and attribute.
197 - [Services](/hetzner/compute/services) and
198 [Servers](/hetzner/compute/servers) — the unit and VM the site
199 creates.
200 - [Zones & records](/hetzner/networking/dns) — the Zone `domain`
201 requires.
202 - [Setup](/hetzner/setup) — project, API token, and alchemy login.