Compartir comentarios
Las respuestas se generan en base a la documentación.

Usa contenedores para el desarrollo con Next.js

Tabla de contenidos

Prerrequisitos

Completa Contenerizar una aplicación Next.js.

Descripción general

En esta sección, aprenderás a configurar entornos de producción y desarrollo para tu aplicación Next.js contenerizada usando Docker Compose. Esta configuración te permite ejecutar una compilación de producción usando el servidor standalone y desarrollar eficientemente dentro de contenedores usando la recarga rápida (hot reloading) integrada de Next.js con Compose Watch.

Aprenderás a:

  • Configurar contenedores separados para producción y desarrollo.
  • Habilitar la sincronización automática de archivos usando Compose Watch en desarrollo.
  • Depurar y previsualizar en vivo tus cambios en tiempo real sin reconstrucciones manuales.

Actualizar servicios automáticamente (Modo de desarrollo)

Usa Compose Watch para sincronizar automáticamente los cambios de los archivos fuente en tu entorno de desarrollo contenerizado. Esto sincroniza automáticamente los cambios de archivos sin necesidad de reiniciar o reconstruir los contenedores manualmente.

Paso 1: Crear un Dockerfile de desarrollo

Crea un archivo llamado Dockerfile.dev en la raíz de tu proyecto con el siguiente contenido (que coincide con el del proyecto de ejemplo):

# ============================================
# Development Dockerfile for Next.js
# ============================================
ARG NODE_VERSION=24.14.0-slim

FROM node:${NODE_VERSION} AS dev

WORKDIR /app

COPY package.json yarn.lock* package-lock.json* pnpm-lock.yaml* .npmrc* ./

RUN --mount=type=cache,target=/root/.npm \
    --mount=type=cache,target=/usr/local/share/.cache/yarn \
    --mount=type=cache,target=/root/.local/share/pnpm/store \
  if [ -f package-lock.json ]; then \
    npm ci --no-audit --no-fund; \
  elif [ -f yarn.lock ]; then \
    corepack enable yarn && yarn install --frozen-lockfile --production=false; \
  elif [ -f pnpm-lock.yaml ]; then \
    corepack enable pnpm && pnpm install --frozen-lockfile; \
  else \
    echo "No lockfile found." && exit 1; \
  fi

COPY . .

ENV WATCHPACK_POLLING=true
ENV HOSTNAME="0.0.0.0"

RUN chown -R node:node /app
USER node

EXPOSE 3000

CMD ["sh", "-c", "if [ -f package-lock.json ]; then npm run dev; elif [ -f yarn.lock ]; then yarn dev; elif [ -f pnpm-lock.yaml ]; then pnpm dev; else npm run dev; fi"]

Este archivo configura un entorno de desarrollo para tu aplicación Next.js con reemplazo rápido de módulos (hot module replacement) y es compatible con npm, yarn y pnpm.

Paso 2: Actualizar tu archivo compose.yaml

Abre tu archivo compose.yaml y define dos servicios: uno para producción (nextjs-prod-standalone) y otro para desarrollo (nextjs-dev). Esto coincide con la estructura del proyecto de ejemplo.

Aquí tienes un ejemplo de configuración para una aplicación Next.js:

services:
  nextjs-prod-standalone:
    build:
      context: .
      dockerfile: Dockerfile
    image: nextjs-sample:prod
    container_name: nextjs-sample-prod
    ports:
      - "3000:3000"

  nextjs-dev:
    build:
      context: .
      dockerfile: Dockerfile.dev
    image: nextjs-sample:dev
    container_name: nextjs-sample-dev
    ports:
      - "3000:3000"
    environment:
      - WATCHPACK_POLLING=true
    develop:
      watch:
        - action: sync
          path: .
          target: /app
          ignore:
            - node_modules/
            - .next/
        - action: rebuild
          path: package.json
  • El servicio nextjs-prod-standalone construye y ejecuta tu aplicación Next.js de producción utilizando la salida standalone.
  • El servicio nextjs-dev ejecuta tu servidor de desarrollo Next.js con reemplazo rápido de módulos.
  • watch activa la sincronización de archivos con Compose Watch.
  • WATCHPACK_POLLING=true asegura que los cambios de archivos se detecten correctamente dentro de Docker.
  • La acción rebuild para package.json asegura que las dependencias se vuelvan a instalar cuando cambie el archivo.
