Updated Nov 20, 20265 min read

How to Write a Dockerfile for a Node.js App

A production Dockerfile for Node.js and TypeScript in 2026: multi-stage builds on node:26-slim, npm ci with production-only dependencies, the node user, PID 1 and SIGTERM, and what to keep out of the image.

Illustration for How to Write a Dockerfile for a Node.js App

A good Node.js Dockerfile installs dependencies from the lockfile, compiles TypeScript in a build stage, and ships a slim image with production dependencies only, running as a non-root user. Most of the problems teams hit later, like slow stops or huge images, come from skipping one of those steps.

The Dockerfile below is for a TypeScript service, followed by what each line does and how the server should behave inside it.

What does a production Node.js Dockerfile look like?

# syntax=docker/dockerfile:1 FROM node:26-slim AS build WORKDIR /app COPY package.json package-lock.json ./ RUN --mount=type=cache,target=/root/.npm npm ci COPY tsconfig.json ./ COPY src ./src RUN npm run build FROM node:26-slim AS deps WORKDIR /app COPY package.json package-lock.json ./ RUN --mount=type=cache,target=/root/.npm npm ci --omit=dev FROM node:26-slim ENV NODE_ENV=production WORKDIR /app COPY --from=deps --chown=node:node /app/node_modules ./node_modules COPY --from=build --chown=node:node /app/dist ./dist COPY --chown=node:node package.json ./ USER node EXPOSE 8080 CMD ["node", "dist/server.js"]

A .dockerignore keeps the context small and the cache stable:

node_modules dist .git .env* npm-debug.log

What does each line do?

  • node:26-slim. Node 26 is the current LTS line, per the Node.js release index. On Docker Hub, the slim image for linux/amd64 is about 86 MB compressed, the full node:26 image about 445 MB.
  • package.json and the lockfile first. The npm ci layer is reused until dependencies change, instead of reinstalling on every code edit.
  • npm ci instead of npm install. It installs exactly what the lockfile says and fails if package.json disagrees with it.
  • A separate deps stage with --omit=dev. TypeScript, test runners and linters stay out of the runtime image.
  • --mount=type=cache,target=/root/.npm. BuildKit keeps npm's download cache between builds.
  • NODE_ENV=production. Express and many libraries skip development behaviour when it is set.
  • USER node. The official images ship a node user with UID 1000, so the app does not run as root.
  • CMD ["node", ...] in exec form. Node runs directly as PID 1 and receives signals, instead of under npm start or a shell.

Why does a Node.js container ignore SIGTERM?

The Docker Node.js best practices note that Node was not designed to run as PID 1, and a process running as PID 1 gets no default action for signals it does not handle. docker stop, Kubernetes, ECS and Cloud Run all send SIGTERM first, and an unhandled one means the container sits until the grace period ends and gets killed, dropping in-flight requests. Handle it in the server:

// src/server.ts import http from "node:http"; const port = Number(process.env.PORT ?? 8080); const server = http.createServer((req, res) => { if (req.url === "/healthz") return res.end("ok"); res.statusCode = 404; res.end(); }); server.listen(port, "0.0.0.0", () => console.log(`listening on ${port}`)); // As PID 1, Node gets no default SIGTERM handling, so handle it explicitly. process.on("SIGTERM", () => { console.log("SIGTERM, closing"); server.close(() => process.exit(0)); setTimeout(() => process.exit(1), 10_000).unref(); });

server.close stops accepting connections and waits for open requests, and the timer forces an exit if they hang. Running with docker run --init adds tini as PID 1 too, which also reaps zombie processes if the app spawns children.

Should you use Alpine, slim or distroless?

Slim is the default choice: glibc, so native modules like sharp, bcrypt or Prisma's engines install from prebuilt binaries. Alpine is smaller but uses musl, and packages without musl builds compile from source or fail. Distroless Node images drop the shell and package manager, which helps a security review and makes debugging inside the container harder.

How does Encore build Node.js images without a Dockerfile?

Encore

