For developers at Sadeem informatique

Image source: NestJS official assets.

Getting Docker working with NestJS is easy. Getting it right with proper layer caching, deterministic installs, Prisma client generation, and a secure runtime image takes a bit more structure. This guide walks through each Dockerfile decision so you can adapt it safely to your own services.

By the end, you'll have a Dockerfile that:

• Maximises Docker layer caching so rebuilds are fast
• Never reinstalls node_modules when only application code changes
• Generates Prisma client in the build stage
• Uses multi-stage builds to keep the final image lean
• Runs as a non-root user in production

The Full Dockerfile​

Here's the complete file we'll walk through first, then break down stage by stage.

# ===============================
# Base image
# ===============================
FROM node:22-alpine AS base
WORKDIR /usr/src/app

# ===============================
# Dependencies (build deps)
# ===============================
FROM base AS deps
COPY package.json package-lock.json ./
RUN npm ci

# ===============================
# Build stage
# ===============================
FROM base AS builder
WORKDIR /usr/src/app

ARG NODE_MEMORY=512
ENV NODE_OPTIONS="--max-old-space-size=${NODE_MEMORY}"

COPY --from=deps /usr/src/app/node_modules ./node_modules
COPY . .

RUN npx prisma generate
RUN npm run build

# ===============================
# Production dependencies only
# ===============================
FROM base AS prod-deps
COPY package.json package-lock.json ./
RUN npm ci --omit=dev && npm cache clean --force

# ===============================
# Runtime image
# ===============================
FROM base AS runner
WORKDIR /usr/src/app

ARG PORT=3000
ARG RUNTIME_NODE_MEMORY=384

ENV NODE_ENV=production
ENV PORT=${PORT}
ENV NODE_OPTIONS="--enable-source-maps --max-old-space-size=${RUNTIME_NODE_MEMORY}"

RUN addgroup -S appgroup && adduser -S appuser -G appgroup

COPY --from=builder --chown=appuser:appgroup /usr/src/app/dist ./dist
COPY --from=prod-deps --chown=appuser:appgroup /usr/src/app/node_modules ./node_modules
COPY --from=builder --chown=appuser:appgroup /usr/src/app/package.json ./package.json
COPY --from=builder --chown=appuser:appgroup /usr/src/app/prisma ./prisma

USER appuser
EXPOSE ${PORT}
CMD ["node", "dist/main.js"]

If your project does not use Prisma, remove npx prisma generate, the prisma/ copy step, and the migration script section.

Stage 1: The Base Image​

FROM node:22-alpine AS base
WORKDIR /usr/src/app

Why node:22-alpine?​

For many NestJS services, Alpine provides a good size/performance balance. If your stack has native dependencies that require glibc, switch to node:22-slim for compatibility.

Naming the stage with AS base​

Using a shared base stage gives one source of truth for Node version and workdir across all later stages.

Stage 2: The Dependency Layer, Docker Caching Done Right​

This is the most important caching decision in the file.

FROM base AS deps
COPY package.json package-lock.json ./
RUN npm ci

The problem: cache invalidation​

Docker caches layer by layer. If a layer changes, every following layer is invalidated. If you copy all source before installing dependencies, Docker reinstalls packages on every code change.

# Bad pattern
COPY . .
RUN npm ci
RUN npm run build

The solution: isolate dependency installation​

By copying only manifest files in the dependency stage, Docker reuses npm ci unless dependency files change.

# Good pattern
COPY package.json package-lock.json ./
RUN npm ci

Why npm ci instead of npm install?​

npm ci is deterministic and CI-friendly:

• Installs exactly what package-lock.json defines
• Fails if lockfile and manifest are out of sync
• Avoids implicit upgrades
• Produces reproducible builds across environments

Stage 3: The Build Stage, No Hardcoded Values​

FROM base AS builder
WORKDIR /usr/src/app

ARG NODE_MEMORY=512
ENV NODE_OPTIONS="--max-old-space-size=${NODE_MEMORY}"

Build arguments over hardcoded values​

Hardcoding configuration in images creates environment-specific artifacts. Prefer ARG defaults that can be overridden during build.

ARG NODE_MEMORY=512
ENV NODE_OPTIONS="--max-old-space-size=${NODE_MEMORY}"

Passing build args​

docker build \
  --build-arg NODE_MEMORY=1024 \
  -t nest-app:staging .

services:
  api:
    build:
      context: .
      args:
        NODE_MEMORY: 1024

- name: Build Docker image
  run: |
    docker build \
      --build-arg NODE_MEMORY=1024 \
      -t nest-app:${{ github.sha }} .

Bringing in node_modules from the deps stage​

COPY --from=deps /usr/src/app/node_modules ./node_modules
COPY . .
RUN npx prisma generate
RUN npm run build

The stage reuses cached dependencies and then compiles NestJS to dist/. Prisma generation belongs here because it depends on schema and build-time tooling.

tsconfig.build.json for predictable dist/ output​

Make sure your NestJS build config writes only compiled source into dist:

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "test", "dist", "**/*spec.ts"]
}

Stage 4: The Runtime Image, Lean and Secure​

FROM base AS runner
WORKDIR /usr/src/app

