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.

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.
# 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
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.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.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.
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.
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.

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.
npm install instead of npm ci, which can drift from the lockfile.CMD npm start or a shell-form CMD, which breaks signal handling.SIGTERM handler and no --init, so every deploy waits out the grace period.node user..env files into the image.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.
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.
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.
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.