Configuração Básica do Next.js

Q: Qual flag seleciona o App Router?

--app. Sem ela, create-next-app pode usar o App Router por padrão no Next 15, mas a flag torna a escolha explícita e não interativa.

Q: Como desativo o Tailwind e o ESLint ao mesmo tempo?

Passe --no-tailwind --no-eslint para create-next-app. Ambas as flags são necessárias porque cada uma é ativada por padrão no Next 15.

Q: O que --import-alias "@/*" realmente configura?

Ele escreve uma entrada paths em tsconfig.json para que @/lib/x resolva para ./lib/x (ou ./src/lib/x se você usou --src-dir).

Q: Por que meu app/page.tsx é um Server Component por padrão?

Tudo em app/ é um Server Component, a menos que o arquivo comece com "use client". É por isso que você pode usar await dentro do corpo do componente.

Q: O que acontece se a porta 3000 estiver ocupada?

next dev sai com EADDRINUSE. Execute npm run dev -- -p 3001 ou mate o processo que está escutando na porta 3000. Armadilha: algumas versões mais antigas do Next aumentavam automaticamente a porta; o Next 15 não faz isso.

Q: Como habilito o TypeScript estrito?

Já está ativado. create-next-app escreve "strict": true em tsconfig.json por padrão quando você passa --typescript. Nota TS: isso também habilita strictNullChecks, noImplicitAny e similares.

Q: Por que minha chamada fetch atinge a rede a cada requisição?

O Next 15 mudou o padrão: fetch não é mais cacheado, a menos que você opte por isso. Adicione next: \{ revalidate: 60 \} ou cache: "force-cache" às opções do fetch.

A configuração mais mínima do Next.js 15 - create-next-app puro com TypeScript e o App Router, nada mais. Sem Tailwind, sem ESLint, sem diretório src/. Apenas o essencial para um projeto com Server Components primeiro no React 19.

Receita

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

# Cria o app com apenas as flags que queremos
npx create-next-app@latest my-app \
  --typescript \
  --app \
  --no-tailwind \
  --no-eslint \
  --no-src-dir \
  --import-alias "@/*"
 
# Entra no projeto e inicia o servidor de desenvolvimento
cd my-app
npm run dev

Quando usar isso: Aprendendo Next.js, escrevendo um repro de bug mínimo e reproduzível, ou iniciando um projeto onde você planeja adicionar suas próprias ferramentas (Biome, Vanilla Extract, seu próprio linter) em vez de aceitar os padrões.

Exemplo de Trabalho

Após a conclusão da receita acima, você terá o seguinte layout de diretório:

my-app/
├── app/
│   ├── favicon.ico
│   ├── globals.css
│   ├── layout.tsx
│   └── page.tsx
├── public/
│   ├── next.svg
│   └── vercel.svg
├── next.config.ts
├── next-env.d.ts
├── package.json
├── tsconfig.json
└── README.md

O layout raiz é um Server Component e envolve todas as rotas:

// app/layout.tsx
import type { Metadata } from "next";
import "./globals.css";
 
export const metadata: Metadata = {
  title: "My App",
  description: "Configuração mínima de Next.js 15 + React 19",
};
 
export default function RootLayout({
  children,
}: Readonly<{ children: React.ReactNode }>) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}

Uma página Server Component que busca dados no momento da requisição - sem useEffect, sem custo de bundle do cliente:

// app/page.tsx
type Post = { id: number; title: string };
 
async function getPosts(): Promise<Post[]> {
  const res = await fetch("https://jsonplaceholder.typicode.com/posts?_limit=5", {
    // Next 15 usa como padrão nenhuma cache automática para fetch; opte explicitamente
    next: { revalidate: 60 },
  });
  if (!res.ok) throw new Error("Falha ao buscar posts");
  return res.json();
}
 
export default async function HomePage() {
  const posts = await getPosts();
  return (
    <main>
      <h1>Últimos posts</h1>
      <ul>
        {posts.map((p) => (
          <li key={p.id}>{p.title}</li>
        ))}
      </ul>
    </main>
  );
}