This stage starts fresh and receives only runtime artifacts. Build tooling and source-only files stay out of production.

Configurable port and memory​

ARG PORT=3000
ARG RUNTIME_NODE_MEMORY=384

ENV NODE_ENV=production
ENV PORT=${PORT}
ENV NODE_OPTIONS="--enable-source-maps --max-old-space-size=${RUNTIME_NODE_MEMORY}"

Use separate memory limits for build and runtime. Build usually needs more memory than the long-running API process.

Running as a non-root user​

RUN addgroup -S appgroup && adduser -S appuser -G appgroup
USER appuser

This reduces blast radius if the process is compromised.

Copying only what is needed​

COPY --from=builder --chown=appuser:appgroup /usr/src/app/dist ./dist
COPY --from=prod-deps --chown=appuser:appgroup /usr/src/app/node_modules ./node_modules
COPY --from=builder --chown=appuser:appgroup /usr/src/app/package.json ./package.json
COPY --from=builder --chown=appuser:appgroup /usr/src/app/prisma ./prisma

The runtime image includes only:

EXPOSE and CMD​

EXPOSE ${PORT}
CMD ["node", "dist/main.js"]

Use exec-form CMD for proper signal handling in containers. Keep this command focused on serving the NestJS app only; do not add migration commands to the Dockerfile CMD.

.dockerignore for clean context​

node_modules
dist
.git
.gitignore
Dockerfile
npm-debug.log
.env
.env.*
coverage

This keeps build context small and avoids leaking local files into image layers.

Caching Strategy, Visual Summary​

                       ┌──────────────────────────────────────────────┐
                       │  What changed?                               │
                       └──────────────────────────────────────────────┘
                                        │
            ┌───────────────────────────┼─────────────────────────────┐
            ▼                           ▼                             ▼
    package.json / lockfile     application code only           runtime args only
            │                           │                             │
            ▼                           ▼                             ▼
    ┌──────────────────┐        ┌──────────────────┐          ┌──────────────────┐
    │ deps: MISS       │        │ deps: HIT        │          │ deps: HIT        │
    │ npm ci runs      │        │ cached reuse     │          │ cached reuse     │
    └────────┬─────────┘        └────────┬─────────┘          └────────┬─────────┘
             │                           │                              │
             ▼                           ▼                              ▼
    ┌──────────────────┐        ┌──────────────────┐          ┌──────────────────┐
    │ builder: MISS    │        │ builder: MISS    │          │ runner: MISS     │
    │ prisma + build   │        │ prisma + build   │          │ env-only rebuild │
    └────────┬─────────┘        └────────┬─────────┘          └──────────────────┘
             │                           │
             ▼                           ▼
    ┌──────────────────┐        ┌──────────────────┐
    │ runner: MISS     │        │ runner: MISS     │
    └──────────────────┘        └──────────────────┘

Key point: source-only changes should not invalidate your dependency installation layer.

Building and Running​

# Build local image
docker build -t nest-app:dev .

# Build with custom args
docker build \
  --build-arg NODE_MEMORY=1024 \
  --build-arg PORT=3000 \
  -t nest-app:staging .

# Run
docker run -p 3000:3000 --env-file .env nest-app:staging

# Run on custom runtime port
docker run -p 8080:8080 -e PORT=8080 nest-app:staging

Prisma Migration Note​

Backend developers should include a clear migration command in package.json so every environment can call the same script.

First, define the migration script in package.json:

{
  "scripts": {
    "migration:run": "prisma migrate deploy"
  }
}

Run it with your package manager of choice, for example:

npm run migration:run

Checklist​

Before shipping to production, verify:

• package.json and package-lock.json are copied before full source
• Dependencies are installed in a dedicated cached stage
• Prisma client is generated during build
• tsconfig.build.json outputs app code to dist/
• Runtime image contains only required runtime artifacts
• Runtime installs omit dev dependencies
• Container runs as a non-root user
• CMD uses exec form
• .dockerignore excludes local and sensitive files

Conclusion​

A production-grade NestJS Dockerfile is about repeatability, speed, and operational safety. The patterns in this guide isolate dependency caching, keep runtime images lean, and apply practical security defaults so your service is easier to build, deploy, and maintain.

For developers at Sadeem Informatique

Most developers know what the codes mean — very few consistently use them correctly in real applications. This guide shows practical usage patterns you will actually encounter in production React/Next.js apps + Node.js/Express/Laravel/whatever backend.

Photo by ThisIsEngineering on Unsplash

Quick Reference — Most Used Status Codes in 2026​

Most Important Status Codes — Practical Backend Examples​

app.post("/users", async (req, res) => {
  const data = await createUserSchema.parseAsync(req.body);

  const user = await prisma.user.create({ data });

  res
    .header("Location", `/users/${user.id}`)
    .status(201)
    .json(user);
});

app.post("/users", async (req, res) => {
  try {
    const data = await createUserSchema.parseAsync(req.body);
    // ...
  } catch (err) {
    if (err instanceof ZodError) {
      return res.status(422).json({
        message: "Validation failed",
        errors: err.flatten().fieldErrors,
      });
    }
    throw err;
  }
});

