Installation

Core Idea

Como criar um projeto Next.js novo com create-next-app, os requisitos de sistema, e a configuração manual (TypeScript, absolute imports, linting) para quem monta o projeto na mão.

Key Concepts

create-next-app: CLI oficial que scaffolda um projeto completo com TypeScript, Tailwind CSS, ESLint, App Router e Turbopack habilitados por padrão.
--yes: flag que pula os prompts interativos usando defaults/preferências salvas.
Turbopack: bundler padrão a partir da versão atual; next dev --webpack ou next build --webpack volta para Webpack.
AGENTS.md: arquivo incluído por padrão (com CLAUDE.md referenciando-o) para orientar agentes de código a escrever Next.js atualizado.
Root layout: app/layout.tsx obrigatório, deve conter as tags <html> e <body>; se ausente, o next dev o cria automaticamente.
baseUrl e paths: opções do tsconfig.json/jsconfig.json para criar imports absolutos (@/components/button).
next upgrade: comando que atualiza Next.js e também a documentação embutida em node_modules/next/dist/docs/.

Code Examples

pnpm create next-app@latest my-app --yes
cd my-app
pnpm dev

O que demonstra: fluxo mínimo de criação e start do dev server.

// app/layout.tsx
export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  )
}

O que demonstra: estrutura mínima obrigatória do root layout.

// tsconfig.json
{
  "compilerOptions": {
    "baseUrl": "src/",
    "paths": {
      "@/components/*": ["components/*"]
    }
  }
}

O que demonstra: configuração de alias de import absoluto.

Reference Tables

Script	Comando	Função
`dev`	`next dev`	dev server com Turbopack
`build`	`next build`	build de produção
`start`	`next start`	server de produção
`lint`	`eslint`	roda o linter
`lint:fix`	`eslint --fix`	corrige automaticamente

Requisito	Valor
Node.js mínimo	20.9
SO	macOS, Windows (inclusive WSL), Linux
Browsers	Chrome 111+, Edge 111+, Firefox 111+, Safari 16.4+

Anti-patterns

Rodar next lint esperando lint automático no build: a partir do Next.js 16 next build não roda mais o linter, é preciso rodar via script npm separado.
Confundir Pages Router e App Router quanto à versão do React: App Router embute React canary (features estáveis do React 19 + novidades em validação); Pages Router usa a versão do package.json.

Key Takeaways

create-next-app --yes é o caminho mais rápido; customização manual via prompts interativos cobre TypeScript, linter (ESLint/Biome), React Compiler, Tailwind, src/, App Router e alias de import.
TypeScript é auto-configurado: renomear arquivo para .ts/.tsx e rodar next dev já instala dependências e gera tsconfig.json.
next upgrade deve ser rodado com frequência: atualizações pequenas e a documentação embutida ficam sincronizadas com a versão instalada, o que também alimenta agentes de IA com conhecimento atualizado.
Linter é ESLint ou Biome, escolhidos via script no package.json, não há mais integração automática no build.

Connects To

Project Structure: detalha o que cada arquivo/pasta criado aqui significa.
Layouts and Pages: expande o root layout criado nesta página.