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 \
  --turbopack

Cuá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)

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-compiler

Inmersió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:

1. Analiza banderas y las fusiona con cualquier preferencia almacenada bajo ~/.config/create-next-app/.
2. Solo solicita respuestas que no fueron proporcionadas en la línea de comandos.
3. Elige una plantilla - la plantilla predeterminada, --empty para una minimalista, o el repo señalado por -e / --example.
4. Copia archivos al directorio de destino, reescribiendo nombres de paquetes.
5. Ejecuta el comando de instalación del gestor de paquetes elegido a menos que --skip-install esté establecido.
6. Ejecuta git init y una confirmación inicial a menos que --disable-git esté establecido.
7. Escribe AGENTS.md y CLAUDE.md a menos que --no-agents-md esté 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 editar package.json antes de ejecutar el instalador tú mismo.
• Ejemplo oficial: --example blog-starter. Consulta la carpeta examples/ en el repo vercel/next.js para ver la lista completa.
• Ejemplo de URL de GitHub: --example "https://github.com/owner/repo/tree/branch/path". Combina con --example-path si 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

1. --tailwind vs --no-tailwind - no hay simetría de estilo --no-ts para cada bandera. La mayoría de las banderas admiten --no-*, pero el texto de ayuda es la fuente de verdad; siempre verifica con create-next-app --help.
2. -e significa --example, no --eslint. Las banderas cortas se comprimen y son fáciles de escribir mal. Usa banderas largas en scripts.
3. -ts no es una bandera corta - --ts requiere dos guiones. Un guion único -ts será analizado como -t -s y generará error.
4. 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 @15 o pasa cada bandera explícitamente.
5. --use-npm no bloquea otros gestores de paquetes. Selecciona npm como el instalador para el paso de andamiaje; aún puedes ejecutar pnpm install después en el proyecto y funcionará (solo tendrás que limpiar ambos lockfiles).
6. El modo interactivo recuerda respuestas anteriores. Una segunda ejecución en el mismo shell puede rellenar silenciosamente respuestas desde el caché. Usa --reset-preferences o --yes con banderas explícitas para reproducibilidad.
7. --yes sigue los valores predeterminados actuales. Un trabajo de CI que usa --yes producirá diferentes resultados después de una versión principal de Next.js. Prefiere banderas explícitas en CI.
8. --example desactiva la mayoría de otras banderas. Cuando arranques desde un ejemplo, banderas como --tailwind o --src-dir se ignoran porque el ejemplo ya define su propia estructura.

Alternativas

Preguntas Frecuentes

Revisión rápida de esta página - haz clic para expandir.

Relacionado

• Configuración Básica de Next.js
• Next.js + Tailwind v4 + shadcn/ui