if (existingSubscription?.status === "active") {
  return res.status(409).json({
    code: "SUBSCRIPTION_ALREADY_ACTIVE",
    message: "Cannot create trial — user already has active plan",
  });
}

Frontend — Handling Status Codes Intelligently (React + Next.js)​

"use client";

let isRefreshing = false;

export async function apiFetch(
  input: RequestInfo | URL,
  init?: RequestInit
): Promise<Response> {
  const res = await fetch(input, {
    ...init,
    credentials: "include",
    headers: {
      "Content-Type": "application/json",
      ...init?.headers,
    },
  });

  if (res.status === 401 && !isRefreshing) {
    isRefreshing = true;
    try {
      // attempt silent refresh
      const refreshRes = await fetch("/api/auth/refresh", { method: "POST" });
      if (!refreshRes.ok) throw new Error("refresh failed");

      // retry original request
      return apiFetch(input, init);
    } catch {
      // redirect to login or show session expired modal
      window.location.href = "/login?session_expired=1";
    } finally {
      isRefreshing = false;
    }
  }

  if (!res.ok) {
    const errorData = await res.json().catch(() => ({}));
    throw new ApiError(res.status, errorData.message || "Request failed", errorData);
  }

  return res;
}

class ApiError extends Error {
  constructor(
    public status: number,
    message: string,
    public data?: any
  ) {
    super(message);
  }
}

Security & Best Practices (2026)​

Status Code Checklist Before Shipping​

• Never return 200 with { success: false } — use real 4xx codes

• Use 201 + Location header on resource creation

• Use 204 for successful DELETE / bulk updates without body

• Prefer 422 over 400 for semantic/form validation errors

• Return consistent error shape on 4xx/5xx

  {
    "status": 422,
    "code": "VALIDATION_ERROR",
    "message": "Invalid input",
    "errors": { "email": ["Invalid email format"] }
  }
  

• Include Retry-After on 429 and 503

• Never leak stack traces / internal messages in 500 responses

• Log 5xx with correlation ID — return generic "Something went wrong"

Common Anti-Patterns to Avoid​

Glossary​

• 1xx Informational — Rare in APIs (100 Continue mostly for large uploads)

• 2xx Success — Request completed as expected

• 3xx Redirection — Client should take additional action (mostly handled by browser)

• 4xx Client Error — Something wrong with the request (you fix it)

• 5xx Server Error — Something wrong on our side (we fix it)

• Idempotent — Repeating the request produces the same result (GET, PUT, DELETE usually are)

Conclusion​

HTTP status codes are not decoration — they are the first and most reliable part of the contract between frontend and backend. Using them correctly reduces conditional logic in your React components, improves debugging speed, makes monitoring meaningful, and aligns your application with how the web was designed to work.

Master them — and your APIs will feel professional, predictable, and much easier to integrate with.

Happy coding!

For developers at Sadeem informatique

Photo by ThisIsEngineering on Pexels.

Getting Docker working with Next.js is easy. Getting it right — with proper layer caching, no hardcoded values, and a secure production image — takes a bit more thought. This guide walks you through every decision in a production-grade Dockerfile, explaining the why behind each choice so you can adapt it confidently to your own project.

By the end, you'll have a Dockerfile that:

• Maximises Docker layer caching so rebuilds are fast
• Never invalidates your node_modules cache when only application code changes
• Passes all configurable values as build arguments (no hardcoded ports or URLs)
• Uses multi-stage builds to keep the final image lean
• Runs as a non-root user in production

The Full Dockerfile​

Here's the complete file we'll be walking through. Read it once end-to-end, then we'll break it apart section by section.

# ===============================
# Base image
# ===============================
FROM node:22-slim AS base
WORKDIR /app

# ===============================
# Dependencies (isolated for caching)
# ===============================
FROM base AS deps
COPY package.json package-lock.json ./
RUN npm ci

# ===============================
# Build stage
# ===============================
FROM base AS builder
WORKDIR /app

ARG NEXT_PUBLIC_BACKEND_BASE_URL
ARG NEXT_PUBLIC_BACKEND_SIGNED_FILE_URL
ARG NEXT_PUBLIC_COOKIE_DOMAIN
ARG NEXT_PUBLIC_USE_SECURE_COOKIES
ARG NODE_MEMORY=512

ENV NEXT_PUBLIC_BACKEND_BASE_URL=${NEXT_PUBLIC_BACKEND_BASE_URL}
ENV NEXT_PUBLIC_BACKEND_SIGNED_FILE_URL=${NEXT_PUBLIC_BACKEND_SIGNED_FILE_URL}
ENV NEXT_PUBLIC_COOKIE_DOMAIN=${NEXT_PUBLIC_COOKIE_DOMAIN}
ENV NEXT_PUBLIC_USE_SECURE_COOKIES=${NEXT_PUBLIC_USE_SECURE_COOKIES}
ENV NODE_OPTIONS="--max-old-space-size=${NODE_MEMORY}"
ENV NEXT_TELEMETRY_DISABLED=1

COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build

# ===============================
# Runtime image
# ===============================
FROM node:22-slim AS runner
WORKDIR /app

ARG PORT=3005
ARG RUNTIME_NODE_MEMORY=384

