Pular para o conteúdo
Documentação do Next.js PT-BR

Criar um novo app Next.js

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

Durante a instalação, você verá os seguintes prompts:

Terminal
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 preferences

Se você escolher customize settings, verá os seguintes prompts:

Terminal
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 / Yes

Depois 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@latest

Bom saber:

  • O App Router usa 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 Router usa a versão do React definida no seu package.json.

Depois, adicione os seguintes scripts ao seu arquivo package.json:

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 pages

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 um diretório pages na raiz do projeto. Depois, adicione um arquivo index.tsx dentro da pasta pages. Ele será sua página inicial (/):

pages/index.tsx
export default function Page() {
  return <h1>Hello, Next.js!</h1>
}

Em seguida, adicione um arquivo _app.tsx dentro de pages/ para definir o layout global. Saiba mais sobre o arquivo App personalizado.

pages/_app.tsx
import type { AppProps } from 'next/app'

export default function App({ Component, pageProps }: AppProps) {
  return <Component {...pageProps} />
}

Por fim, adicione um arquivo _document.tsx dentro de pages/ para controlar a resposta inicial do servidor. Saiba mais sobre o arquivo Document personalizado.

pages/_document.tsx
import { Html, Head, Main, NextScript } from 'next/document'

export default function Document() {
  return (
    <Html>
      <Head />
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  )
}

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:

app/page.tsx
import Image from 'next/image'

export default function Page() {
  return <Image src="/profile.png" alt="Profile" width={100} height={100} />
}

Execute o dev server

  1. Execute npm run dev para iniciar o dev server.
  2. Acesse http://localhost:3000 para ver seu app.
  3. Edite o arquivo pages/index.tsx e 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.

Veja a página de referência do TypeScript para mais informações.

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):
package.json
{
  "scripts": {
    "lint": "eslint",
    "lint:fix": "eslint --fix"
  }
}
  • Ou use o Biome (linter + formatador rápido):
package.json
{
  "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:

Terminal
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 build nã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:

tsconfig.json or jsconfig.json
{
  "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/*:

tsconfig.json or jsconfig.json
{
  "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 upgrade

Atualizar 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.