create-next-app

Core Idea

CLI oficial para criar um app Next.js novo com um único comando, usando o template default ou um example de um repositório GitHub público, é a forma mais fácil de começar com Next.js.

Key Concepts

• Uso básico: npx create-next-app@latest [project-name] [options] (ou equivalente pnpm/yarn/bun).
• Fluxo de prompts (default): nome do projeto → escolher "recommended defaults" (TypeScript, ESLint, Tailwind CSS, App Router, AGENTS.md) vs "reuse previous settings" vs "customize settings".
• Fluxo customizado: TypeScript sim/não, linter (ESLint/Biome/None), React Compiler, Tailwind CSS, src/ directory, App Router, import alias custom, AGENTS.md.
• --api: inicializa um projeto só com route handlers (sem UI/páginas).
• --agents-md: inclui AGENTS.md e CLAUDE.md para guiar coding agents (default habilitado).
• --empty: inicializa um projeto vazio.
• Linters disponíveis: ESLint (tradicional, regras Next.js via @next/eslint-plugin-next), Biome (linter+formatter rápido, com suporte nativo a Next.js/React), ou None.

Code Examples

npx create-next-app@latest

• O que demonstra: comando mínimo para iniciar o wizard interativo de criação de projeto.

npx create-next-app@latest --example [example-name] [your-project-name]

• O que demonstra: bootstrap a partir de um example oficial do repositório do Next.js.

npx create-next-app@latest --example "https://github.com/.../" [your-project-name]

• O que demonstra: bootstrap a partir de qualquer repositório GitHub público (não precisa ser um example oficial), passando a URL diretamente.

Reference Tables

Options	Description
-h or --help	Mostra todas as opções disponíveis.
-v or --version	Mostra a versão.
--no-*	Nega opção default, ex. --no-ts.
--ts or --typescript	Projeto TypeScript (default).
--js or --javascript	Projeto JavaScript.
--tailwind	Config Tailwind CSS (default).
--react-compiler	Habilita React Compiler.
--eslint	Config ESLint.
--biome	Config Biome.
--no-linter	Sem linter.
--app	App Router.
--api	Só route handlers.
--src-dir	Código dentro de src/.
--turbopack	Força Turbopack no package.json gerado (default habilitado).
--webpack	Força webpack no package.json gerado.
--import-alias <alias>	Alias de import (default "@/*").
--empty	Projeto vazio.
--use-npm/--use-pnpm/--use-yarn/--use-bun	Força o package manager usado no bootstrap.
-e or --example [name] [github-url]	Example para bootstrap.
--example-path <path>	Path do example dentro do repo.
--reset-preferences	Reseta preferências salvas.
--skip-install	Não instala pacotes.
--disable-git	Não inicializa git.
--agents-md	Inclui AGENTS.md/CLAUDE.md (default).
--yes	Usa preferências anteriores ou defaults para tudo.

Anti-patterns

• Não especificado explicitamente na página; a seção de exemplos foca em uso correto, não em erros comuns.

Key Takeaways

1. Turbopack vem habilitado por default no package.json gerado; webpack precisa ser forçado explicitamente com --webpack.
2. create-next-app guarda preferências entre execuções (--reset-preferences limpa isso, --yes reusa tudo sem perguntar).
3. Suporte a examples cobre tanto examples oficiais do repo do Next.js quanto qualquer repositório GitHub público via URL.
4. AGENTS.md/CLAUDE.md são incluídos por default desde essa versão, refletindo o foco em projetos trabalhados por coding agents.

Connects To

• CLI (cli, índice): página pai que lista create-next-app e next CLI.
• eslint-config-next: gerado automaticamente quando o linter escolhido é ESLint.