ENV NODE_ENV=production
ENV NEXT_TELEMETRY_DISABLED=1
ENV PORT=${PORT}
ENV NODE_OPTIONS="--max-old-space-size=${RUNTIME_NODE_MEMORY}"

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

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

USER nextjs
EXPOSE ${PORT}
CMD ["node", "server.js"]

Stage 1: The Base Image​

FROM node:22-slim AS base
WORKDIR /app

Why node:22-slim?​

The slim variant strips out non-essential packages from the standard Debian image — things like build tools, documentation, and locale data you don't need at runtime. This results in a meaningfully smaller image while still being a well-maintained, official distribution.

Avoid node:22-alpine for Next.js unless you have a strong size constraint. Alpine uses musl libc instead of glibc, which can cause subtle compatibility issues with some native Node.js addons. The slim variant gives you most of the size benefit without the compatibility risk.

Naming the stage with AS base​

By naming this base, all subsequent stages can build on top of it with FROM base. This creates a single source of truth for the Node.js version — update it in one place and all stages pick up the change.

Stage 2: The Dependency Layer — Docker Caching Done Right​

This is the most important caching decision in the entire file.

FROM base AS deps
COPY package.json package-lock.json ./
RUN npm ci

The problem: cache invalidation​

Docker builds images layer by layer and caches each one. When a layer changes, Docker invalidates that layer and every layer after it. This means the order of your COPY and RUN instructions matters enormously.

Consider this naive approach:

# ❌ Bad — installs dependencies on EVERY code change
COPY . .
RUN npm ci
RUN npm run build

Here COPY . . copies all your application source files first. Every time you change a single line of code, Docker sees a changed layer and re-runs npm ci — downloading and reinstalling hundreds of packages unnecessarily. On a modest connection, that's minutes wasted on every push.

The solution: isolate dependency installation​

By separating the dependency stage from the build stage, we take advantage of the fact that package.json and package-lock.json change far less frequently than your application code:

# ✅ Good — node_modules only reinstalled when package files change
COPY package.json package-lock.json ./
RUN npm ci

Docker will only re-run npm ci when either package.json or package-lock.json actually changes. A code-only change skips straight past this stage, pulling node_modules from cache in milliseconds.

Why npm ci instead of npm install?​

npm ci (Clean Install) is purpose-built for automated environments:

• Deletes and recreates node_modules from scratch on every run
• Installs the exact versions locked in package-lock.json (no implicit upgrades)
• Fails if package.json and package-lock.json are out of sync
• Never modifies package-lock.json

This guarantees deterministic, reproducible builds — essential in CI/CD pipelines and Docker.

Stage 3: The Build Stage — No Hardcoded Values​

FROM base AS builder
WORKDIR /app

ARG NEXT_PUBLIC_BACKEND_BASE_URL
ARG NEXT_PUBLIC_BACKEND_SIGNED_FILE_URL
ARG NEXT_PUBLIC_COOKIE_DOMAIN
ARG NEXT_PUBLIC_USE_SECURE_COOKIES
ARG NODE_MEMORY=512

Build arguments over hardcoded values​

Hardcoding environment-specific values into a Dockerfile is a common anti-pattern:

# ❌ Bad — hardcoded, not reusable across environments
ENV NEXT_PUBLIC_BACKEND_BASE_URL=https://api.myapp.com
ENV PORT=3005

This approach creates a different Dockerfile for each environment, and worse — it may bake secrets into image layers where they persist even after being "unset". The correct pattern is ARG:

# ✅ Good — values are injected at build time
ARG NEXT_PUBLIC_BACKEND_BASE_URL
ENV NEXT_PUBLIC_BACKEND_BASE_URL=${NEXT_PUBLIC_BACKEND_BASE_URL}

ARG declares a variable that can be passed in at build time with --build-arg. It is not present in the final image's environment — it's only available during the build. You then promote it to ENV so the running application can access it.

Passing build args​

docker build \
  --build-arg NEXT_PUBLIC_BACKEND_BASE_URL=https://api.staging.myapp.com \
  --build-arg NEXT_PUBLIC_COOKIE_DOMAIN=staging.myapp.com \
  --build-arg NODE_MEMORY=1024 \
  -t myapp:staging .

services:
  web:
    build:
      context: .
      args:
        NEXT_PUBLIC_BACKEND_BASE_URL: ${NEXT_PUBLIC_BACKEND_BASE_URL}
        NEXT_PUBLIC_COOKIE_DOMAIN: ${NEXT_PUBLIC_COOKIE_DOMAIN}
        NODE_MEMORY: 1024

- name: Build Docker image
  run: |
    docker build \
      --build-arg NEXT_PUBLIC_BACKEND_BASE_URL=${{ vars.BACKEND_URL }} \
      --build-arg NEXT_PUBLIC_COOKIE_DOMAIN=${{ vars.COOKIE_DOMAIN }} \
      -t myapp:${{ github.sha }} .

Default values for non-sensitive args​

Note that NODE_MEMORY=512 sets a sensible default. This means developers can build locally without specifying every argument, while CI/CD pipelines can override it for resource-constrained environments:

ARG NODE_MEMORY=512
ENV NODE_OPTIONS="--max-old-space-size=${NODE_MEMORY}"

