Environment, Configuration, Deploying and Production Habits

A Next.js app has many settings: secrets, URLs, flags, headers, image rules, and the way you start the server. Most are easy. A few have sharp edges that cause real incidents: a secret that reaches the browser, a "production URL" that is frozen at the wrong value, or a Docker image that works on your laptop and fails in the cluster. This lesson goes through them in the order you meet them, and proves each claim.

This is lesson 8 of ten. Lesson 7 needed a site URL for metadataBase. Here you will see where that URL should come from. The next lesson, Next.js Interview Questions With Model Answers, uses everything in this series. For Docker itself (layers, caching, volumes), see Writing a Dockerfile. Here I only show the Next.js parts of a Dockerfile.

Words used in this lesson

• Environment variable is a named value that lives outside your code, such as DATABASE_URL. Programs read it at start or at run time.
• .env file is a text file with NAME=value lines. Next.js reads it into process.env.
• Build time is when you run next build. Run time is when the server runs and answers requests.
• Inline means to replace a variable with its value inside the code at build time, like find and replace.
• NEXT_PUBLIC_ is a name prefix. Variables that start with it are inlined into the JavaScript sent to the browser.
• Secret is a value that must stay private: a database password, an API key, a session signing key.
• next.config.ts is the settings file at the root of a Next.js project.
• Standalone output is a build mode (output: 'standalone') that makes a small folder with only the files needed to run the server.
• Output file tracing means Next.js follows your imports to find which files each page needs, so it can copy only those.
• Docker image is a packaged app plus its runtime. A container is a running copy of an image.
• Multi-stage build is a Dockerfile that uses several FROM steps, so the final image does not carry build tools.
• Instrumentation is code that sets up logging and monitoring when the server starts. The file is instrumentation.ts.
• Health check is a small endpoint that says "I am alive", used by a platform to decide if a container is working.
• Version skew means a browser running old code talks to a server running new code, after a deployment.

Environment variables: the load order

Next.js reads .env files for you. You do not need the dotenv package. The docs say the lookup goes in this order and stops at the first match:

1. process.env (the variables that are really set in the shell or the platform)
2. .env.$(NODE_ENV).local
3. .env.local (not read when NODE_ENV is test)
4. .env.$(NODE_ENV)
5. .env

NODE_ENV is development for next dev and production for next build and next start. Let me prove the order. I made three files, and put the same name, SHARED, in each:

.env              GREETING=from-.env             SHARED=env.env.production   SHARED=env.production          NEXT_PUBLIC_API_URL=https://api.prod.example.com.env.local        SECRET_TOKEN=sk_live_super_secret_123                  NEXT_PUBLIC_BUILD_LABEL=label-from-env-local                  SHARED=env.local

(The sk_live_... value is made up for this lab.) next build told me which files it loaded, in order:

- Environments: .env.local, .env.production, .env

And a static page that prints GREETING and SHARED showed:

GREETING=from-.env SHARED=env.local (read while building)

GREETING exists only in .env, so it came from there. SHARED is in all three files, and .env.local won. Good: .env.local is meant for your own machine and for secrets. The create-next-app template adds .env*.local to .gitignore. This blog's .gitignore has the same line. The docs say you almost never want to commit these files.

Server variables and NEXT_PUBLIC_ variables

Here is the rule from the docs: by default, an environment variable exists only on the server. If you want the browser to see it, you must start its name with NEXT_PUBLIC_. Next.js then inlines the value into the JavaScript during next build.

Let me show both halves in a real browser. I made a Client Component that prints three variables:

'use client'// app/leak/client.tsx (shortened)setTxt(JSON.stringify({  NEXT_PUBLIC_API_URL: process.env.NEXT_PUBLIC_API_URL,  NEXT_PUBLIC_BUILD_LABEL: process.env.NEXT_PUBLIC_BUILD_LABEL,  SECRET_TOKEN: process.env.SECRET_TOKEN,}))

Then I opened the page with Playwright and read what the browser printed:

{"NEXT_PUBLIC_API_URL":"https://api.prod.example.com","NEXT_PUBLIC_BUILD_LABEL":"label-from-env-local"}

