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

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