Node.js Deployment

Detection

Project is Node.js if package.json exists in the root directory.

Versions

Node.js version priority:

1. .node-version or .nvmrc file
2. engines.node field in package.json
3. mise.toml or .tool-versions
4. Defaults to 22

Bun

If Bun is detected as the package manager:

1. engines.bun field in package.json
2. .bun-version file
3. mise.toml or .tool-versions
4. Defaults to latest

When Bun is the primary runtime, Node.js must still be installed if:

• The project uses Corepack (packageManager field exists in package.json)
• Build tools require Node (Astro, Vite, or native addon compilation via node-gyp)
• Any package.json script explicitly invokes node

Package Managers

Detect in order:

1. packageManager field in package.json → use Corepack to install exact version (e.g. pnpm@9.1.0)
2. Lock files:

3. engines field — engines.pnpm → pnpm, engines.bun → Bun, engines.yarn → Yarn
4. Default: npm

Install Commands

Runtime Variables

Set NODE_ENV=production for the runtime stage. During the build, keep NPM_CONFIG_PRODUCTION=false and YARN_PRODUCTION=false so dev dependencies remain available for compilation. Disable update notifications with NPM_CONFIG_UPDATE_NOTIFIER=false and NPM_CONFIG_FUND=false. Set CI=true to enable CI-appropriate behavior in tooling.

Build & Start

Start Command Resolution

1. start script in package.json
2. main or module field in package.json (run with node)
3. server.js, index.js, or index.ts in root (run with node)

Build Command Resolution

1. build script in package.json → ${packageManager} run build
2. If no build script → skip build step

Output Directory

Port Detection

1. Environment files — PORT=<number> from .env, .env.example, .env.production
2. package.json scripts — scan start, dev, serve for -p <port>, --port <port>, PORT=<port>
3. Framework config — next.config.* or vite.config.* for port: <number>
4. Framework defaults:

5. Final default: 3000

Framework Detection

From package.json dependencies (merge dependencies + devDependencies). First match wins.

Config file fallback:

Framework-Specific Behavior

Next.js

• Check next.config.* for output: "standalone" → standalone build (smaller image, includes node_modules subset)
• output: "export" → static site, no server needed
• Cache .next/cache between builds
• app/ directory → React Server Components

Nuxt

• Default start: node .output/server/index.mjs
• Cache node_modules/.cache

Astro

• If output is not "server" → static site
• Cache node_modules/.astro

Monorepo Support

Detection Signals

• workspaces field in root package.json
• pnpm-workspace.yaml
• Build orchestrators: turbo.json, nx.json, lerna.json, rush.json
• Conventional directories: apps/, packages/, services/

Workspace Package Resolution

• pnpm: Parse pnpm-workspace.yaml → packages: list
• npm / yarn / bun: Parse workspaces field in root package.json

Build Steps

1. Detect workspace configurations automatically
2. Install all workspace dependencies (copy all package.json files + root lock file)
3. Respect workspace dependency links
4. Cache workspace node_modules
5. Build the target workspace package

Optimizing the Install Layer

Always copy:

• package.json (root + workspace packages if monorepo)
• Lock file
• pnpm-workspace.yaml (if pnpm monorepo)
• .npmrc (if exists — contains registry config)

Framework-specific install files (copy if they exist, they trigger postinstall):

• prisma/schema.prisma — Prisma generates client on postinstall
• .env files needed at build time (e.g. Next.js NEXT_PUBLIC_*)

If package.json defines preinstall or postinstall scripts that depend on source files, copy the entire source before install to avoid broken hooks.

Static Sites

Serve with Caddy/nginx. SPA fallback, cache headers for hashed assets, gzip/brotli.

Environment Variable Semantics

Build-Time vs Runtime

Build-time env vars must be available during Docker build step (via ARG + ENV).

System Dependencies

Dev Dependency Pruning

After build, remove dev dependencies to reduce image size:

• npm: npm prune --omit=dev
• yarn: yarn install --production or set NODE_ENV=production during install
• pnpm: pnpm prune --prod
• bun: bun install --production

Skip pruning if the start command references a dev dependency (ts-node, tsx, nodemon).

Caching

Dockerfile Patterns

Simple Node.js Server (Express, Fastify, NestJS, Hono)

FROM node:<version>-slim AS base

FROM base AS deps
WORKDIR /app
COPY package.json <lockfile> ./
RUN <install-command>

FROM base AS build
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN <build-command>

FROM base AS runtime
WORKDIR /app
ENV NODE_ENV=production
COPY --from=build /app/dist ./dist
COPY --from=build /app/node_modules ./node_modules
COPY --from=build /app/package.json ./
EXPOSE <port>
CMD ["node", "dist/index.js"]

Next.js Standalone

FROM node:<version>-slim AS base

FROM base AS deps
WORKDIR /app
COPY package.json <lockfile> ./
RUN <install-command>

FROM base AS build
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN <build-command>

FROM base AS runtime
WORKDIR /app
ENV NODE_ENV=production
COPY --from=build /app/.next/standalone ./
COPY --from=build /app/.next/static ./.next/static
COPY --from=build /app/public ./public
EXPOSE 3000
CMD ["node", "server.js"]

Static Site (Vite, CRA, Astro static)

FROM node:<version>-slim AS build
WORKDIR /app
COPY package.json <lockfile> ./
RUN <install-command>
COPY . .
RUN <build-command>

FROM caddy:alpine AS runtime
COPY --from=build /app/<output-dir> /srv
COPY Caddyfile /etc/caddy/Caddyfile
EXPOSE 80

Gotchas

• Yarn Berry (v2+) uses Plug'n'Play by default — node_modules won't exist unless nodeLinker: node-modules is set in .yarnrc.yml
• npm ci deletes node_modules before installing — copy package.json + lockfile first, install, then copy source for proper layer caching
• Next.js output: "standalone" must be set in config BEFORE running the build — the build step generates the standalone directory
• Prisma runs prisma generate on postinstall — prisma/schema.prisma must be copied before npm install
• pnpm with --shamefully-hoist may be needed for packages expecting a flat node_modules layout
• Bun --frozen-lockfile is the correct flag (not --ci like npm)
• SvelteKit and Astro dev servers use different ports (5173, 4321) than production — ensure EXPOSE matches the production port