O tsconfig.json gerado ativa o modo estrito e configura o alias @/*:

// tsconfig.json (abreviado)
{
  "compilerOptions": {
    "target": "ES2022",
    "lib": ["dom", "dom.iterable", "esnext"],
    "strict": true,
    "noEmit": true,
    "esModuleInterop": true,
    "module": "esnext",
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "jsx": "preserve",
    "incremental": true,
    "plugins": [\{ "name": "next" \}],
    "paths": \{ "@/*": ["./*"] \}
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
  "exclude": ["node_modules"]
}

E o arquivo de configuração agora é TypeScript por padrão:

// next.config.ts
import type { NextConfig } from "next";
 
const nextConfig: NextConfig = {
  // Adicione a configuração aqui conforme necessário.
};
 
export default nextConfig;

Mergulho Profundo

Como Funciona

create-next-app é um pequeno gerador de estrutura distribuído como seu próprio pacote npm. Quando você executa npx create-next-app@latest, o npx baixa a versão mais recente publicada em um cache temporário, a executa e passa os argumentos restantes para ela. O gerador copia um diretório de template de dentro do pacote, executa a instalação do seu gerenciador de pacotes escolhido e (a menos que --disable-git seja definido) executa git init com um commit inicial.

Cada flag na receita corresponde 1:1 a uma resposta a um prompt interativo, então --typescript --app --no-tailwind --no-eslint --no-src-dir é o mesmo que responder manualmente a esses cinco prompts. Passar todos os cinco significa que create-next-app é executado de forma não interativa e sua configuração é reproduzível em CI.

Após a instalação, npm run dev inicia o servidor de desenvolvimento do Next.js. No Next 15, o Turbopack é o bundler de desenvolvimento padrão - você não precisa de uma flag separada.

Variações

Desenvolvimento com Turbopack (explícito): está ativado por padrão, mas você pode forçá-lo em package.json com "dev": "next dev --turbopack".
Porta personalizada: npm run dev -- -p 4000 ou defina PORT=4000 npm run dev.
Diretório personalizado: passe qualquer caminho como nome do projeto, por exemplo, npx create-next-app@latest ./apps/web ....
Sem git init: adicione --disable-git ao comando.
Configuração manual: mkdir my-app && cd my-app && npm init -y && npm install next@latest react@latest react-dom@latest && npm install -D typescript @types/react @types/node, em seguida, crie app/layout.tsx e app/page.tsx manualmente; o Next gera next-env.d.ts na primeira execução.
pnpm: pnpm create next-app my-app --typescript --app --no-tailwind --no-eslint --no-src-dir.
yarn: yarn create next-app my-app --typescript --app --no-tailwind --no-eslint --no-src-dir.
bun: bun create next-app my-app --typescript --app --no-tailwind --no-eslint --no-src-dir.

Notas sobre TypeScript

A flag --typescript escreve um tsconfig.json com strict: true, moduleResolution: "bundler", e o plugin TypeScript do Next.js registrado em compilerOptions.plugins. Esse plugin é o que habilita o autocompletar para metadata, parâmetros de rota e os tipos de rota gerados em .next/types/.

A entrada paths "@/*": ["./*"] é relativa à raiz do projeto, não a src/, porque você optou por não usar --src-dir. Se você mover arquivos para src/ posteriormente, deverá atualizar o alias para "@/*": ["./src/*"].

next-env.d.ts é gerado automaticamente a cada desenvolvimento/build. Não o edite; não o exclua. O .gitignore padrão o inclui.

Armadilhas

App Router vs Pages Router. O diretório app/ é o App Router. Se você também criar um diretório pages/, ambos os roteadores serão executados lado a lado e você terá conflitos em rotas compartilhadas. Exclua pages/ a menos que você esteja migrando intencionalmente.
Posicionamento de src/ vs app/ raiz. Com --no-src-dir, o App Router fica em ./app. Se algum tutorial disser para colocar arquivos em ./src/app, esse é o layout com --src-dir; misturar os dois quebra silenciosamente as importações.
Os padrões mudam entre as versões do Next.js. No Next 15, os prompts padrão incluem Turbopack e AGENTS.md - flags que não existiam no Next 13 ou 14. Sempre fixe em @latest ou uma versão exata em sua documentação.
Node.js 18.18 ou mais recente é necessário. O Next 15 se recusa a iniciar em Node 18.17 e anteriores. Execute node -v antes de npm run dev; use nvm para alternar se você estiver em um LTS mais antigo.
Porta 3000 já em uso. npm run dev falhará com EADDRINUSE se outro processo estiver usando a porta 3000. Mate o processo (lsof -iTCP:3000 -sTCP:LISTEN) ou execute com -p 3001.
fetch não é cacheado por padrão no Next 15. Se você espera o comportamento antigo de "fetch é cacheado para sempre" do Next 13/14, você deve optar explicitamente com next: \{ revalidate: N \} ou cache: "force-cache".
next.config.ts requer um runtime Node ciente de TypeScript. Funciona diretamente no Next 15, mas algumas ferramentas mais antigas que chamam next build de um script Node simples podem reclamar - volte para next.config.mjs se encontrar isso.

Alternativas

Ferramenta	Quando usar	Contrapartida vs Next.js 15
Vite + React Router	SPAs, dashboards protegidos por autenticação, sem necessidades de SEO	Sem Server Components, sem SSR integrado, sem roteamento baseado em sistema de arquivos
Remix	Aplicativos com muitos formulários, roteamento aninhado, aprimoramento progressivo	Ecossistema menor; modelo de carregamento de dados diferente (`loader`/`action`)
Astro	Sites de conteúdo, páginas de marketing, blogs	React é um convidado; sem história completa de Server Components do React 19
Next.js Pages Router	Bases de código legadas, bibliotecas ainda vinculadas a `getServerSideProps`	Sendo substituído pelo App Router; sem Server Components

FAQs

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

Qual flag seleciona o App Router?

--app. Sem ela, create-next-app pode usar o App Router por padrão no Next 15, mas a flag torna a escolha explícita e não interativa.

Como desativo o Tailwind e o ESLint ao mesmo tempo?

Passe --no-tailwind --no-eslint para create-next-app. Ambas as flags são necessárias porque cada uma é ativada por padrão no Next 15.

O que `--import-alias "@/*"` realmente configura?

Ele escreve uma entrada paths em tsconfig.json para que @/lib/x resolva para ./lib/x (ou ./src/lib/x se você usou --src-dir).

Por que meu `app/page.tsx` é um Server Component por padrão?

Tudo em app/ é um Server Component, a menos que o arquivo comece com "use client". É por isso que você pode usar await dentro do corpo do componente.

Preciso de uma flag `--turbopack` separada no Next 15?

Não. Turbopack é o bundler de desenvolvimento padrão. A flag só é útil se você quiser fixá-la em package.json para clareza.

Qual é a versão mínima do Node.js?

18.18.0. Qualquer versão anterior falha na inicialização. Armadilha: várias imagens de CI populares ainda enviam 18.17 por padrão.

O que acontece se a porta 3000 estiver ocupada?

next dev sai com EADDRINUSE. Execute npm run dev -- -p 3001 ou mate o processo que está escutando na porta 3000. Armadilha: algumas versões mais antigas do Next aumentavam automaticamente a porta; o Next 15 não faz isso.

É seguro editar `next-env.d.ts`?

Não. Ele é regenerado a cada build e quaisquer edições serão perdidas. Mantenha-o commitado e intocado.

Como habilito o TypeScript estrito?

Já está ativado. create-next-app escreve "strict": true em tsconfig.json por padrão quando você passa --typescript. Nota TS: isso também habilita strictNullChecks, noImplicitAny e similares.

Por que minha chamada `fetch` atinge a rede a cada requisição?

O Next 15 mudou o padrão: fetch não é mais cacheado, a menos que você opte por isso. Adicione next: \{ revalidate: 60 \} ou cache: "force-cache" às opções do fetch.

Posso tipar `next.config.ts` com IntelliSense completo?

Sim. Importe NextConfig de next e anote a constante exportada. Nota TS: NextConfig é o tipo canônico no Next 15; o comentário JSDoc mais antigo /** @type \{import('next').NextConfig\} */ não é mais necessário.