Encore is a backend framework with built-in infrastructure, and it builds the image from the application. encore build docker compiles a TypeScript app on the host and produces an image on a node:slim base, on the same code path Encore's CI uses for deploys, per the Docker build docs. The image listens on 8080 or PORT.

Application code passes through Encore and infrastructure guardrails to resources provisioned in your own AWS or GCP account.
Get started
brew install encoredev/tap/encore &&
encore app create
Copy

Run in your terminal to get started locally.

A service with a database and a secret, where the hand-written Dockerfile would also need a connection string and an environment variable wired up at deploy:

// webhooks/webhooks.ts import { api, APIError } from "encore.dev/api"; import { SQLDatabase } from "encore.dev/storage/sqldb"; import { secret } from "encore.dev/config"; import { createHmac, timingSafeEqual } from "node:crypto"; const db = new SQLDatabase("webhooks", { migrations: "./migrations" }); // Set with: encore secret set --type prod SigningSecret const signingSecret = secret("SigningSecret"); interface Delivery { id: string; payload: string; signature: string; } export const receive = api( { expose: true, method: "POST", path: "/webhooks" }, async ({ id, payload, signature }: Delivery): Promise<{ stored: boolean }> => { const expected = createHmac("sha256", signingSecret()).update(payload).digest("hex"); const a = Buffer.from(expected); const b = Buffer.from(signature); if (a.length !== b.length || !timingSafeEqual(a, b)) { throw APIError.permissionDenied("bad signature"); } await db.exec` INSERT INTO deliveries (id, payload) VALUES (${id}, ${payload}) ON CONFLICT (id) DO NOTHING`; return { stored: true }; }, );
-- webhooks/migrations/1_init.up.sql CREATE TABLE deliveries ( id TEXT PRIMARY KEY, payload TEXT NOT NULL, received_at TIMESTAMPTZ NOT NULL DEFAULT now() );

Secret values are stored per environment and are not in the repo or in git, so they are not in the image or the code. When self-hosting the image, encore build docker --config=infra-config.json takes the database and secret settings from an infrastructure config file, and migrations are applied separately. On the Encore deploy path, a push to AWS or GCP builds the image, runs migrations and provisions the database in your own account.

Best fit: Teams who want production images, secrets and databases from the application code instead of a Dockerfile and deploy config per service.

What mistakes should you avoid?

  1. npm install instead of npm ci, which can drift from the lockfile.
  2. Copying the source before installing dependencies, which reinstalls on every change.
  3. Shipping devDependencies and the TypeScript compiler.
  4. CMD npm start or a shell-form CMD, which breaks signal handling.
  5. No SIGTERM handler and no --init, so every deploy waits out the grace period.
  6. Running as root when the image already has a node user.
  7. Copying .env files into the image.

Frequently asked questions

What is the best base image for Node.js in Docker?

node:26-slim for most apps, which is the current LTS line on Debian with the extras removed, about 86 MB compressed for linux/amd64 against about 445 MB for the full [node:26](https://hub.docker.com/_/node) image. Alpine is smaller but uses musl, which some native modules do not support.

Why does my Node.js container take 10 seconds to stop?

Node as PID 1 gets no default handling for SIGTERM, so docker stop waits out its 10-second grace period and then kills the process. Handle SIGTERM in your code, or run the container with --init or tini.

Should I use npm start in a Dockerfile CMD?

No. Run node directly, as in CMD ["node", "dist/server.js"]. With npm start, npm is the main process and your server runs as its child, which makes signal handling and exit codes less predictable.

Should I use npm install or npm ci in Docker?

Use npm ci, which installs exactly what package-lock.json lists, fails if the lockfile and package.json disagree, and with --omit=dev it leaves out devDependencies such as TypeScript and test tools.

Deploy to your cloud on AWS and Google Cloud
without managing infrastructure

Encore lets developers and agents define application infrastructure directly in code, then automatically provisions it from local development to production in your AWS or GCP account.

~/orders — claude
Claude Code
Claude Code v2.1.180Opus 5.5~/orders