NEXT_TELEMETRY_DISABLED​

ENV NEXT_TELEMETRY_DISABLED=1

Next.js collects anonymous telemetry data during builds by default. Setting this to 1 disables it in the build stage — good practice in automated pipelines both for privacy and to eliminate the small network call during every build.

Bringing in node_modules from the deps stage​

COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build

Rather than re-running npm ci in the builder, we pull node_modules directly from the deps stage using --from=deps. This keeps the two concerns cleanly separated: dependency installation happens once in its own cached stage, and the builder simply uses the result.

The order here is intentional: copy node_modules first, then copy application source. If you reversed this, a source file change would invalidate the node_modules copy step — which defeats the purpose.

Stage 4: The Runtime Image — Lean and Secure​

FROM node:22-slim AS runner
WORKDIR /app

This stage starts completely fresh from node:22-slim. It has no knowledge of the builder stage except for what we explicitly copy into it. This is the core benefit of multi-stage builds: your production image contains only what is needed to run the application.

It does not contain:

• Source code
• node_modules (the standalone output bundles its own minimal dependencies)
• Build tools
• Intermediate build artifacts

Configurable port and memory​

ARG PORT=3005
ARG RUNTIME_NODE_MEMORY=384

ENV PORT=${PORT}
ENV NODE_OPTIONS="--max-old-space-size=${RUNTIME_NODE_MEMORY}"

The same principle applies here: no hardcoded port. The default of 3005 is used if nothing is passed, but your orchestration layer (Kubernetes, ECS, Compose) can override it for any environment.

Note the separate RUNTIME_NODE_MEMORY argument (defaulting to 384 MB) versus the build-time NODE_MEMORY (defaulting to 512 MB). The build process is memory-hungry — TypeScript compilation and tree-shaking for a large Next.js app can easily spike over 512 MB. The runtime process is far lighter; constraining it prevents memory bloat in production.

Running as a non-root user​

This is one of the most important security practices for production containers.

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

By default, Docker containers run as root. This means that if your application process is ever compromised — through a vulnerability in a dependency, a deserialization flaw, or any other attack vector — the attacker has root access inside the container. Depending on how Docker is configured on the host, this can sometimes translate into host-level risk.

Creating a dedicated system user (nextjs) with a fixed UID/GID (1001) and then switching to it with USER nextjs ensures the application process has only the permissions it needs:

USER nextjs

The --system flag creates the user/group without a home directory, a password, or login shell — appropriate for a service account.

The fixed GID/UID 1001 matters for file permission consistency. If your container mounts volumes or shares a filesystem with the host, predictable UIDs make permission management straightforward.

Copying only what's needed​

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

This relies on Next.js's output: 'standalone' mode (configured in next.config.js). In standalone mode, the Next.js build produces a self-contained server.js that bundles only the minimal dependencies required at runtime, without the full node_modules tree.

The three things copied into the runner are:

Every file is --chown'd to the nextjs:nodejs user/group at copy time. This is more efficient than a separate RUN chown command, which would create an extra layer.

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'standalone',
}

module.exports = nextConfig

EXPOSE and CMD​

EXPOSE ${PORT}
CMD ["node", "server.js"]

EXPOSE is documentation — it tells Docker (and anyone reading the Dockerfile) which port the container listens on. It does not actually publish the port; that happens with -p at runtime or in your Compose/Kubernetes config. Using the $PORT variable here keeps it consistent with the ENV PORT declaration above.

CMD ["node", "server.js"] uses the exec form (a JSON array), not the shell form (CMD node server.js). The exec form runs node as PID 1, which means it receives OS signals (like SIGTERM for graceful shutdown) directly. The shell form wraps it in /bin/sh -c, which often drops those signals — a common source of containers that take 30 seconds to stop because they wait for the shutdown timeout.

Caching Strategy — A Visual Summary​

Here's how cache invalidation flows through the stages for the most common scenarios:

                       ┌──────────────────────────────────────────────────────┐
                       │  What changed?                                        │
                       └──────────────────────────────────────────────────────┘
                                         │
            ┌────────────────────────────┼────────────────────────────┐
            ▼                            ▼                            ▼
    package.json or           Application code only          Dockerfile args only
    package-lock.json         (e.g. a component change)      (e.g. different PORT)
            │                            │                            │
            ▼                            ▼                            ▼
    ┌───────────────┐          ┌──────────────────┐         ┌──────────────────┐
    │  deps: MISS   │          │  deps: HIT ✓     │         │  deps: HIT ✓     │
    │  npm ci runs  │          │  (cached)        │         │  (cached)        │
    └───────┬───────┘          └────────┬─────────┘         └────────┬─────────┘
            │                           │                             │
            ▼                           ▼                             ▼
    ┌───────────────┐          ┌──────────────────┐         ┌──────────────────┐
    │ builder: MISS │          │  builder: MISS   │         │  runner: MISS    │
    │  npm run build│          │  npm run build   │         │  (rebuilt only)  │
    └───────┬───────┘          └────────┬─────────┘         └──────────────────┘
            │                           │
            ▼                           ▼
    ┌───────────────┐          ┌──────────────────┐
    │  runner: MISS │          │  runner: MISS    │
    └───────────────┘          └──────────────────┘

