Skip to content
Tutorials Center
My learning

Topics

Lesson 35 of 39 ยท Testing and Deployment

Building and Deploying Your App

Build and deploy a React Router framework app: react-router build, the Node server and Dockerfile, serverless and edge targets, environment variables, health checks and a release checklist.

A framework-mode app has two outputs. The build creates a client folder of static files (JavaScript, CSS, images) and a server bundle that handles requests, runs loaders and actions and renders HTML. Deploying means putting both somewhere they can run. Because the server part is built on standard Request and Response, the same app can run on a Node server, in a container, on a serverless platform or at the edge, with small adapter differences. This lesson walks through the build, the common targets, configuration and a release checklist.

The real tooling is not available on this site, so commands and config are read-only. The runnable blocks model the ideas.

What the build produces

Terminal
# read-only
npm run build        # runs: react-router build
Text
build/
  client/            static assets: hashed JS/CSS, public files (serve with long cache)
  server/
    index.js         the request handler bundle

react-router-serve is a ready-made Node server for the build; you start it with react-router-serve ./build/server/index.js (the start script in a new project). If you need custom behavior (your own Express or Hono server, middleware, WebSockets) you import the build and mount the request handler yourself.

Node server and Docker

A container is the most portable target: it runs on Fly.io, Railway, Render, a VPS, Kubernetes and more. A multi-stage Dockerfile keeps the image small:

DOCKERFILE
# Dockerfile (read-only)
FROM node:24-slim AS deps
WORKDIR /app
COPY package*.json ./
RUN npm ci

FROM deps AS build
COPY . .
RUN npm run build

FROM node:24-slim AS runtime
WORKDIR /app
ENV NODE_ENV=production
COPY package*.json ./
RUN npm ci --omit=dev
COPY --from=build /app/build ./build
USER node
EXPOSE 3000
CMD ["npm", "run", "start"]

Why this shape: the first stages install and compile with dev tools, the final image contains only production dependencies and the build output, and it runs as the unprivileged node user. Listen on the port your platform provides (process.env.PORT) and bind to 0.0.0.0 inside a container.

Serverless and edge

Target Fits Notes
Node server or container steady traffic, WebSockets, long tasks, local files simplest mental model; you manage scaling
Vercel / Netlify auto-scaling, previews per pull request each request may be a cold function; keep startup light
Cloudflare Workers global low latency, cheap static assets no Node-only APIs unless compatibility flags; use D1/KV/R2 instead of local files
Deno / Bun hosts their runtimes check which Node APIs your dependencies use

The big question when choosing is where your database lives. A server in Frankfurt talking to a database in Virginia is slow no matter how clever the framework is; put compute near the data, or use a database with read replicas close to users. Edge runtimes also lack a persistent file system and restrict some libraries, so test on the target early.

Node.js Stand-in: a runtime-agnostic request handler

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Environment variables and secrets

Configuration that changes between environments (database URL, session secret, API keys) belongs in environment variables, never in the repository. Read them in .server modules only. Validate them at startup so a missing variable fails the deploy instead of the first user:

Node.js Stand-in: fail fast on missing configuration

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Values prefixed for the client (for example VITE_) are public, embedded in the browser bundle. Never put a secret in one. Expose the few public values you need through a loader instead of reading process.env in components.

Migrations, health checks and graceful shutdown

  • Database migrations should run as a separate release step before the new version takes traffic, and be backward compatible with the old version for a moment (add a column first, use it next release).
  • Health check route (/healthz) returns 200 quickly and checks only what must work (a simple database ping). The platform uses it to decide whether to route traffic.
  • Graceful shutdown: on SIGTERM, stop accepting connections, finish in-flight requests, then exit. Platforms send this signal during deploys.

Release checklist

  1. Tests pass (unit, route stubs and a few end-to-end journeys).
  2. npm run build succeeds and npm run typecheck is clean.
  3. Environment variables are set and validated; secrets rotated if they leaked.
  4. Migrations applied; backups verified.
  5. Static assets cached for a year; documents have cache headers matching their privacy.
  6. Error logging and an uptime monitor are on (see Unexpected Errors and Logging).
  7. A rollback plan: keep the previous image or deployment ready.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does the build produce?

    Client assets are served statically; the server bundle runs loaders, actions and rendering.
  2. 2. Why use a multi-stage Dockerfile?

    Dev tools stay in earlier stages, and the runtime stage runs as an unprivileged user.
  3. 3. What is the most important factor when choosing between a server and an edge runtime?

    Compute far from the data is slow, and edge runtimes restrict Node APIs and local files.
  4. 4. Which variables are safe for secrets?

    Prefixed variables are embedded in the browser bundle and loader data is sent to the client.

Summary

  • The build creates static client assets and a server request handler; the handler is Request to Response, so it runs on many hosts.
  • Containers are the most portable target; serverless and edge trade control for scale and latency.
  • Keep config in validated environment variables; client-prefixed variables are public.
  • Run migrations as a release step, expose a health check, shut down gracefully and keep a rollback ready.

Next: Project: Notes App