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

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