Build-Time or Runtime Environment Variables for Railway Frontend Config

Direct Answer

Mark NEXT_PUBLIC_ variables as build (or both) in Railway. Runtime-only will leave them undefined in the client bundle because Next.js inlines public variables at build time. The requirement is the same for Nixpacks and custom Dockerfiles, but the mechanism differs.

Why Build-Time Is Required

Next.js replaces process.env.NEXT_PUBLIC_* references with literal values during next build. If the variable is not present in the build environment, the replacement cannot happen and the browser sees undefined. This is a Next.js compile-time behavior, not a Railway-specific quirk.

Nixpacks Deployment

Railway's Nixpacks builder injects all variables flagged build or both into the build container before running next build. Marking the variable build (or both) in the Railway dashboard is sufficient.

Custom Dockerfile Deployment

Marking the variable build in the Railway UI makes it available as a build argument, but your Dockerfile must explicitly consume it:

# Dockerfile
ARG NEXT_PUBLIC_API_URL
ENV NEXT_PUBLIC_API_URL=$NEXT_PUBLIC_API_URL

RUN next build

Without the ARG and ENV lines, the variable exists in the build context but is not passed to the next build command. Runtime-only flags have no effect here because the build step has already completed.

Verification Steps

1. Check the Railway build log for the frontend build step; search for the variable name to confirm it was inlined.
2. Run next build locally with the same variable set and compare the generated .next/ output.
3. After deploy, open the browser console and inspect process.env.NEXT_PUBLIC_YOUR_VAR — presence confirms successful inlining.

One Diagnostic Detail

Are you using Nixpacks (auto-detected) or a custom Dockerfile in the repository root? The answer above covers both, but the Dockerfile must be updated as shown if you are using a custom one.