Qual é a diferença entre `app/` e `pages/`?

app/ é o App Router (React 19, Server Components, layouts, streaming). pages/ é o legado Pages Router. Você pode executar ambos, mas inicie novos projetos apenas em app/.

Relacionado

Receita

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

# Cria o app com apenas as flags que queremos
npx create-next-app@latest my-app \
  --typescript \
  --app \
  --no-tailwind \
  --no-eslint \
  --no-src-dir \
  --import-alias "@/*"
 
# Entra no projeto e inicia o servidor de desenvolvimento
cd my-app
npm run dev

Exemplo de Trabalho

Após a conclusão da receita acima, você terá o seguinte layout de diretório:

my-app/
├── app/
│   ├── favicon.ico
│   ├── globals.css
│   ├── layout.tsx
│   └── page.tsx
├── public/
│   ├── next.svg
│   └── vercel.svg
├── next.config.ts
├── next-env.d.ts
├── package.json
├── tsconfig.json
└── README.md

O layout raiz é um Server Component e envolve todas as rotas:

// app/layout.tsx
import type { Metadata } from "next";
import "./globals.css";
 
export const metadata: Metadata = {
  title: "My App",
  description: "Configuração mínima de Next.js 15 + React 19",
};
 
export default function RootLayout({
  children,
}: Readonly<{ children: React.ReactNode }>) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}

