Banderas CLI de create-next-app
Referencia completa para cada bandera de línea de comandos de create-next-app en Next.js 15, cuándo usar cada una y comandos listos para copiar y pegar en escenarios comunes. Obtenida de los docs agrupados en next/dist/docs/01-app/03-api-reference/06-cli/create-next-app.md.
Receta
Tarjeta de referencia rápida — lista para copiar y pegar.
# El comando "todo activado" — TypeScript, Tailwind, App Router,
# directorio src/, alias personalizado, npm explícito, Turbopack, no interactivo
npx create-next-app@latest my-app \
--typescript \
--tailwind \
--app \
--src-dir \
--import-alias "@/*" \
--use-npm \
--turbopackCuándo usarlo: En cualquier momento que quieras un comando de andamiaje reproducible y no interactivo en un README, un script de arranque o un trabajo de CI.
Ejemplo Funcional
Todas las banderas (Next.js 15)
| Bandera | Descripción | Predeterminado |
|---|---|---|
-h, --help | Mostrar todas las opciones disponibles | — |
-v, --version | Salida del número de versión | — |
--no-* | Negar cualquier opción predeterminada (p. ej. --no-ts, --no-tailwind) | — |
--ts, --typescript | Inicializar como un proyecto TypeScript | activado |
--js, --javascript | Inicializar como un proyecto JavaScript | desactivado |
--tailwind | Inicializar con Tailwind CSS | activado |
--react-compiler | Inicializar con React Compiler habilitado | desactivado |
--eslint | Inicializar con configuración ESLint | activado (cuando no se elige otro linter) |
--biome | Inicializar con configuración Biome | desactivado |
--no-linter | Omitir configuración de linter completamente | desactivado |
--app | Inicializar como un proyecto App Router | activado |
--api | Inicializar un proyecto solo con route handlers | desactivado |
--src-dir | Poner código dentro de un directorio src/ | desactivado |
--turbopack | Forzar Turbopack en package.json generado | activado |
--webpack | Forzar Webpack en package.json generado | desactivado |
--import-alias <alias> | Configurar el alias de importación | @/* |
--empty | Inicializar un proyecto vacío (archivos mínimos) | desactivado |
--use-npm | Arrancar con npm | — |
--use-pnpm | Arrancar con pnpm | — |
--use-yarn | Arrancar con Yarn | — |
--use-bun | Arrancar con Bun | — |
-e, --example <name-or-url> | Arrancar desde un ejemplo oficial o URL pública de GitHub | — |
--example-path <path> | Ruta dentro de un ejemplo de monorepo | — |
--reset-preferences | Reestablece cualquier respuesta almacenada de ejecuciones anteriores | desactivado |
--skip-install | Omitir la instalación de paquetes | desactivado |
--disable-git | No ejecutar git init | desactivado |
--agents-md | Incluir AGENTS.md y CLAUDE.md | activado |
--yes | Usar preferencias anteriores o valores predeterminados para todo | desactivado |
Comandos de escenario
# Mínimo — TS y App Router, nada más
npx create-next-app@latest my-app \
--typescript --app \
--no-tailwind --no-eslint --no-src-dir
# Con Tailwind v4 (la pila de este libro de recetas)
npx create-next-app@latest my-app \
--typescript --tailwind --app \
--import-alias "@/*"
# Con un directorio src/ (común en bases de código más grandes)
npx create-next-app@latest my-app \
--typescript --tailwind --app --src-dir
# Sí a todos los valores predeterminados actuales, omitir cada indicador
npx create-next-app@latest my-app --yes
# Omitir cada indicador e instalación, útil para CI
npx create-next-app@latest my-app --yes --skip-install --disable-git
# Arrancar desde un ejemplo oficial
npx create-next-app@latest my-blog --example blog-starter
# Arrancar desde cualquier repo público de GitHub
npx create-next-app@latest my-app \
--example "https://github.com/vercel/next.js/tree/canary/examples/with-stripe-typescript"
# Proyecto solo API (route handlers, sin páginas de app)
npx create-next-app@latest my-api --typescript --api
# React Compiler habilitado desde el primer día
npx create-next-app@latest my-app \
--typescript --tailwind --app --react-compilerInmersión Profunda
Cómo Funciona
create-next-app es un andamiador independiente publicado en npm. Cuando lo ejecutas a través de npx, pnpm create, yarn create o bun create, el gestor de paquetes descarga el paquete a un caché temporal y ejecuta su entrada bin. La CLI:
- Analiza banderas y las fusiona con cualquier preferencia almacenada bajo
~/.config/create-next-app/. - Solo solicita respuestas que no fueron proporcionadas en la línea de comandos.
- Elige una plantilla — la plantilla predeterminada,
--emptypara una minimalista, o el repo señalado por-e/--example. - Copia archivos al directorio de destino, reescribiendo nombres de paquetes.
- Ejecuta el comando de instalación del gestor de paquetes elegido a menos que
--skip-installesté establecido. - Ejecuta
git inity una confirmación inicial a menos que--disable-gitesté establecido. - Escribe
AGENTS.mdyCLAUDE.mda menos que--no-agents-mdesté establecido.
Debido a que se respetan las preferencias almacenadas, dos desarrolladores ejecutando el mismo comando create-next-app pueden obtener andamios diferentes. --reset-preferences o pasar cada bandera explícitamente garantiza determinismo.
Variaciones
- Modo interactivo: omite cada bandera —
npx create-next-app@latest— y responde indicadores uno por uno. Bueno para aprendices; malo para scripts. - Fija la versión de la CLI:
npx create-next-app@15.0.0 my-app ...para que tu andamio sea reproducible meses después. - Omitir git:
--disable-git. Útil cuando se andamia en un monorepo existente. - Omitir instalación:
--skip-install. Luego puedes editarpackage.jsonantes de ejecutar el instalador tú mismo. - Ejemplo oficial:
--example blog-starter. Consulta la carpetaexamples/en el repovercel/next.jspara ver la lista completa. - Ejemplo de URL de GitHub:
--example "https://github.com/owner/repo/tree/branch/path". Combina con--example-pathsi el ejemplo vive profundamente dentro de un monorepo.
Notas de TypeScript
Las banderas --typescript y --ts son alias para el mismo comportamiento exacto — ambas escriben tsconfig.json con strict: true, moduleResolution: "bundler", el plugin de Next registrado y rutas @/* configuradas. Todo lo demás es idéntico.
Comparado con agregar TypeScript manualmente después (npm install -D typescript @types/react @types/node, luego ejecutar next dev), la bandera ahorra un paso: Next genera tsconfig.json automáticamente en la primera ejecución de next dev de todos modos, pero la bandera también instala las dependencias de desarrollo e escribe next-env.d.ts por adelantado. Para monorepos donde ya controlas un tsconfig.base.json compartido, omitir --typescript e implementar TS tú mismo a veces es más limpio.
Gotchas
--tailwindvs--no-tailwind— no hay simetría de estilo--no-tspara cada bandera. La mayoría de las banderas admiten--no-*, pero el texto de ayuda es la fuente de verdad; siempre verifica concreate-next-app --help.-esignifica--example, no--eslint. Las banderas cortas se comprimen y son fáciles de escribir mal. Usa banderas largas en scripts.-tsno es una bandera corta —--tsrequiere dos guiones. Un guion único-tsserá analizado como-t -sy generará error.- Los valores predeterminados cambian entre versiones de Next.js. Tailwind, ESLint y Turbopack se convirtieron en valores predeterminados relativamente recientemente. Si tu README dice
npx create-next-app@latest, el andamio resultante variará con el tiempo; fija a@15o pasa cada bandera explícitamente. --use-npmno bloquea otros gestores de paquetes. Selecciona npm como el instalador para el paso de andamiaje; aún puedes ejecutarpnpm installdespués en el proyecto y funcionará (solo tendrás que limpiar ambos lockfiles).- El modo interactivo recuerda respuestas anteriores. Una segunda ejecución en el mismo shell puede rellenar silenciosamente respuestas desde el caché. Usa
--reset-preferenceso--yescon banderas explícitas para reproducibilidad. --yessigue los valores predeterminados actuales. Un trabajo de CI que usa--yesproducirá diferentes resultados después de una versión principal de Next.js. Prefiere banderas explícitas en CI.--exampledesactiva la mayoría de otras banderas. Cuando arranques desde un ejemplo, banderas como--tailwindo--src-dirse ignoran porque el ejemplo ya define su propia estructura.
Alternativas
| Herramienta | Comando | Cuándo usar |
|---|---|---|
| Configuración manual | npm init -y && npm install next react react-dom | Control total, sin ruido de plantilla, eres cómodo escribiendo app/layout.tsx a mano |
| Turborepo | npx create-turbo@latest | Quieres un monorepo con múltiples apps (Next.js + packages) andamiados juntos |
| T3 Stack | npx create-t3-app@latest | Quieres Next.js + Prisma + tRPC + NextAuth + Tailwind pre-cableados |
| Galería de plantillas de Vercel | npx create-next-app@latest --example <template> | Quieres un iniciador de forma productiva (comercio, blog, portafolio) |
Preguntas Frecuentes
Revisión rápida de esta página — haz clic para expandir.
¿Cuál es la diferencia entre --ts y --typescript?
Ninguna. Son alias para la misma bandera exacta y producen el mismo tsconfig.json, dependencias y next-env.d.ts.
¿Cómo me desactivo de una bandera predeterminada?
Prefijalo con --no-. Por ejemplo, --no-tailwind, --no-eslint, --no-src-dir. Gotcha: no todas las banderas admiten negación; ejecuta create-next-app --help para confirmar.
¿Qué hace --yes?
Omite cada indicador y usa tus preferencias almacenadas si existen, de lo contrario los valores predeterminados actuales. Seguro para primeras ejecuciones; riesgoso en scripts de larga duración porque los valores predeterminados varían.
¿Puedo omitir git init?
Sí — pasa --disable-git. Útil cuando se andamia en un directorio que ya es un repo git o un monorepo.
¿Puedo omitir npm install?
Sí — pasa --skip-install. La CLI aún copiará archivos e inicializará git; ejecutas el instalador tú mismo después.
¿Cómo arranco desde un ejemplo de GitHub?
npx create-next-app@latest my-app --example "https://github.com/owner/repo/tree/branch/path/to/example". Funciona para cualquier repo público de GitHub.
¿Para qué es --empty?
Crea un proyecto mínimo sin contenido de demostración — sin estilos iniciadores, sin componentes de ejemplo — solo los archivos que necesitas para que el router arranque.
¿Previene --use-npm que use pnpm después?
No. Solo controla qué instalador se ejecuta durante el andamiaje. Puedes cambiar gestores de paquetes después. Gotcha: elimina el lockfile antiguo primero o terminarás con ambos package-lock.json y pnpm-lock.yaml.
¿Por qué mi andamio se vio diferente hoy que la semana pasada?
Estás ejecutando @latest y los valores predeterminados cambiaron entre versiones de Next.js. Fija la versión: create-next-app@15.0.0. Gotcha: esto sucede silenciosamente, a menudo después de una versión menor de Next.js.
¿Hay una manera de forzar Webpack en lugar de Turbopack?
Sí — --webpack escribe package.json generado para que next dev y next build usen Webpack.
¿Difiere --typescript de agregar TS manualmente después?
Funcionalmente, no. Ambos terminan con el mismo tsconfig.json porque Next lo genera en la primera ejecución de todos modos. Nota TS: la bandera además pre-instala typescript, @types/react y @types/node para que la primera next dev no se pause para instalarlos.
¿Qué hace exactamente --react-compiler?
Implementa el React Compiler (la herramienta de memoización en tiempo de compilación) en next.config.ts desde el inicio. Nota TS: el compilador es ortogonal a TypeScript — afecta la salida de compilación, no el sistema de tipos.