Flags da CLI create-next-app

Referência completa para todas as flags de linha de comando do create-next-app no Next.js 15, quando usar cada uma e comandos de copiar e colar para cenários comuns. Originado da documentação incluída em next/dist/docs/01-app/03-api-reference/06-cli/create-next-app.md.

Receita

Cartão de referência rápida - pronto para copiar e colar.

# The "everything on" command - TypeScript, Tailwind, App Router,
# src/ directory, custom alias, explicit npm, Turbopack, non-interactive
npx create-next-app@latest my-app \
  --typescript \
  --tailwind \
  --app \
  --src-dir \
  --import-alias "@/*" \
  --use-npm \
  --turbopack

Quando usar isso: Sempre que você quiser um comando de scaffolding reproduzível e não interativo em um README, um script de bootstrap ou um job de CI.

Exemplo de Trabalho

Todas as flags (Next.js 15)

Comandos de Cenário

# Minimal - TS and App Router, nothing else
npx create-next-app@latest my-app \
  --typescript --app \
  --no-tailwind --no-eslint --no-src-dir
 
# With Tailwind v4 (this cookbook's stack)
npx create-next-app@latest my-app \
  --typescript --tailwind --app \
  --import-alias "@/*"
 
# With a src/ directory (common in larger codebases)
npx create-next-app@latest my-app \
  --typescript --tailwind --app --src-dir
 
# Yes to all current defaults, skip every prompt
npx create-next-app@latest my-app --yes
 
# Skip every prompt and install, useful for CI
npx create-next-app@latest my-app --yes --skip-install --disable-git
 
# Bootstrap from an official example
npx create-next-app@latest my-blog --example blog-starter
 
# Bootstrap from any public GitHub repo
npx create-next-app@latest my-app \
  --example "https://github.com/vercel/next.js/tree/canary/examples/with-stripe-typescript"
 
# API-only project (route handlers, no app pages)
npx create-next-app@latest my-api --typescript --api
 
# React Compiler enabled from day one
npx create-next-app@latest my-app \
  --typescript --tailwind --app --react-compiler

Análise Profunda

Como Funciona

create-next-app é um scaffolder independente publicado no npm. Quando você o executa através de npx, pnpm create, yarn create ou bun create, o gerenciador de pacotes baixa o pacote para um cache temporário e executa sua entrada bin. A CLI:

1. Analisa as flags e as combina com quaisquer preferências armazenadas em ~/.config/create-next-app/.
2. Pergunta apenas por respostas que não foram fornecidas na linha de comando.
3. Escolhe um template - o template padrão, --empty para um template básico, ou o repositório apontado por -e / --example.
4. Copia os arquivos para o diretório de destino, reescrevendo nomes de pacotes.
5. Executa o comando de instalação do gerenciador de pacotes escolhido, a menos que --skip-install esteja definido.
6. Executa git init e um commit inicial, a menos que --disable-git esteja definido.
7. Escreve AGENTS.md e CLAUDE.md, a menos que --no-agents-md esteja definido.

Como as preferências armazenadas são respeitadas, dois desenvolvedores executando o mesmo comando create-next-app podem obter scaffolds diferentes. --reset-preferences ou passar todas as flags explicitamente garantem a determinismo.

Variações

• Modo interativo: omita todas as flags - npx create-next-app@latest - e responda às perguntas uma por uma. Bom para aprendizes; ruim para scripts.
• Fixar a versão da CLI: npx create-next-app@15.0.0 meu-app ... para que seu scaffold seja reproduzível meses depois.
• Pular git: --disable-git. Útil ao fazer scaffolding em um diretório existente.
• Pular instalação: --skip-install. Você pode então editar package.json antes de executar o instalador.
• Exemplo oficial: --example blog-starter. Veja a pasta examples/ no repositório vercel/next.js para a lista completa.
• URL do GitHub: --example "https://github.com/owner/repo/tree/branch/path". Combine com --example-path se o exemplo estiver em um monorepo.

Notas sobre TypeScript

As flags --typescript e --ts são aliases para o mesmo comportamento - ambas escrevem tsconfig.json com strict: true, moduleResolution: "bundler", o plugin Next registrado e caminhos @/* configurados. Todo o resto é idêntico.

Comparado a adicionar TypeScript manualmente depois (npm install -D typescript @types/react @types/node, então executar next dev), a flag economiza um passo: Next gera tsconfig.json automaticamente na primeira execução de next dev de qualquer maneira, mas a flag também instala as dependências de desenvolvimento e escreve next-env.d.ts antecipadamente. Para monorepos onde você já controla um tsconfig.base.json compartilhado, pular --typescript e configurar TS manualmente é às vezes mais limpo.

Armadilhas

1. --tailwind vs --no-tailwind - não há simetria --no-ts-style para todas as flags. A maioria das flags suporta --no-*, mas o texto de ajuda é a fonte da verdade; sempre verifique com create-next-app --help.
2. -e significa --example, não --eslint. As flags curtas são comprimidas e fáceis de digitar incorretamente. Use flags longas em scripts.
3. -ts não é uma flag curta - --ts requer dois hifens. Um único hífen -ts será analisado como -t -s e gerará um erro.
4. Padrões mudam entre versões do Next.js. Tailwind, ESLint e Turbopack se tornaram padrões relativamente recentemente. Se o seu README diz npx create-next-app@latest, o scaffold resultante irá variar ao longo do tempo; fixe em @15 ou passe todas as flags explicitamente.
5. --use-npm não bloqueia outros gerenciadores de pacotes. Ele seleciona npm como o instalador para a etapa de scaffolding; você ainda pode executar pnpm install depois no projeto e funcionará (você apenas terá ambos os lockfiles para limpar).
6. O modo interativo lembra respostas anteriores. Uma segunda execução no mesmo shell pode preencher silenciosamente respostas do cache. Use --reset-preferences ou --yes com flags explícitas para reprodutibilidade.
7. --yes segue quaisquer que sejam os padrões atuais. Um job de CI usando --yes produzirá uma saída diferente após um lançamento principal do Next.js. Prefira flags explícitas em CI.
8. --example desabilita a maioria das outras flags. Quando você faz bootstrap de um exemplo, flags como --tailwind ou --src-dir são ignoradas porque o exemplo já define sua própria estrutura.

Alternativas

FAQs

Revisão rápida desta página - clique para expandir.

Relacionados

• Configuração Básica do Next.js
• Next.js + Tailwind v4 + shadcn/ui