Note

Para obtener más detalles, consulta la guía oficial: Usar Compose Watch.

Paso 3: Configurar Next.js para el desarrollo con Docker

Next.js funciona bien dentro de contenedores Docker de forma predeterminada, pero hay algunas configuraciones que pueden mejorar la experiencia de desarrollo.

El archivo next.config.ts que creaste durante la contenerización ya incluye la opción output: "standalone" para producción. Para el desarrollo, Next.js utiliza automáticamente su servidor de desarrollo integrado con la recarga rápida habilitada.

Note

El servidor de desarrollo de Next.js de forma automática:

  • Habilita el reemplazo rápido de módulos (HMR) para actualizaciones instantáneas.
  • Monitorea los cambios de archivos y recompila automáticamente.
  • Proporciona mensajes de error detallados en el navegador.

La variable de entorno WATCHPACK_POLLING=true en el archivo de Compose asegura que el monitoreo de archivos funcione correctamente dentro de los contenedores Docker.

Después de completar los pasos anteriores, el directorio de tu proyecto debería contener los siguientes archivos:

├── docker-nextjs-sample/
│ ├── Dockerfile
│ ├── Dockerfile.dev
│ ├── .dockerignore
│ ├── compose.yaml
│ ├── next.config.ts
│ └── README.Docker.md

Paso 4: Iniciar Compose Watch

Ejecuta el siguiente comando desde la raíz de tu proyecto para iniciar tu contenedor en modo watch (monitoreo):

$ docker compose watch nextjs-dev

Paso 5: Probar Compose Watch con Next.js

Para verificar que Compose Watch esté funcionando correctamente:

  1. Abre el archivo app/page.tsx en tu editor de texto (o src/app/page.tsx si tu proyecto utiliza un directorio src).

  2. Localiza el área de contenido principal y busca un elemento de texto para modificar.

  3. Realiza un cambio visible, por ejemplo, actualiza un encabezado:

    <h1>Hello from Docker Compose Watch!</h1>

  4. Guarda el archivo.

  5. Abre tu navegador en http://localhost:3000.

Deberías ver el texto actualizado aparecer instantáneamente, sin necesidad de reconstruir el contenedor manualmente. Esto confirma que el monitoreo de archivos y la sincronización automática están funcionando como se esperaba.

Resumen

En esta sección, configuraste un flujo de trabajo de desarrollo y producción completo para tu aplicación Next.js utilizando Docker y Docker Compose.

Esto es lo que lograste:

  • Creaste un Dockerfile.dev para agilizar el desarrollo local con recarga rápida.
  • Definiste servicios separados nextjs-dev y nextjs-prod-standalone en tu archivo compose.yaml.
  • Habilitaste la sincronización de archivos en tiempo real usando Compose Watch para una experiencia de desarrollo más fluida.
  • Verificaste que las actualizaciones en vivo funcionan sin problemas modificando y previsualizando un componente.

Con esta configuración, puedes construir, ejecutar e iterar en tu aplicación Next.js completamente dentro de contenedores en cualquier entorno.

Recursos relacionados

Profundiza tus conocimientos y mejora tu flujo de trabajo de desarrollo contenerizado con estas guías:

Next steps

En la siguiente sección, aprenderás cómo ejecutar pruebas unitarias para tu aplicación Next.js dentro de contenedores Docker. Esto asegura pruebas consistentes en todos los entornos y elimina las dependencias de la configuración de la máquina local.

Ejecuta pruebas de Next.js en un contenedor »