CLI de Next.js

La CLI de Next.js le permite desarrollar, construir, iniciar su aplicación y más.

Uso básico:

Terminal

npm run next [comando] [opciones]

Referencia

Las siguientes opciones están disponibles:

Opciones	Descripción
`-h` o `--help`	Muestra todas las opciones disponibles
`-v` o `--version`	Muestra el número de versión de Next.js

Comandos

Los siguientes comandos están disponibles:

Comando	Descripción
`dev`	Inicia Next.js en modo desarrollo con Recarga de Módulos en Caliente (HMR), reporte de errores y más.
`build`	Crea una compilación optimizada para producción de su aplicación. Muestra información sobre cada ruta.
`start`	Inicia Next.js en modo producción. La aplicación debe ser compilada primero con `next build`.
`info`	Imprime detalles relevantes sobre el sistema actual que pueden usarse para reportar errores de Next.js.
`lint`	Ejecuta ESLint para todos los archivos en los directorios `/src`, `/app`, `/pages`, `/components` y `/lib`. También proporciona una configuración guiada para instalar las dependencias requeridas si ESLint no está configurado en su aplicación.
`telemetry`	Permite habilitar o deshabilitar la recolección completamente anónima de telemetría de Next.js.

Es bueno saberlo: Ejecutar next sin un comando es un alias para next dev.

Opciones de `next dev`

next dev inicia la aplicación en modo desarrollo con Recarga de Módulos en Caliente (HMR), reporte de errores y más. Las siguientes opciones están disponibles al ejecutar next dev:

Opción	Descripción
`-h, --help`	Muestra todas las opciones disponibles.
`[directorio]`	Un directorio en el cual construir la aplicación. Si no se proporciona, se usa el directorio actual.
`--turbo`	Inicia el modo desarrollo usando Turbopack.
`-p` o `--port <puerto>`	Especifica un número de puerto en el cual iniciar la aplicación. Por defecto: 3000, env: PORT
`-H`o `--hostname <hostname>`	Especifica un nombre de host en el cual iniciar la aplicación. Útil para hacer que la aplicación esté disponible para otros dispositivos en la red. Por defecto: 0.0.0.0
`--experimental-https`	Inicia el servidor con HTTPS y genera un certificado autofirmado.
`--experimental-https-key <ruta>`	Ruta a un archivo de clave HTTPS.
`--experimental-https-cert <ruta>`	Ruta a un archivo de certificado HTTPS.
`--experimental-https-ca <ruta>`	Ruta a un archivo de autoridad certificadora HTTPS.
`--experimental-upload-trace <traceUrl>`	Reporta un subconjunto del trazo de depuración a una URL HTTP remota.

Opciones de `next build`

next build crea una compilación optimizada para producción de su aplicación. La salida muestra información sobre cada ruta. Por ejemplo:

Terminal

Ruta (app)                              Tamaño     JS de Primera Carga
┌ ○ /_not-found                          0 B               0 kB
└ ƒ /products/[id]                       0 B               0 kB

○  (Estático)   prerenderizado como contenido estático
ƒ  (Dinámico)  renderizado en el servidor bajo demanda

Tamaño: El tamaño de los recursos descargados al navegar a la página del lado del cliente. El tamaño para cada ruta solo incluye sus dependencias.
JS de Primera Carga: El tamaño de los recursos descargados al visitar la página desde el servidor. La cantidad de JS compartido por todos se muestra como una métrica separada.

Ambos valores están comprimidos con gzip. La primera carga se indica con verde, amarillo o rojo. Apunte a verde para aplicaciones con buen rendimiento.

Las siguientes opciones están disponibles para el comando next build:

Opción	Descripción
`-h, --help`	Muestra todas las opciones disponibles.
`[directorio]`	Un directorio en el cual construir la aplicación. Si no se proporciona, se usará el directorio actual.
`-d` o `--debug`	Habilita una salida de compilación más detallada. Con esta bandera habilitada, se mostrará información adicional como reescrituras, redirecciones y encabezados.