The key takeaway: only changing application code never touches the deps stage. Your node_modules layer stays cached and you skip the most time-consuming part of the build.

Building and Running​

# Build for local development
docker build -t myapp:dev .

# Build for staging with custom args
docker build \
  --build-arg NEXT_PUBLIC_BACKEND_BASE_URL=https://api.staging.myapp.com \
  --build-arg NEXT_PUBLIC_COOKIE_DOMAIN=staging.myapp.com \
  --build-arg PORT=3005 \
  --build-arg NODE_MEMORY=1024 \
  -t myapp:staging .

# Run the container
docker run -p 3005:3005 myapp:staging

# Run with a custom port at runtime
docker run -p 8080:8080 -e PORT=8080 myapp:staging

Checklist​

Before pushing your Dockerfile to production, verify the following:

• output: 'standalone' is set in next.config.js
• Dependencies are installed in a separate stage from the build
• package.json and package-lock.json are copied before application source
• No environment-specific URLs, ports, or credentials are hardcoded
• All configurable values are declared as ARG with sensible defaults
• The runner stage starts FROM the base image, not the builder
• A non-root system user owns and runs the application
• CMD uses exec form (JSON array), not shell form
• NEXT_TELEMETRY_DISABLED=1 is set in both builder and runner stages

Conclusion​

A well-structured Dockerfile is not just about getting the application running in a container — it's about making your build pipeline fast, your configuration flexible, and your production environment secure. The four principles covered in this guide — smart layer caching, isolated dependency stages, build arguments over hardcoded values, and non-root execution — are straightforward to implement and pay dividends every time you push a change.

For developers at Sadeem informatique

Most articles explain where to store tokens. This guide shows you exactly how to implement a secure setup in a real web application.

We'll build the modern recommended pattern:

This approach aligns with OWASP security guidance and is widely used in production SaaS applications.

Photo by Dan Nelson on Pexels.

Architecture Overview​

The authentication flow works as follows:

1. User logs in
2. Server returns an encrypted access token (short-lived JWT) in the response body, and a refresh token (HTTP-only encrypted cookie)
3. Frontend stores the access token in memory only — never in localStorage or sessionStorage
4. When the access token expires, the frontend silently calls /refresh
5. Server decrypts and validates the refresh token cookie, then issues a new access token

Browser                          Server
  │                                │
  │  POST /login                   │
  ├───────────────────────────────►│
  │                                │
  │  { accessToken, expiresIn } ◄──┤  Set-Cookie: refreshToken (httpOnly)
  │                                │
  │  accessToken → stored in memory│
  │                                │
  │  GET /profile                  │
  │  Authorization: Bearer <token> │
  ├───────────────────────────────►│
  │                                │  decrypt → verify → respond
  │  { profile data } ◄────────────┤
  │                                │
  │  [token expires]               │
  │                                │
  │  POST /refresh (cookie auto-sent)
  ├───────────────────────────────►│
  │  { accessToken, expiresIn } ◄──┤
  │                                │

Backend Implementation​

npm install express jsonwebtoken cookie-parser cors crypto-js

const express = require("express");
const jwt = require("jsonwebtoken");
const cookieParser = require("cookie-parser");
const cors = require("cors");
const CryptoJS = require("crypto-js");

const app = express();
app.use(express.json());
app.use(cookieParser());

app.use(cors({
  origin: "http://localhost:3000",
  credentials: true,  // required for cross-origin cookies
}));

const ACCESS_SECRET = process.env.ACCESS_SECRET;
const REFRESH_SECRET = process.env.REFRESH_SECRET;
const ENCRYPTION_KEY = process.env.ENCRYPTION_KEY;

function generateAccessToken(user) {
  const token = jwt.sign(user, ACCESS_SECRET, { expiresIn: "15m" });
  // URL-encode the Base64 output to make it safe for headers and cookies
  return encodeURIComponent(CryptoJS.AES.encrypt(token, ENCRYPTION_KEY).toString());
}

function generateRefreshToken(user) {
  const token = jwt.sign(user, REFRESH_SECRET, { expiresIn: "7d" });
  return encodeURIComponent(CryptoJS.AES.encrypt(token, ENCRYPTION_KEY).toString());
}

function decryptToken(encryptedToken) {
  // Decode before decrypting
  const bytes = CryptoJS.AES.decrypt(decodeURIComponent(encryptedToken), ENCRYPTION_KEY);
  return bytes.toString(CryptoJS.enc.Utf8);
}

app.post("/login", (req, res) => {
  // Replace with real user lookup + password verification
  const user = { id: 1, email: "dev@example.com" };

  const accessToken = generateAccessToken(user);
  const refreshToken = generateRefreshToken(user);

  res.cookie("refreshToken", refreshToken, {
    httpOnly: true,       // not accessible via JavaScript
    secure: true,         // HTTPS only
    sameSite: "strict",   // no cross-site sending (see note below)
    path: "/refresh",     // scoped to the refresh endpoint only
  });

  // Return expiresIn so the frontend can schedule a proactive refresh
  res.json({ accessToken, expiresIn: 15 * 60 });
});