Two keys, no SECRET_TOKEN. (JSON.stringify leaves out undefined, so the secret was undefined in the browser.) So a plain variable did not leak. I also searched the build output for the secret:

secret in .next/static: 0 files

Zero files in the folder that is sent to browsers. Good.

Two warnings here.

First: the failure is silent. If you forget the prefix on a value the browser needs, you do not get an error. You get undefined, and a bug that shows up only in the browser. In the other direction, putting NEXT_PUBLIC_ on a secret is a leak. The name is the only guard. Review any NEXT_PUBLIC_ name as if it were printed on the page, because it is.

Second: a good guard exists for server code. Put import 'server-only' at the top of a file that uses secrets. If a Client Component imports it, even by accident, the build fails. I tested it, and the real output was:

Error: 'server-only' cannot be imported from a Client Component module> 1 | import 'server-only'It should only be used from a Server Component.Import traces:  Client Component Browser:    ./a8/lib/secret.ts [Client Component Browser]    ./a8/app/leak2/page.tsx [Client Component Browser]

(You also saw this in lesson 5.) The docs also mention a taint option for marking a value as not allowed to reach the client. I did not test it.

"Build time" is the trap

Now the part that surprises people. I started the production server with different values from the ones I built with:

GREETING=changed-at-start SHARED=changed-at-start \NEXT_PUBLIC_API_URL=https://runtime-override.example.com next start -p 3109

And then I asked for three things.

static:  GREETING=from-.env SHARED=env.local (read while building)runtime: GREETING=changed-at-start SHARED=changed-at-start (read per request)

• The static page still showed the old values. It was built during next build, with the variables of that moment, and the file does not change.
• The runtime page showed the new values. It is dynamic (it calls await connection()), so it reads process.env on each request. A real environment variable beats the .env files, as the load order says.

And the browser variable:

files in .next/static with the build-time URL (api.prod.example.com):   1files in .next/static with the runtime URL (runtime-override):           0

The NEXT_PUBLIC_API_URL I gave at start time was ignored. The browser code still had the value from the build. This is exactly what the docs say: after the build, the app no longer responds to changes in NEXT_PUBLIC_ variables. If you build one Docker image and promote it from "staging" to "production", the browser code will still point to the staging URL.

So there are two kinds of values, and you must keep them straight:

The docs give two ways out for "I need one image for many environments": (1) read the value on the server during dynamic rendering, after calling connection() (or any request API), and pass it to the browser as a prop, or (2) serve a small API that returns the config. The doc comment says it plainly: the variable is read at run time "meaning this env variable is evaluated at runtime".

next.config.ts: what lives there

next.config.ts (or .js, .mjs) is in the project root. It exports an object. Most settings you will use fall into a few groups:

• Headers, redirects, rewrites. (headers(), redirects(), rewrites(). Lesson 4 covers redirects and rewrites.)
• Images. images.remotePatterns, formats, qualities. (Lesson 7.)
• Output. output: 'standalone' or 'export'.
• Caching model. cacheComponents: true. (Lessons 2 and 6.)
• Server Actions. serverActions.allowedOrigins. (Lesson 5.)
• Small switches. poweredByHeader, reactStrictMode, typedRoutes, experimental.*.

The config file runs only when the build or the server starts, so it can read process.env. I saw ✓ Running next.config.ts took 51ms in the output each time.

Headers are the most useful production setting. Mine:

const nextConfig: NextConfig = {  output: 'standalone',  poweredByHeader: false,  async headers() {    return [{ source: '/:path*', headers: [      { key: 'X-Content-Type-Options', value: 'nosniff' },      { key: 'Referrer-Policy', value: 'strict-origin-when-cross-origin' },    ] }]  },}

What curl -i saw:

X-Content-Type-Options: nosniffReferrer-Policy: strict-origin-when-cross-origin

and there was no X-Powered-By: Next.js header, because poweredByHeader: false. That header tells everyone which framework you run, which helps attackers a little and helps you not at all.