`--profile`	Habilita el perfilado para React en producción.
`--no-lint`	Deshabilita el linting.
`--no-mangling`	Deshabilita el name mangling. Esto puede afectar el rendimiento y solo debe usarse para propósitos de depuración.
`--experimental-app-only`	Construye solo rutas del Enrutador de Aplicación.
`--experimental-build-mode [modo]`	Usa un modo de compilación experimental. (opciones: "compile", "generate", predeterminado: "default")

Opciones de `next start`

next start inicia la aplicación en modo producción. La aplicación debe ser compilada primero con next build.

Las siguientes opciones están disponibles para el comando next start:

Opción	Descripción
`-h` o `--help`	Muestra todas las opciones disponibles.
`[directorio]`	Un directorio en el cual iniciar la aplicación. Si no se proporciona un directorio, se usará el directorio actual.
`-p` o `--port <puerto>`	Especifica un número de puerto en el cual iniciar la aplicación. (predeterminado: 3000, env: PORT)
`-H` o `--hostname <hostname>`	Especifica un nombre de host en el cual iniciar la aplicación (predeterminado: 0.0.0.0).
`--keepAliveTimeout <keepAliveTimeout>`	Especifica la cantidad máxima de milisegundos para esperar antes de cerrar las conexiones inactivas.

next info imprime detalles relevantes sobre el sistema actual que pueden usarse para reportar errores de Next.js al abrir un issue en GitHub. Esta información incluye plataforma/arquitectura/versión del Sistema Operativo, Binarios (Node.js, npm, Yarn, pnpm), versiones de paquetes (next, react, react-dom) y más.

La salida debería verse así:

Terminal

Sistema Operativo:
  Plataforma: darwin
  Arquitectura: arm64
  Versión: Darwin Kernel Version 23.6.0
  Memoria disponible (MB): 65536
  Núcleos de CPU disponibles: 10
Binarios:
  Node: 20.12.0
  npm: 10.5.0
  Yarn: 1.22.19
  pnpm: 9.6.0
Paquetes Relevantes:
  next: 15.0.0-canary.115 // Se detecta la última versión disponible (15.0.0-canary.115).
  eslint-config-next: 14.2.5
  react: 19.0.0-rc
  react-dom: 19.0.0
  typescript: 5.5.4
Configuración de Next.js:
  output: N/A

Las siguientes opciones están disponibles para el comando next info:

Opción	Descripción
`-h` o `--help`	Muestra todas las opciones disponibles
`--verbose`	Recolecta información adicional para depuración.

Opciones de `next lint`

next lint ejecuta ESLint para todos los archivos en los directorios pages/, app/, components/, lib/ y src/. También proporciona una configuración guiada para instalar las dependencias requeridas si ESLint no está configurado en su aplicación.

Las siguientes opciones están disponibles para el comando next lint:

Opción	Descripción
`[directorio]`	Un directorio base en el cual ejecutar ESLint en la aplicación. Si no se proporciona, se usará el directorio actual.
`-d, --dir, <dirs...>`	Incluye directorio, o directorios, para ejecutar ESLint.
`--file, <files...>`	Incluye archivo, o archivos, para ejecutar ESLint.
`--ext, [exts...]`	Especifica extensiones de archivos JavaScript. (predeterminado: [".js", ".mjs", ".cjs", ".jsx", ".ts", ".mts", ".cts", ".tsx"])
`-c, --config, <config>`	Usa este archivo de configuración, anulando todas las demás opciones de configuración.
`--resolve-plugins-relative-to, <rprt>`	Especifica un directorio desde el cual se deben resolver los plugins.
`--strict`	Crea un archivo `.eslintrc.json` usando la configuración estricta de Next.js.
`--rulesdir, <rulesdir...>`	Usa reglas adicionales de este directorio(s).
`--fix`	Corrige automáticamente problemas de linting.
`--fix-type <fixType>`	Especifica los tipos de correcciones a aplicar (ej., problem, suggestion, layout).
`--ignore-path <ruta>`	Especifica un archivo a ignorar.
`--no-ignore <ruta>`	Deshabilita la opción `--ignore-path`.
`--quiet`	Reporta solo errores.
`--max-warnings [maxWarnings]`	Especifica el número de advertencias antes de activar un código de salida distinto de cero. (predeterminado: -1)
`-o, --output-file, <outputFile>`	Especifica un archivo para escribir el reporte.
`-f, --format, <format>`	Usa un formato de salida específico.
`--no-inline-config`	Previene que los comentarios cambien la configuración o reglas.
`--report-unused-disable-directives-severity <nivel>`	Especifica el nivel de severidad para las directivas eslint-disable no utilizadas. (opciones: "error", "off", "warn")
`--no-cache`	Deshabilita el caché.
`--cache-location, <cacheLocation>`	Especifica una ubicación para el caché.
`--cache-strategy, [cacheStrategy]`	Especifica una estrategia para detectar archivos cambiados en el caché. (predeterminado: "metadata")
`--error-on-unmatched-pattern`	Reporta errores cuando algún patrón de archivo no coincide.
`-h, --help`	Muestra este mensaje.