app.post("/refresh", (req, res) => {
  const encryptedToken = req.cookies.refreshToken;
  if (!encryptedToken) return res.sendStatus(401);

  // Validate the Origin header to prevent cross-origin refresh attempts
  const allowedOrigin = process.env.ALLOWED_ORIGIN || "http://localhost:3000";
  if (req.headers.origin !== allowedOrigin) return res.sendStatus(403);

  try {
    const token = decryptToken(encryptedToken);
    const user = jwt.verify(token, REFRESH_SECRET);
    const accessToken = generateAccessToken({ id: user.id });

    // Return expiresIn so the frontend can schedule the next silent refresh
    res.json({ accessToken, expiresIn: 15 * 60 });
  } catch {
    res.sendStatus(403);
  }
});

app.get("/profile", (req, res) => {
  const auth = req.headers.authorization;
  if (!auth) return res.sendStatus(401);

  try {
    const token = decryptToken(auth.split(" ")[1]);
    const user = jwt.verify(token, ACCESS_SECRET);
    res.json({ id: user.id, email: "dev@example.com" });
  } catch {
    res.sendStatus(403);
  }
});

Frontend Implementation​

// Module-scoped — not accessible outside this file
let accessToken = null;
let refreshTimer = null;

export async function login() {
  const res = await fetch("http://localhost:4000/login", {
    method: "POST",
    credentials: "include",  // sends/receives cookies
  });

  const data = await res.json();
  accessToken = data.accessToken;

  // Schedule a proactive refresh before the token expires
  scheduleRefresh(data.expiresIn);
}

export async function apiFetch(url, options = {}) {
  options.headers = {
    ...options.headers,
    Authorization: `Bearer ${accessToken}`,
  };

  let res = await fetch(url, { ...options, credentials: "include" });

  if (res.status === 401 || res.status === 403) {
    await refreshAccessToken();  // try to get a new access token
    options.headers.Authorization = `Bearer ${accessToken}`;
    res = await fetch(url, { ...options, credentials: "include" });
  }

  return res;
}

async function refreshAccessToken() {
  const res = await fetch("http://localhost:4000/refresh", {
    method: "POST",
    credentials: "include",  // the httpOnly cookie is sent automatically
  });

  if (!res.ok) throw new Error("Session expired. Please log in again.");

  const data = await res.json();
  accessToken = data.accessToken;

  // Reschedule the next proactive refresh
  scheduleRefresh(data.expiresIn);
}

function scheduleRefresh(expiresInSeconds) {
  if (refreshTimer) clearTimeout(refreshTimer);

  // Refresh 60 seconds before expiry to avoid any clock drift
  const delay = (expiresInSeconds - 60) * 1000;

  refreshTimer = setTimeout(async () => {
    try {
      await refreshAccessToken();
    } catch {
      // Token could not be refreshed — force the user to log in again
      accessToken = null;
    }
  }, delay);
}

Security Practices​

Encrypted JWTs​

Cookie Flags​

Access Token vs Bearer Token​

• Access token — what the token is for (authorizing API access)
• Bearer token — how the token is used (anyone who holds it can use it)

In standard REST APIs, the access token travels as a bearer token in the Authorization header. With encrypted JWTs, the bearer concept still applies — the server decrypts and verifies on each request.

Production Hardening​

Glossary​

Access Token​

A short-lived credential sent with each API request to prove the user is authenticated. Typically valid for 15 minutes.

Bearer Token​

A token authentication scheme where any party possessing the token can use it. Access tokens in web apps are bearer tokens by convention.

Refresh Token​

A long-lived credential used exclusively to obtain new access tokens, without requiring the user to log in again.

HTTP-only Cookie​

A browser cookie that cannot be read or written by JavaScript. Protects the refresh token from XSS-based theft.

CSRF (Cross-Site Request Forgery)​

An attack in which a malicious site tricks a user's browser into sending authenticated requests to another site. Mitigated here by sameSite: strict and scoping the refresh cookie to path: /refresh.

XSS (Cross-Site Scripting)​

A vulnerability allowing attackers to inject malicious JavaScript into your page. Keeping tokens out of localStorage/sessionStorage means XSS cannot steal them.

JWT (JSON Web Token)​

A signed token format used to transmit identity and authorization claims between parties.

Encrypted JWT (Custom Envelope)​

A JWT whose content is encrypted using AES before transmission, so only the server can read the payload. This guide uses a custom CryptoJS + JWT envelope — not the JWE standard (RFC 7516). For standards-compliant encrypted JWTs, use the jose library.

SameSite Cookie Policy​

A browser attribute controlling whether cookies are sent in cross-site requests. strict means the cookie is only sent when the request originates from the same site. Note: strict is incompatible with OAuth/SSO redirect flows — use lax in those cases.

CSP (Content Security Policy)​

An HTTP header that restricts which scripts and resources the browser is permitted to load, reducing the impact of XSS attacks.

Conclusion​

Secure bearer-token handling is not about a single storage choice, but about a full lifecycle: short-lived access tokens in memory, refresh tokens in HTTP-only cookies, strict server validation, and proactive refresh on the client. When combined with HTTPS, origin checks, token rotation, and CSP, this pattern provides a practical and production-ready baseline for modern web authentication.