This blog's next.config.ts is a nice real example of production headers. It sets a Content-Security-Policy (CSP), X-Frame-Options: DENY, X-Content-Type-Options: nosniff, Referrer-Policy, Strict-Transport-Security, Permissions-Policy and Cross-Origin-Opener-Policy. It turns the CSP off in development, because the dev tools need more than a strict policy allows. And a comment explains a trade-off: a per-request CSP nonce would force every page to be dynamic, so this fully static site allows inline scripts and limits the external origins instead. For the theory behind each header, see XSS, CSRF, Clickjacking and Security Headers and Frontend Security Checklist.

Build and run

Two commands, always in this order:

npm run build     # next build: makes the production output in .next/npm run start     # next start: serves it

next build prints the route table you know from the other lessons. It also type-checks your code and fails on errors, so run it in CI. The docs' production checklist says to run next build and next start locally before going live, because dev mode hides caching and performance.

Here is my build output for the lab app, shortened:

▲ Next.js 16.3.5 (Turbopack)- Environments: .env.local, .env.production, .env✓ Compiled successfully in 275msRoute (app)┌ ○ /├ ○ /_not-found├ ƒ /api/boom├ ƒ /api/health├ ○ /leak├ ƒ /runtime└ ○ /static

Warning: A Node.js API is used (process.pid at line: 4) which is not supported in the Edge Runtime.

Three ways to run it

1. next start

The simplest. You copy the project, run npm ci, npm run build, npm run start. It needs the whole node_modules folder (mine is 402 MB here). The docs say this server supports all Next.js features. It reads the PORT variable (or -p). The docs recommend putting a reverse proxy such as nginx in front, to handle slow clients, payload limits and rate limits.

2. Standalone output

With output: 'standalone', next build makes a folder .next/standalone with only the files the server needs. It uses output file tracing: it follows your imports and copies just those files and the used parts of node_modules. Compare the sizes:

67M   .next/standalone592K  .next/static402M  node_modules (the full dev install)

A 67 MB folder instead of 402 MB. It contains a tiny server.js. You start it with node server.js, not next start. I saw a message about this:

⚠ "next start" does not work with "output: standalone" configuration. Use "node .next/standalone/server.js" instead.

(In my test, next start still answered requests, but I would follow the warning.) Two more things from the docs that I checked:

• The standalone folder does not copy public/ or .next/static, because a CDN should serve them. If you serve them from the same server, you copy them yourself. I copied them and ran:

cp -r public .next/standalone/a8/cp -r .next/static .next/standalone/a8/.next/cd .next/standalone/a8 && PORT=3110 HOSTNAME=127.0.0.1 GREETING=standalone-run node server.js

▲ Next.js 16.3.5- Local:         http://127.0.0.1:3110✓ Ready in 0ms[instrumentation] register() runs once at server start, pid 3956

$ curl localhost:3110/api/health{"ok":true,"node":"v22.22.0","uptimeSeconds":2}$ curl localhost:3110/runtime      ->  GREETING=standalone-run SHARED=env.production (read per request)static asset: 200

PORT and HOSTNAME control where it listens. GREETING=standalone-run was read at run time, as expected.

• Look at the path: .next/standalone/a8/server.js, not .next/standalone/server.js. My lab app lives in a subfolder of a folder with its node_modules, so Next.js used the parent as the tracing root and kept the folder name. In a monorepo the docs say to set outputFileTracingRoot, and the tracing root decides where server.js ends up. If you cannot find server.js, look here first.

And an important detail about env files: in the standalone folder, I found .env and .env.production, but not .env.local. The server printed SHARED=env.production, not env.local. So the secrets in .env.local were not there. I did not dig into why. The lesson is to never depend on .env files in an image or a server. Set real environment variables in the platform.

3. A Docker image

The docs say Docker supports all features and show the standalone pattern. Here is the Dockerfile I used. It has three stages: install, build, and a small runtime image:

# syntax=docker/dockerfile:1FROM node:22-alpine AS depsWORKDIR /appCOPY package.json package-lock.json ./RUN npm ciFROM node:22-alpine AS buildWORKDIR /appCOPY --from=deps /app/node_modules ./node_modulesCOPY . .# NEXT_PUBLIC_* values are frozen into the browser JS here, at build time.ARG NEXT_PUBLIC_API_URL=https://api.example.comENV NEXT_PUBLIC_API_URL=$NEXT_PUBLIC_API_URLRUN npm run buildFROM node:22-alpine AS runWORKDIR /appENV NODE_ENV=productionENV PORT=3000ENV HOSTNAME=0.0.0.0RUN addgroup -S app && adduser -S app -G appCOPY --from=build --chown=app:app /app/.next/standalone ./COPY --from=build --chown=app:app /app/.next/static ./.next/staticCOPY --from=build --chown=app:app /app/public ./publicUSER appEXPOSE 3000CMD ["node", "server.js"]

The key points:

• Three stages. The final image has no build tools, no source and no dev dependencies. Only the standalone output.
• ARG for NEXT_PUBLIC_. These must be known at build time. A docker run -e NEXT_PUBLIC_X=... is too late. I will prove it below.
• HOSTNAME=0.0.0.0. Inside a container, the server must listen on all interfaces, or you cannot reach it from outside.
• A non-root user. USER app, so a bug in the app does not run as root.
• A .dockerignore with node_modules, .next, .env.local and .git, so you do not send your secrets and your local build into the build context.

I built it:

docker build ... -t nb-lab:1 ....#16 [run 4/6] COPY --from=build --chown=app:app /app/.next/standalone ./#17 [run 5/6] COPY --from=build --chown=app:app /app/.next/static ./.next/static#18 [run 6/6] COPY --from=build --chown=app:app /app/public ./public#19 naming to docker.io/library/nb-lab:1 done      (about 48 seconds on a cold cache)

IMAGE      DISK USAGE   CONTENT SIZEnb-lab:1   332MB        84.9MBnode:22-alpine  238MB   61.1MB          (the base image alone)

The app adds about 94 MB on disk to the 238 MB base image. Now I ran it, and passed runtime variables, including a different NEXT_PUBLIC_API_URL:

docker run -d --name nb-run --network host \  -e PORT=3111 -e GREETING=from-docker-run \  -e NEXT_PUBLIC_API_URL=https://changed-at-run.example.com nb-lab:1

▲ Next.js 16.3.5- Local:         http://localhost:3111- Network:       http://0.0.0.0:3111✓ Ready in 0ms[instrumentation] register() runs once at server start, pid 1

$ curl localhost:3111/api/health{"ok":true,"node":"v22.23.3","uptimeSeconds":3}$ curl localhost:3111/runtime   ->  GREETING=from-docker-run SHARED=env.production (read per request)whoami inside the container:    appfiles in /app/.next/static with the build ARG url (api.example.com): 1files in /app/.next/static with the runtime -e url (changed-at-run): 0

Everything matches what I proved earlier:

• The container ran as user app, not root.
• GREETING, a server variable, was read at run time from -e.
• The browser variable was not changed by -e. It stayed at the value from the build.
• The server started as process pid 1, so signals (like a stop request) reach it directly.

What I did not test: Kubernetes, health probes against this image, or running several copies of the container at once. The docs warn about three things there: the default cache is kept per instance (in memory and on disk), so a revalidation on one pod does not reach the others unless you configure a shared cache handler; all instances must share the same Server Actions encryption key (NEXT_SERVER_ACTIONS_ENCRYPTION_KEY), or users get "Failed to find Server Action" errors after a request lands on another instance; and a rolling deploy needs a deploymentId for version-skew protection, so old browsers do not request files that new servers no longer have.

Deploying to a platform

The docs list four options: a Node.js server (all features), a Docker container (all features), a static export (limited), and adapters for platforms. Vercel and Bun have verified adapters, according to the page I read. They also list templates for many hosts (Railway, Fly.io, Google Cloud Run, Render, DigitalOcean and others).

On a platform like Vercel, you connect the Git repository, the platform runs next build for you, and it serves static files from a CDN and runs dynamic routes as functions. You set environment variables in the platform's dashboard, per environment (production, preview). The platform also sets its own variables. This blog reads VERCEL_ENV and VERCEL_PROJECT_PRODUCTION_URL from them. I did not deploy anything, so I cannot show you output.

