Instalação
Crie um novo app Next.js e execute-o localmente.
Início rápido
- Crie um novo app Next.js chamado
my-app - Use
cd my-appe inicie o dev server. - Acesse
http://localhost:3000.
pnpm create next-app@latest my-app --yes
cd my-app
pnpm devnpx create-next-app@latest my-app --yes
cd my-app
npm run devyarn create next-app@latest my-app --yes
cd my-app
yarn devbun create next-app@latest my-app --yes
cd my-app
bun dev--yespula os prompts usando preferências salvas ou padrões. A configuração padrão ativa TypeScript, Tailwind CSS, ESLint, App Router e Turbopack, com o alias de importação@/*, e inclui oAGENTS.mdpara orientar agentes de código a escrever código Next.js atualizado.
Requisitos do sistema
Antes de começar, confira se seu ambiente de desenvolvimento atende aos seguintes requisitos:
- Versão mínima do Node.js: 20.9
- Sistemas operacionais: macOS, Windows (incluindo WSL) e Linux.
Navegadores compatíveis
O Next.js funciona com navegadores modernos sem nenhuma configuração.
- Chrome 111+
- Edge 111+
- Firefox 111+
- Safari 16.4+
Saiba mais sobre o suporte a navegadores, incluindo como configurar polyfills e definir navegadores específicos como alvo.
Criar com a CLI
A forma mais rápida de criar um novo app Next.js é usando o create-next-app, que configura tudo automaticamente para você. Para criar um projeto, execute:
pnpm create next-appnpx create-next-app@latestyarn create next-appbun create next-appDurante a instalação, você verá os seguintes prompts:
What is your project named? my-app
Would you like to use the recommended Next.js defaults?
Yes, use recommended defaults - TypeScript, ESLint, No React Compiler, Tailwind CSS, No src/ directory, Cache Components, AGENTS.md
No, reuse previous settings
No, customize settings - Choose your own preferencesSe você escolher customize settings, verá os seguintes prompts:
Would you like to use TypeScript? No / Yes
Which linter would you like to use? ESLint / Biome / None
Would you like to use React Compiler? No / Yes
Would you like to use Tailwind CSS? No / Yes
Would you like your code inside a `src/` directory? No / Yes
Would you like to use Cache Components? No / Yes
Would you like to customize the import alias (`@/*` by default)? No / Yes
What import alias would you like configured? @/*
Would you like to include AGENTS.md to guide coding agents to write up-to-date Next.js code? No / YesDepois dos prompts, o create-next-app vai criar uma pasta com o nome do seu projeto e instalar as dependências necessárias.
Instalação manual
Para criar um novo app Next.js manualmente, instale os pacotes necessários:
pnpm i next@latest react@latest react-dom@latestnpm i next@latest react@latest react-dom@latestyarn add next@latest react@latest react-dom@latestbun add next@latest react@latest react-dom@latestBom saber:
- O
App Routerusa por padrão as versões canary do React, que incluem todas as mudanças estáveis do React 19, além de recursos mais novos que estão sendo validados em frameworks. Mesmo assim, você deve declarar react e react-dom no package.json para garantir compatibilidade com as ferramentas e com o ecossistema.- O
Pages Routerusa a versão do React definida no seupackage.json.
Depois, adicione os seguintes scripts ao seu arquivo package.json:
{
"scripts": {
"dev": "next dev",
"build": "next build",
"start": "next start",
"lint": "eslint",
"lint:fix": "eslint --fix"
}
}Esses scripts correspondem às diferentes etapas de desenvolvimento de um app:
next dev: inicia o dev server usando o Turbopack (bundler padrão).next build: gera o build do app para produção.next start: inicia o servidor de produção.eslint: executa o ESLint.
O Turbopack agora é o bundler padrão. Para usar o webpack, execute next dev --webpack ou next build --webpack. Veja a documentação do Turbopack para detalhes de configuração.
Crie o diretório app
O Next.js usa roteamento baseado no sistema de arquivos, ou seja, as rotas do seu app são definidas pela forma como você organiza os arquivos.
Crie uma pasta app. Depois, dentro dela, crie um arquivo layout.tsx. Esse arquivo é o layout raiz. Ele é obrigatório e precisa conter as tags <html> e <body>.
export default function RootLayout({
children,
}: {
children: React.ReactNode
}) {
return (
<html lang="en">
<body>{children}</body>
</html>
)
}export default function RootLayout({ children }) {
return (
<html lang="en">
<body>{children}</body>
</html>
)
}Crie uma página inicial app/page.tsx com um conteúdo inicial:
export default function Page() {
return <h1>Hello, Next.js!</h1>
}export default function Page() {
return <h1>Hello, Next.js!</h1>
}Tanto layout.tsx quanto page.tsx serão renderizados quando o usuário acessar a raiz do seu app (/).


Bom saber:
- Se você esquecer de criar o layout raiz, o Next.js vai criar esse arquivo automaticamente ao executar o dev server com
next dev.- Opcionalmente, você pode usar uma pasta
srcna raiz do projeto para separar o código do app dos arquivos de configuração.
Crie a pasta public (opcional)
Crie uma pasta public na raiz do projeto para armazenar arquivos estáticos, como imagens, fontes etc. Os arquivos dentro de public podem ser referenciados no seu código a partir da URL base (/).
Depois, você pode referenciar esses arquivos usando o caminho raiz (/). Por exemplo, public/profile.png pode ser referenciado como /profile.png:
import Image from 'next/image'
export default function Page() {
return <Image src="/profile.png" alt="Profile" width={100} height={100} />
}import Image from 'next/image'
export default function Page() {
return <Image src="/profile.png" alt="Profile" width={100} height={100} />
}Execute o dev server
- Execute
npm run devpara iniciar o dev server. - Acesse
http://localhost:3000para ver seu app. - Edite o arquivo
app/page.tsxe salve para ver o resultado atualizado no navegador.
Configure o TypeScript
Versão mínima do TypeScript:
v5.1.0
O Next.js já vem com suporte nativo ao TypeScript. Para adicionar TypeScript ao seu projeto, renomeie um arquivo para .ts / .tsx e execute next dev. O Next.js vai instalar automaticamente as dependências necessárias e adicionar um arquivo tsconfig.json com as opções de configuração recomendadas.
Plugin para IDE
O Next.js inclui um plugin personalizado de TypeScript e um verificador de tipos, que o VS Code e outros editores de código podem usar para verificação de tipos avançada e autocompletar.
Você pode ativar o plugin no VS Code assim:
- Abrindo a paleta de comandos (
Ctrl/⌘+Shift+P) - Pesquisando por "TypeScript: Select TypeScript Version"
- Selecionando "Use Workspace Version"

Veja a página de referência do TypeScript para mais informações.
Configure seu editor
O App Router nomeia arquivos por convenção, como page.tsx, layout.tsx e route.ts, então o editor logo fica cheio de abas com o mesmo nome. Identifique cada aba com as pastas em que ela está, como blog/[id], para diferenciá-las.
No VS Code 1.88+ ou no Cursor, adicione rótulos de editor personalizados ao .vscode/settings.json. Usar rótulos com duas pastas de profundidade evita que rotas dinâmicas como blog/[id]/page.tsx fiquem todas com o mesmo rótulo [id]:
{
"workbench.editor.customLabels.patterns": {
"**/app/**/page.tsx": "${dirname(1)}/${dirname} - page.tsx",
"**/app/**/layout.tsx": "${dirname(1)}/${dirname} - layout.tsx",
"**/app/**/loading.tsx": "${dirname(1)}/${dirname} - loading.tsx",
"**/app/**/error.tsx": "${dirname(1)}/${dirname} - error.tsx",
"**/app/**/not-found.tsx": "${dirname(1)}/${dirname} - not-found.tsx",
"**/app/**/template.tsx": "${dirname(1)}/${dirname} - template.tsx",
"**/app/**/default.tsx": "${dirname(1)}/${dirname} - default.tsx",
"**/app/**/route.ts": "${dirname(1)}/${dirname} - route.ts"
}
}Ou copie este prompt para que seu agente de código faça a configuração:
Set up custom editor labels so my Next.js App Router files are easy to tell apart. Read https://nextjs.org/docs/app/getting-started/installation#set-up-your-editor and add the workbench.editor.customLabels.patterns config shown there to my .vscode/settings.json, creating the file if it doesn't exist. Adjust the labels to taste. If I use a different editor, apply the equivalent setting or tell me it's automatic, and leave my other settings untouched.Bom saber: as IDEs da JetBrains (WebStorm, IntelliJ) mostram automaticamente a pasta dos arquivos com o mesmo nome, então não é preciso configurar nada.
Configure o linting
O Next.js oferece suporte a linting com ESLint ou Biome. Escolha um linter e execute-o diretamente pelos scripts do package.json.
- Use o ESLint (regras abrangentes):
{
"scripts": {
"lint": "eslint",
"lint:fix": "eslint --fix"
}
}- Ou use o Biome (linter + formatador rápido):
{
"scripts": {
"lint": "biome check",
"format": "biome format --write"
}
}Se seu projeto já usava next lint, migre seus scripts para a CLI do ESLint com o codemod:
npx @next/codemod@canary next-lint-to-eslint-cli .Se você usar o ESLint, crie uma configuração explícita (recomendado: eslint.config.mjs). O ESLint aceita tanto o formato legado .eslintrc.* quanto o novo formato eslint.config.mjs. Veja a referência da API do ESLint para uma configuração recomendada.
Bom saber: a partir do Next.js 16, o
next buildnão executa mais o linter automaticamente. Em vez disso, você pode executar seu linter pelos scripts do NPM.
Veja a página do plugin do ESLint para mais informações.
Configure importações absolutas e aliases de caminhos de módulos
O Next.js tem suporte nativo às opções "paths" e "baseUrl" dos arquivos tsconfig.json e jsconfig.json.
Essas opções permitem criar aliases de diretórios do projeto para caminhos absolutos, deixando as importações de módulos mais simples e limpas. Por exemplo:
// Before
import { Button } from '../../../components/button'
// After
import { Button } from '@/components/button'Para configurar importações absolutas, adicione a opção baseUrl ao seu arquivo tsconfig.json ou jsconfig.json. Por exemplo:
{
"compilerOptions": {
"baseUrl": "src/"
}
}Além de configurar o baseUrl, você pode usar a opção "paths" para criar "alias" de caminhos de módulos.
Por exemplo, a configuração a seguir mapeia @/components/* para components/*:
{
"compilerOptions": {
"baseUrl": "src/",
"paths": {
"@/styles/*": ["styles/*"],
"@/components/*": ["components/*"]
}
}
}Cada um dos "paths" é relativo à localização do baseUrl.
Atualize seu app Next.js
Mantenha a versão do Next.js atualizada. Cada release traz correções de segurança, correções de bugs e otimizações de performance junto com novos recursos, e manter-se atualizado deixa cada atualização pequena. Execute o comando upgrade:
pnpm next upgradenpx next upgradeyarn next upgradebunx next upgradeAtualizar também atualiza a documentação incluída no pacote next, em node_modules/next/dist/docs/. Novos recursos chegam com a documentação deles, e as páginas existentes ganham orientações novas e armadilhas descobertas ao longo do caminho. Os agentes de código com IA do seu projeto passam então a trabalhar com a versão que você tem instalada, em vez de depender dos dados de treinamento.
Para que um agente de código faça e verifique a atualização, execute npx next@canary upgrade --agent=latest. Veja Atualizar com um agente de código para outras políticas.
Veja Atualização para guias de versão e passos de atualização manual, ou a documentação de preview para conhecer recursos antes de chegarem a uma versão estável.