CLI de Next

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

Uso básico:

Terminal

npx 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 Hot Module Reloading, reporte de errores y más.
`build`	Crea una compilación optimizada para producción de tu 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 tu aplicación.
`telemetry`	Permite habilitar o deshabilitar la recolección completamente anónima de telemetría de Next.js.

Bueno saber: 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 Hot Module Reloading (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.
`--turbopack`	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 hostname en el cual iniciar la aplicación. Útil para hacer la aplicación disponible para otros dispositivos en la red. Por defecto: 0.0.0.0
`--experimental-https`	Inicia el servidor con HTTPS y genera un certificado auto-firmado.
`--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 trace de depuración a una URL HTTP remota.

Opciones de `next build`

next build crea una compilación optimizada para producción de tu 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 assets 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 assets 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. Apunta 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án salidas adicionales como rewrites, redirects y headers.

`--profile`	Habilita profiling 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 App Router.
`--experimental-build-mode [modo]`	Usa un modo de compilación experimental. (opciones: "compile", "generate", por defecto: "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. (por defecto: 3000, env: PORT)
`-H` o `--hostname <hostname>`	Especifica un hostname en el cual iniciar la aplicación (por defecto: 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 tu 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 el linting de 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 las extensiones de archivos JavaScript. (por defecto: [".js", ".mjs", ".cjs", ".jsx", ".ts", ".mts", ".cts", ".tsx"])
`-c, --config, <config>`	Usa este archivo de configuración, sobrescribiendo todas las otras opciones de configuración.
`--resolve-plugins-relative-to, <rprt>`	Especifica un directorio desde donde se deben resolver los plugins.
`--strict`	Crea un archivo `.eslintrc.json` usando la configuración estricta de Next.js.
`--rulesdir, <rulesdir...>`	Usa reglas adicionales desde 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. (por defecto: -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 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é. (por defecto: "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 puedes optar por no participar si prefieres 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.

Aprende 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: No se puede configurar PORT 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 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

Con el certificado generado, el servidor de desarrollo de Next.js estará disponible en https://localhost:3000. Se utiliza el puerto predeterminado 3000 a menos que se especifique un puerto con -p, --port o PORT.

También puede proporcionar un certificado y una 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 únicamente para desarrollo y crea un certificado localmente confiable con mkcert. En producción, utilice certificados emitidos adecuadamente por autoridades confiables.

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, de la siguiente manera:

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