A static export (output: 'export') builds plain HTML, CSS and JS files that any web server can host, such as S3. The docs say it does not support features that need a server. That includes proxy.ts and server rendering per request. I did not run one. If your site is a pure blog, it is worth asking if you need more than that.

A last point from the docs' rendering guide: the finer-grained rendering model of Next.js (streaming, partial prerendering, on-demand revalidation) moves some complexity into the hosting platform. A single Node.js process supports every feature. Streaming needs the proxies and CDNs in front of it not to buffer the response. Nginx and similar proxies buffer by default, and the docs say to send the header X-Accel-Buffering: no to turn that off. If your streamed page seems to arrive all at once in production but not locally, look for a buffering proxy.

Logging and monitoring

When a production server breaks, you have two questions: what happened, and how often? Next.js gives you one hook for the first: instrumentation.ts in the project root. It can export two functions:

• register() runs once, when a new server instance starts, before it takes requests. Use it to start your monitoring SDK. The docs show registerOTel('next-app') from @vercel/otel for OpenTelemetry.
• onRequestError(error, request, context) runs when the server captures an error. Use it to send errors to your error tracker.

Mine just prints to the console. I also made a route that throws, to trigger it:

// instrumentation.tsexport function register() {  if (process.env.NEXT_RUNTIME === 'nodejs') console.log('[instrumentation] register() runs once at server start, pid', process.pid)}export const onRequestError: Instrumentation.onRequestError = async (err, request, context) => {  const message = err instanceof Error ? err.message : String(err)  console.log('[instrumentation] onRequestError', JSON.stringify({ message, path: request.path, method: request.method, routeType: context.routeType, routePath: context.routePath }))}

$ curl -s -o /dev/null -w "%{http_code}\n" localhost:3109/api/boom500

and the server log:

[instrumentation] register() runs once at server start, pid 3723⨯ Error: boom from route handler    at <unknown> (.next/server/chunks/[root-of-the-server]__0q20b9r._.js:1:1073)[instrumentation] onRequestError {"message":"boom from route handler","path":"/api/boom","method":"GET","routeType":"route","routePath":"/api/boom"}

The hook got the message, the path, the method and, from context, that it was a route (not a page render or an action). In a real app, you would send that to an error tracker. The docs warn that the error object may not be the original: React can change it during Server Component rendering, and you can use its digest to match it to the log line. They also say to await any async work inside the hook.

Other habits that need almost no code:

• A health endpoint. I made app/api/health/route.ts with export const dynamic = 'force-dynamic'. It returned {"ok":true,"node":"v22.22.0","uptimeSeconds":7}. A platform can call it to see if the process is alive. Keep it cheap: do not make it call your database unless you also want "ready" checks.
• Log to stdout. In a container, console.log goes to the platform's log system. Do not write log files inside the container.
• Web vitals from real users. Use the useReportWebVitals hook (lesson 7).
• Do not log secrets. A request header or an environment object can contain them. See Logging and Observability.

A short production checklist

This is my own list, based on what I proved above and on the docs' checklist. Tick each one before you go live.

1. next build passes in CI, and I read the route table. Each route is what I expect.
2. I ran next start (or the standalone server, or the image) and clicked through. Not just next dev.
3. No secret has a NEXT_PUBLIC_ name. Files that use secrets import server-only.
4. .env*.local is in .gitignore. No .env file is needed inside the image. Real variables are set on the platform.
5. Every NEXT_PUBLIC_ value is correct at build time for that environment.
6. Metadata has metadataBase, and previews are not indexable.
7. Security headers are set (headers() or a CDN), and poweredByHeader is off.
8. Images have sizes and remotePatterns. Fonts come from next/font.
9. app/error.tsx, app/not-found.tsx and app/global-error.tsx exist (the docs recommend a global error page and a global 404).
10. Errors reach my tracker through onRequestError, or an SDK in register().
11. Multiple instances: shared cache handler, same encryption key, a deploymentId.
12. A buffering proxy does not break streaming.
13. The container runs as a non-root user, listens on 0.0.0.0, and I know how it is stopped.

