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