Uma página Server Component que busca dados no momento da requisição - sem useEffect, sem custo de bundle do cliente:

// app/page.tsx
type Post = { id: number; title: string };
 
async function getPosts(): Promise<Post[]> {
  const res = await fetch("https://jsonplaceholder.typicode.com/posts?_limit=5", {
    // Next 15 usa como padrão nenhuma cache automática para fetch; opte explicitamente
    next: { revalidate: 60 },
  });
  if (!res.ok) throw new Error("Falha ao buscar posts");
  return res.json();
}
 
export default async function HomePage() {
  const posts = await getPosts();
  return (
    <main>
      <h1>Últimos posts</h1>
      <ul>
        {posts.map((p) => (
          <li key={p.id}>{p.title}</li>
        ))}
      </ul>
    </main>
  );
}

O tsconfig.json gerado ativa o modo estrito e configura o alias @/*:

// tsconfig.json (abreviado)
{
  "compilerOptions": {
    "target": "ES2022",
    "lib": ["dom", "dom.iterable", "esnext"],
    "strict": true,
    "noEmit": true,
    "esModuleInterop": true,
    "module": "esnext",
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "jsx": "preserve",
    "incremental": true,
    "plugins": [\{ "name": "next" \}],
    "paths": \{ "@/*": ["./*"] \}
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
  "exclude": ["node_modules"]
}

E o arquivo de configuração agora é TypeScript por padrão:

// next.config.ts
import type { NextConfig } from "next";
 
const nextConfig: NextConfig = {
  // Adicione a configuração aqui conforme necessário.
};
 
export default nextConfig;

Mergulho Profundo

Como Funciona

Após a instalação, npm run dev inicia o servidor de desenvolvimento do Next.js. No Next 15, o Turbopack é o bundler de desenvolvimento padrão - você não precisa de uma flag separada.

Variações

Desenvolvimento com Turbopack (explícito): está ativado por padrão, mas você pode forçá-lo em package.json com "dev": "next dev --turbopack".
Porta personalizada: npm run dev -- -p 4000 ou defina PORT=4000 npm run dev.
Diretório personalizado: passe qualquer caminho como nome do projeto, por exemplo, npx create-next-app@latest ./apps/web ....
Sem git init: adicione --disable-git ao comando.
Configuração manual: mkdir my-app && cd my-app && npm init -y && npm install next@latest react@latest react-dom@latest && npm install -D typescript @types/react @types/node, em seguida, crie app/layout.tsx e app/page.tsx manualmente; o Next gera next-env.d.ts na primeira execução.
pnpm: pnpm create next-app my-app --typescript --app --no-tailwind --no-eslint --no-src-dir.
yarn: yarn create next-app my-app --typescript --app --no-tailwind --no-eslint --no-src-dir.
bun: bun create next-app my-app --typescript --app --no-tailwind --no-eslint --no-src-dir.

Notas sobre TypeScript

next-env.d.ts é gerado automaticamente a cada desenvolvimento/build. Não o edite; não o exclua. O .gitignore padrão o inclui.

Armadilhas

App Router vs Pages Router. O diretório app/ é o App Router. Se você também criar um diretório pages/, ambos os roteadores serão executados lado a lado e você terá conflitos em rotas compartilhadas. Exclua pages/ a menos que você esteja migrando intencionalmente.
Posicionamento de src/ vs app/ raiz. Com --no-src-dir, o App Router fica em ./app. Se algum tutorial disser para colocar arquivos em ./src/app, esse é o layout com --src-dir; misturar os dois quebra silenciosamente as importações.
Os padrões mudam entre as versões do Next.js. No Next 15, os prompts padrão incluem Turbopack e AGENTS.md - flags que não existiam no Next 13 ou 14. Sempre fixe em @latest ou uma versão exata em sua documentação.
Node.js 18.18 ou mais recente é necessário. O Next 15 se recusa a iniciar em Node 18.17 e anteriores. Execute node -v antes de npm run dev; use nvm para alternar se você estiver em um LTS mais antigo.
Porta 3000 já em uso. npm run dev falhará com EADDRINUSE se outro processo estiver usando a porta 3000. Mate o processo (lsof -iTCP:3000 -sTCP:LISTEN) ou execute com -p 3001.
fetch não é cacheado por padrão no Next 15. Se você espera o comportamento antigo de "fetch é cacheado para sempre" do Next 13/14, você deve optar explicitamente com next: \{ revalidate: N \} ou cache: "force-cache".
next.config.ts requer um runtime Node ciente de TypeScript. Funciona diretamente no Next 15, mas algumas ferramentas mais antigas que chamam next build de um script Node simples podem reclamar - volte para next.config.mjs se encontrar isso.

Alternativas

Ferramenta	Quando usar	Contrapartida vs Next.js 15
Vite + React Router	SPAs, dashboards protegidos por autenticação, sem necessidades de SEO	Sem Server Components, sem SSR integrado, sem roteamento baseado em sistema de arquivos
Remix	Aplicativos com muitos formulários, roteamento aninhado, aprimoramento progressivo	Ecossistema menor; modelo de carregamento de dados diferente (`loader`/`action`)
Astro	Sites de conteúdo, páginas de marketing, blogs	React é um convidado; sem história completa de Server Components do React 19
Next.js Pages Router	Bases de código legadas, bibliotecas ainda vinculadas a `getServerSideProps`	Sendo substituído pelo App Router; sem Server Components

FAQs

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

Qual flag seleciona o App Router?

--app. Sem ela, create-next-app pode usar o App Router por padrão no Next 15, mas a flag torna a escolha explícita e não interativa.

Como desativo o Tailwind e o ESLint ao mesmo tempo?

Passe --no-tailwind --no-eslint para create-next-app. Ambas as flags são necessárias porque cada uma é ativada por padrão no Next 15.

O que `--import-alias "@/*"` realmente configura?

Ele escreve uma entrada paths em tsconfig.json para que @/lib/x resolva para ./lib/x (ou ./src/lib/x se você usou --src-dir).

Por que meu `app/page.tsx` é um Server Component por padrão?

Tudo em app/ é um Server Component, a menos que o arquivo comece com "use client". É por isso que você pode usar await dentro do corpo do componente.

Preciso de uma flag `--turbopack` separada no Next 15?

Não. Turbopack é o bundler de desenvolvimento padrão. A flag só é útil se você quiser fixá-la em package.json para clareza.

Qual é a versão mínima do Node.js?

18.18.0. Qualquer versão anterior falha na inicialização. Armadilha: várias imagens de CI populares ainda enviam 18.17 por padrão.

O que acontece se a porta 3000 estiver ocupada?

É seguro editar `next-env.d.ts`?

Não. Ele é regenerado a cada build e quaisquer edições serão perdidas. Mantenha-o commitado e intocado.

Como habilito o TypeScript estrito?

Por que minha chamada `fetch` atinge a rede a cada requisição?

O Next 15 mudou o padrão: fetch não é mais cacheado, a menos que você opte por isso. Adicione next: \{ revalidate: 60 \} ou cache: "force-cache" às opções do fetch.

Posso tipar `next.config.ts` com IntelliSense completo?

Qual é a diferença entre `app/` e `pages/`?

app/ é o App Router (React 19, Server Components, layouts, streaming). pages/ é o legado Pages Router. Você pode executar ambos, mas inicie novos projetos apenas em app/.

Configuração Básica do Next.js

Buscar na documentação

Configuração Básica do Next.js