Common mistakes

• Using NEXT_PUBLIC_ on a secret.
• Forgetting the prefix on a value the browser needs, and getting undefined.
• Expecting docker run -e NEXT_PUBLIC_X=... to change browser code.
• Reading process.env in a static page and expecting it to follow the environment at run time.
• Committing .env.local, or copying it into an image.
• Using process.env[name] with a variable name for a public variable.
• HOSTNAME not set to 0.0.0.0 in a container, so the app is not reachable.
• Forgetting to copy public/ and .next/static next to a standalone server.js and no CDN serving them.
• A single Dockerfile stage that keeps all of node_modules and the source in the final image.
• Running several instances with the default per-instance cache and expecting revalidateTag to reach all of them.
• Putting Node-only code in instrumentation.ts without the NEXT_RUNTIME check.
• Testing production behavior only in dev.

Try it

1. Make .env, .env.production and .env.local, each with SHARED= and a different value. Run next build and look at the line that starts with Environments:. Which value does a static page show?
2. Make a static page and a page that calls await connection() that both print process.env.GREETING. Build, then start with GREETING=new npm run start. Which page changes?
3. Make a Client Component that prints process.env.NEXT_PUBLIC_X and process.env.SECRET_X. What does the browser show for each?
4. Build with NEXT_PUBLIC_X=one, then start with NEXT_PUBLIC_X=two. What does the browser show? How can you check the JS files?
5. Make a file with import 'server-only' and import it from a Client Component. What happens at build time?
6. Add output: 'standalone' and build. How big is .next/standalone? Run it with node .../server.js and PORT=4000.
7. Add an instrumentation.ts with register and onRequestError. Make a route that throws. What do you see in the log?
8. (Optional) Write the three-stage Dockerfile. Build it and run it with -e for one server variable and one NEXT_PUBLIC_ variable. Which one changes?

Answers

1. The line lists the files in order. A variable that is in several files shows the value from the most specific one: .env.local before .env.production before .env.
2. Only the connection() page. The static page was built before the start, with the old value.
3. NEXT_PUBLIC_X shows its value. SECRET_X is undefined.
4. It shows one. Search the files in .next/static with grep. You find one, and you do not find two.
5. The build fails with "'server-only' cannot be imported from a Client Component module" and an import trace.
6. Usually tens of MB, much smaller than a full node_modules. It listens on port 4000.
7. The register line once at start, and an onRequestError line for each error, with the message, path and route type.
8. The server variable changes. The NEXT_PUBLIC_ one does not, because it was frozen into the JavaScript at build time.

Interview questions

Key takeaways

• Load order: real environment, then .env.$(NODE_ENV).local, .env.local, .env.$(NODE_ENV), .env. I proved it with one variable in three files.
• Server variables stay on the server. NEXT_PUBLIC_ variables are copied into the browser JavaScript at build time and never change after that. I tried to override one at start time and failed.
• Static pages read the environment when you build. Dynamic routes read it on each request.
• Use import 'server-only' for files with secrets. A wrong import fails the build with a trace.
• next.config.ts holds headers, images, output mode and flags. Turn off poweredByHeader. Set security headers.
• output: 'standalone' cut my deployable folder from 402 MB to 67 MB. Start it with node server.js, and copy public and .next/static yourself.
• A Docker image: three stages, non-root user, HOSTNAME=0.0.0.0, ARG for build-time values. Mine was 332 MB and behaved as proved.
• instrumentation.ts gives you register and onRequestError. Guard Node-only code with NEXT_RUNTIME.
• With many instances, plan for a shared cache, one encryption key and a deployment ID. I did not test those.
• I did not deploy to a host. Test your own platform, and always run a production build first.

What's next

Next: Next.js Interview Questions With Model Answers. The final lesson gathers the questions that interviewers really ask about this whole series: rendering, caching, Server Components, actions, auth, metadata and deployment, with answers and the traps. Practise now: build the lab Dockerfile for any small Next.js app, run it with -e for two kinds of variable, and check which one changes.