For developers at Sadeem informatique

This guide defines best practices for using free-tier AI tools to support development work.
The goal is to improve productivity, learning, and code quality while keeping developers in control of architecture, logic, and security decisions.

Photo by Matheus Bertelli on Pexels.

1. Use AI as a Knowledge Assistant, Not a Code Replacement​

AI tools should primarily help developers understand concepts, not replace engineering decisions.

Appropriate Usage​

Frontend (React)​

• Ask AI to explain how React state differs from refs.
• Request a small example of a controlled form component.
• Ask why a component is re-rendering unnecessarily.

Backend (Laravel / NestJS)​

• Ask AI to explain middleware lifecycle.
• Request clarification on dependency injection in NestJS.
• Ask how Laravel queues work conceptually.

Avoid requesting full modules, features, or production-ready systems from AI tools.

2. Break Requests Into Small, Focused Questions​

Free-tier plans perform best with targeted prompts.

Instead of asking:
Build a full authentication system

Prefer asking step-by-step:

Frontend (React)​

1. How should I structure authentication context?
2. How do I store tokens securely in React apps?
3. Why is my protected route redirect looping?

Backend (Laravel)​

1. Explain how Laravel guards differ from middleware.
2. How can I structure authentication services cleanly?

Backend (NestJS)​

1. How do guards interact with interceptors?
2. What is the recommended folder structure for auth modules?

This approach produces clearer answers and reduces wasted usage.

Bad prompt  -> "Build full auth"
Good prompt -> "Explain auth context boundaries in React"

3. Prioritize Understanding Over Code Generation​

Developers should use AI to explain logic and review implementation choices.

Examples:

React​

Ask AI to review a component and explain:

• Why a hook dependency warning appears.
• Whether memoization is useful in this case.
• If state should be lifted or localized.

Laravel​

Ask AI to explain:

• Why a query might cause N+1 problems.
• Whether eager loading is appropriate.
• If a service class improves maintainability.

NestJS​

Ask AI to evaluate:

• Whether a provider should be singleton or request-scoped.
• If a controller contains too much business logic.

4. Use AI to Improve Debugging Strategy​

AI should guide investigation, not just provide fixes.

Example Prompts​

React​

• How do I systematically debug a component that renders twice?
• What tools should I use to inspect context updates?

Laravel​

• How do I trace a failed job through logs and queues?
• What steps should I follow to debug a slow query?

NestJS​

• How do I trace a request lifecycle across modules?
• Where should I log to debug injection failures?

This strengthens developer problem-solving skills across the team.

Context:
- Stack: React/Laravel/NestJS
- Symptom:
- Expected behavior:
- What I already tried:
- Logs / errors:

Question:
"Give me a step-by-step investigation path, not just a fix."

5. Validate All AI Output Before Use​

Any AI-generated suggestion must be:

• Reviewed by the developer
• Tested locally
• Checked against company coding standards
• Evaluated for security implications

Example: if AI suggests storing tokens in localStorage in a React app, developers must verify whether this aligns with company security policy.

6. Combine AI Advice With Internal Knowledge​

AI responses must be validated against:

• Official framework documentation (primary source).
• Official framework and programming language documentation (primary sources).
• Existing company codebases.
• Internal architecture standards.

Example: if AI proposes a new service pattern in Laravel, confirm it matches the company's existing service and repository structure before adopting it.

7. Never Share Sensitive Information​

When using public AI tools:

• Do not paste client data.
• Do not paste credentials or API keys.
• Avoid sharing proprietary business logic.
• Use anonymized examples when possible.

This protects both company and client assets.

+ Do this: "User A cannot access report endpoint (403)."
- Not this: "Client X with account #29431 and token abc123... cannot access..."

8. Use AI to Accelerate Learning, Not Shortcut Thinking​

Recommended learning uses:

Frontend (React)​

• Understanding performance optimization strategies.
• Learning accessibility best practices.
• Reviewing component design patterns.

Backend (Laravel / NestJS)​

• Exploring clean architecture patterns.
• Understanding caching strategies.
• Learning message queue patterns.

AI should help developers grow their expertise, not bypass it.

Teams that treat AI as a tutor improve faster than teams that treat AI as an autopilot.

9. Use AI for Repetitive Tasks and Boilerplate​

Free AI tools are ideal for reducing time spent on repetitive or boilerplate tasks. This helps speed development and reduces human error.

Frontend (React)​

• Generating boilerplate form validation code.
• Translating static content or labels for multiple languages.
• Creating repetitive UI components like tables, cards, or modals.

Backend (Laravel / NestJS)​

• Generating boilerplate CRUD endpoints.
• Producing standard DTOs or request validation classes.
• Automating repetitive configuration or migration templates.

Developers should still review AI-generated boilerplate to ensure it aligns with internal coding standards and project architecture.

Safe Division of Responsibility​

Conclusion​

Free-tier AI tools can significantly enhance developer effectiveness when used thoughtfully.
At Sadeem informatique, the goal is to use these tools to support learning, reinforce engineering standards, reduce repetitive effort, and improve code quality, not to replace developer judgment.