Building and Deploying

Deploying a Next.js application means three things: producing a production build, running it somewhere that can serve requests, and supplying configuration that differs between your machine and the environment users reach.

The build is not the development server with a flag changed. It compiles and minifies your code, drops the development-only checks, decides which routes can be rendered ahead of time, and fails on type errors that the development server tolerates. The first production build of an application usually finds something.

Because a Next.js application runs on both sides of the network, deployment has one hazard that a purely server-rendered application does not: some of your code is downloaded by the browser, and a configuration value used in that code is downloaded with it.

# Compile the production build. Type errors and lint errors fail the
# build by default, which is the point of running it before deploying.
npm run build

# Serve that build. This is not the development server: no hot reload,
# no development warnings, and the timings users will actually see.
npm run start

# The standalone output, when next.config.ts sets output: "standalone".
# server.js here is the entry point for a container.
ls .next/standalone

• The build prints one line per route with its size and whether it was rendered statically or will be rendered per request. Read it. A route you expected to be static appearing as dynamic means something in it reads cookies, headers or searchParams, or has a fetch with no-store.
• The first load JavaScript figure is the number to watch over time. It includes the shared framework code, so it will never be tiny, but a jump after adding a dependency tells you which change cost what.
• npm run start requires a build to exist. It serves .next; it does not rebuild. Forgetting to rebuild after a change and then wondering why the fix is missing is a normal afternoon.
• A build failing on a type error that the development server ignored is correct behaviour, not an obstacle. The development server type-checks the files it happens to compile; the build checks the whole project.
• The standalone directory contains a server, the compiled application, and only the node_modules actually needed to run it. Static assets and the public folder are copied alongside it, which is why the Dockerfile further down has three COPY lines rather than one.

// ---- app/employees/page.tsx — a server component ----
// This function runs on the server and is never sent to the browser,
// so it can read a secret.
export default async function EmployeesPage() {
  const response = await fetch("https://api.example.com/employees", {
    headers: {
      Authorization: "Bearer " + process.env.DIRECTORY_API_KEY,
    },
  });

  if (!response.ok) throw new Error("Could not load the directory");

  const employees = await response.json();
  return <EmployeeList employees={employees} />;
}

// ---- components/SupportLink.tsx — a client component ----
// "use client" must be the first line of its own file. Everything here
// is downloaded by the browser, so only a public value belongs in it.
"use client";

export function SupportLink() {
  return (
    <a href={process.env.NEXT_PUBLIC_SUPPORT_URL}>
      Contact the directory team
    </a>
  );
}

• The server component reads DIRECTORY_API_KEY. That code stays on the server, the key stays with it, and the browser receives only the rendered employee list.
• The client component can only read NEXT_PUBLIC_SUPPORT_URL, because unprefixed variables are not defined in the browser bundle. The value you get otherwise is undefined, which is the framework telling you the boundary exists.
• Renaming the API key to NEXT_PUBLIC_DIRECTORY_API_KEY to make it work in a client component publishes it. The prefix is not a fix for an undefined value; it is a decision to make the value public.
• Data crosses the boundary as props, and props are serialised into the HTML. Passing a whole record to a client component sends every field, including ones you do not render. Send what the component displays.
• If a client component needs something derived from a secret — a short-lived upload token, for example — generate it on the server and pass the result, never the secret that produced it.

# Stage 1 — install dependencies and run the build.
FROM node:22-alpine AS builder
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build

# Stage 2 — the runtime image, carrying only what serving needs.
FROM node:22-alpine AS runner
WORKDIR /app

ENV NODE_ENV=production
ENV PORT=3000
# Without this the server listens on localhost inside the container,
# which nothing outside it can reach.
ENV HOSTNAME=0.0.0.0

RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs

COPY --from=builder /app/public ./public
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static

USER nextjs
EXPOSE 3000
CMD ["node", "server.js"]

• This needs output: "standalone" in next.config.ts. That setting makes the build emit a self-contained server in .next/standalone, including only the production dependencies the application actually reaches at runtime.
• Two stages keep the result small. The build stage needs the full dependency tree and your source; the runtime stage needs neither, so neither is in the final image.
• The three COPY lines are not interchangeable. standalone provides the server and application code, .next/static holds the built assets it serves, and public holds files you added yourself. Miss the second and the page loads with no styles.
• HOSTNAME=0.0.0.0 is the setting people lose an hour to. The server defaults to localhost, which inside a container means the container only, so port mapping appears to do nothing.
• The image runs as a non-root user. If a process is compromised, this limits what it can do inside the container. It costs two lines.
• This site is deployed this way. The Anvi Learning Academy runs from a standalone build in a container, using the structure above — which is also why the Dockerfile in this repository is worth reading alongside this lesson.