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

main
mdx 159 lines 4.5 KB
Raw
1 ---
2 title: Next.js
3 description: "Deploy a Next.js app to Hetzner with Hetzner.Website.Nextjs — next build plus a Node next({ dev: false }) systemd unit, and next dev under alchemy dev."
4 sidebar:
5 order: 9
6 ---
7
8 import PackageManagers from "../../../../components/PackageManagers.astro";
9
10 export const devDeps = "@alchemy.run/frontend-frameworks";
11
12 `Hetzner.Website.Nextjs` deploys a [Next.js](https://nextjs.org) app
13 to a Hetzner Cloud Server. It runs a real `next build`, then a
14 long-running `next({ dev: false })` systemd unit on port 3000:
15
16 - one [`Hetzner.Server`](/hetzner/compute/servers) (default `cpx12`
17 / `ubuntu-24.04` / `fsn1` when `server` is omitted) and a
18 [`Hetzner.Service`](/hetzner/compute/services) as a systemd unit
19 - live URL `http://{ipv4}:3000`
20 - `.next` and `public/` packed into the unit archive; `next`,
21 `react`, and `react-dom` installed with `bun install`
22
23 This is **not** OpenNext — those wrappers target Lambda and workerd.
24 ISR and `next/image` use Next's own Node behavior. Several sites and
25 APIs can share one Server.
26
27 App Router and Pages Router both work — server components, API
28 routes, middleware, server actions, dynamic segments, streaming SSR,
29 and `getServerSideProps` pages all run in the Node process.
30
31 ## Install
32
33 The build integration is not bundled with alchemy. Install
34 `@alchemy.run/frontend-frameworks`; the resource loads the package's
35 `/nextjs/node` export from your project at deploy time. It is only
36 used at build time, so a dev dependency is enough. Your app still
37 needs `next`, `react`, and `react-dom` as usual:
38
39 <PackageManagers dev={devDeps} />
40
41 ## Configure Next.js
42
43 Your `next.config.*` is loaded and honored as-is — the build runs a
44 real `next build`, and Alchemy never rewrites the file. There is no
45 adapter to install and no `open-next.config.ts` to write.
46
47 Pass `rootDir` when the Next.js project is not the stack root.
48
49 ## Declare the Website
50
51 Declare the site as a module-level const (rather than inline in the
52 Stack):
53
54 ```typescript
55 // alchemy.run.ts
56 import * as Hetzner from "@alchemy.run/hetzner";
57
58 export const Website = Hetzner.Website.Nextjs("Website");
59 ```
60
61 ## Add it to the Stack
62
63 Yield the site from your Stack and return its URL:
64
65 ```typescript
66 // alchemy.run.ts
67 import * as Alchemy from "alchemy";
68 import * as Effect from "effect/Effect";
69
70 export default Alchemy.Stack(
71 "MyNextjsSite",
72 {
73 providers: Hetzner.providers(),
74 state: Alchemy.localState(),
75 },
76 Effect.gen(function* () {
77 const site = yield* Website;
78 return { url: site.url };
79 }),
80 );
81 ```
82
83 `url` is `http://{ipv4}:3000` on deploy. `server` and `service` are
84 set then and `undefined` under `alchemy dev`.
85
86 Pass an existing Server so the Next unit shares the VM with other
87 Services:
88
89 ```typescript
90 export const Website = Hetzner.Website.Nextjs("Website", {
91 server: Box,
92 });
93 ```
94
95 ## Add environment variables
96
97 Process environment is the top-level `env` prop — plain strings, or
98 `Redacted` secrets:
99
100 ```diff lang="typescript"
101 // alchemy.run.ts
102 export const Website = Hetzner.Website.Nextjs("Website", {
103 + env: {
104 + GREETING: "Hello from Alchemy!",
105 + API_BASE: "https://api.example.com",
106 + },
107 });
108 ```
109
110 The values are copied onto `process.env` before `next build` /
111 `next dev`, and onto the systemd unit at deploy, so server code and
112 `NEXT_PUBLIC_*` inlining see the same map in both modes.
113
114 ## Read the environment in server code
115
116 The Next server is a plain Node process, so route handlers, server
117 components, and server actions read the environment from
118 `process.env`:
119
120 ```typescript
121 // app/api/hello/route.ts
122 export function GET() {
123 return Response.json({ greeting: process.env.GREETING ?? "hello" });
124 }
125 ```
126
127 ## Local dev
128
129 ```sh
130 bun alchemy dev
131 ```
132
133 `alchemy dev` runs `next dev` (native HMR, Turbopack) instead of
134 deploying; `site.url` is the local address and no Hetzner resources
135 are created. Wrap the site in `Alchemy.remote()` to deploy the live
136 Service even during dev.
137
138 ## Custom domain
139
140 ```typescript
141 const site = yield* Hetzner.Website.Nextjs("Web", {
142 domain: "app.example.com",
143 zone,
144 });
145 ```
146
147 `domain` requires an existing [`Hetzner.Zone`](/hetzner/networking/dns)
148 — v1 does not create one, and passing `domain` without `zone` fails.
149 Alchemy creates an A RecordSet pointing at the Server's public IPv4.
150 `url` becomes `http://app.example.com:3000`. There is no TLS on the
151 Service.
152
153 ## Where next
154
155 - [`Hetzner.Website.Nextjs` reference](/providers/hetzner/website/nextjs)
156 — every prop and attribute
157 - [Servers](/hetzner/compute/servers),
158 [Services](/hetzner/compute/services),
159 [DNS](/hetzner/networking/dns)