Opciones de `next telemetry`

Next.js recolecta datos de telemetría completamente anónimos sobre el uso general. La participación en este programa anónimo es opcional, y puede optar por no participar si prefiere no compartir información.

Las siguientes opciones están disponibles para el comando next telemetry:

Opción	Descripción
`-h, --help`	Muestra todas las opciones disponibles.
`--enable`	Habilita la recolección de telemetría de Next.js.
`--disable`	Deshabilita la recolección de telemetría de Next.js.

Aprenda más sobre Telemetría.

Ejemplos

Cambiar el puerto predeterminado

Por defecto, Next.js utiliza http://localhost:3000 durante el desarrollo y con next start. El puerto predeterminado se puede cambiar con la opción -p, de la siguiente manera:

Terminal

next dev -p 4000

O utilizando la variable de entorno PORT:

Terminal

PORT=4000 next dev

Nota importante: PORT no se puede configurar en .env ya que el inicio del servidor HTTP ocurre antes de que se inicialice cualquier otro código.

Usar HTTPS durante el desarrollo

Para ciertos casos de uso como webhooks o autenticación, puede ser necesario utilizar HTTPS para tener un entorno seguro en localhost. Next.js puede generar un certificado autofirmado con next dev usando la bandera --experimental-https:

Terminal

next dev --experimental-https

También puede proporcionar un certificado y clave personalizados con --experimental-https-key y --experimental-https-cert. Opcionalmente, puede proporcionar un certificado CA personalizado con --experimental-https-ca.

Terminal

next dev --experimental-https --experimental-https-key ./certificates/localhost-key.pem --experimental-https-cert ./certificates/localhost.pem

next dev --experimental-https está destinado solo para desarrollo y crea un certificado localmente confiable con mkcert. En producción, utilice certificados emitidos adecuadamente por autoridades confiables.

Nota importante: Al implementar en Vercel, HTTPS se configura automáticamente para su aplicación Next.js.

Configurar un tiempo de espera para proxies descendentes

Al implementar Next.js detrás de un proxy descendente (por ejemplo, un balanceador de carga como AWS ELB/ALB), es importante configurar el servidor HTTP subyacente de Next con tiempos de espera keep-alive que sean mayores que los tiempos de espera del proxy descendente. De lo contrario, una vez que se alcance un tiempo de espera keep-alive para una conexión TCP dada, Node.js terminará inmediatamente esa conexión sin notificar al proxy descendente. Esto resulta en un error del proxy cada vez que intenta reutilizar una conexión que Node.js ya ha terminado.

Para configurar los valores de tiempo de espera para el servidor de producción de Next.js, pase --keepAliveTimeout (en milisegundos) a next start, así:

Terminal

next start --keepAliveTimeout 70000

Pasar argumentos de Node.js

Puede pasar cualquier argumento de Node.js a los comandos next. Por ejemplo:

Terminal

NODE_OPTIONS='--throw-deprecation' next
NODE_OPTIONS='-r esm' next
NODE_OPTIONS='--inspect' next

Referencia

Comandos

Opciones de `next dev`

Opciones de `next build`

Opciones de `next start`

Opciones de `next info`

Opciones de `next lint`

Opciones de `next telemetry`

Ejemplos

Cambiar el puerto predeterminado

Usar HTTPS durante el desarrollo

Configurar un tiempo de espera para proxies descendentes

Pasar argumentos de Node.js

On this page