Next.js com TypeScript: boas praticas que evitam dor de cabeca

Se voce chegou ate aqui, provavelmente ja tentou usar TypeScript em um projeto Next.js e percebeu que, sozinho, ele nao faz milagres. O compilador ate reclama quando algo esta errado, mas se a estrutura do projeto estiver bagunçada, o resultado e um codigo rigido, chato de manter e ainda propenso a bugs. A boa noticia: existem praticas simples que mudam completamente a experiencia de desenvolver em Next.js com TypeScript.

Neste guia, voce vai encontrar um conjunto de boas praticas reunidas a partir da documentacao oficial do Next.js, do TypeScript e de anos de uso em producao. A ideia nao e virar um guru, e sim evitar os erros mais comuns e ganhar produtividade real. Vamos falar de tipagem, organizacao de pastas, componentizacao, servidor e cliente, performance e deploy.

Este conteudo tem carater informativo. Decisoes tecnicas devem ser tomadas com profissional especializado, especialmente em projetos de producao com dados sensiveis.

O que e Next.js e por que usar TypeScript

Next.js e um framework React criado pela Vercel que facilita a construcao de aplicacoes web com renderizacao no servidor, rotas baseadas em arquivos, otimizacao de imagens, suporte a API Routes e uma serie de recursos prontos para uso. Em outras palavras, e um "atalho" para criar sites e sistemas que precisam de performance e SEO sem montar tudo do zero.

TypeScript, por sua vez, e uma linguagem baseada em JavaScript que adiciona tipagem estatica. Em vez de descobrir erros apenas quando o usuario clica em um botao, voce recebe avisos enquanto escreve o codigo. Para projetos Next.js, isso significa:

• Menos bugs em producao.
• especialmente em formularios.
• respostas de API e manipulacao de dados.
• Refatoracao mais segura.
• porque o editor sabe quais funcoes e componentes recebem quais dados.
• Documentacao implicita.
• ja que os tipos descrevem o que cada parte do codigo espera.
• Melhor experiencia em equipe.
• pois novos desenvolvedores entendem contratos de funcoes lendo os tipos.

A combinacao funciona muito bem porque o Next.js ja nasceu preparado para TypeScript, com tipos proprios para paginas, rotas dinamicas, parametros de URL e respostas de API.

Estrutura de pastas recomendada para projetos Next.js com TypeScript

Antes de falar de tipos em si, vale resolver a base: como organizar o projeto. Uma estrutura confusa e a porta de entrada para inconsistencias. O Next.js usa o diretorio app/ (a partir da versao 13) ou pages/, e cada um pede uma organizacao especifica.

Estrutura base com App Router

A estrutura recomendada pelo time do Next.js para projetos novos em 2026 segue o padrao:

• src/app/ para paginas.
• layouts e rotas, src/components/ para componentes reutilizaveis, src/lib/ para utilitarios e integracoes externas, src/types/ para tipos globais compartilhados, src/hooks/ para hooks customizados, public/ para arquivos estaticos, next.config.ts para configuracoes do Next.

Estrutura base com Pages Router

Para quem ainda usa pages/, a organizacao segue um caminho semelhante:, src/pages/ para paginas e rotas de API, src/components/ para componentes, src/lib/ para utilitarios, src/types/ para tipos globais, src/hooks/ para hooks customizados, public/ para arquivos estaticos

Comparativo rapido entre App Router e Pages Router

Para novos projetos em 2026, a recomendacao oficial da Vercel e usar o App Router, mas o Pages Router ainda e totalmente suportado e comum em sistemas ja em producao.

Boas praticas de TypeScript com Next.js

Agora vamos ao que interessa: como escrever TypeScript que ajuda, em vez de atrapalhar. As praticas abaixo cobrem os pontos mais sensiveis em projetos Next.js.

Ative as configuracoes estritas no tsconfig.json

O Next.js ja cria um tsconfig.json inicial, mas em muitos casos ele vem mais permissivo do que o ideal. Para uma tipagem consistente, ative no minimo:, "strict": true, "noUncheckedIndexedAccess": true, "forceConsistentCasingInFileNames": true

Essas tres opcoes fazem o TypeScript reclamar quando voce acessa arrays ou objetos sem checar se o valor existe, ou quando ha inconsistencia entre maiusculas e minusculas nos imports. Em sistemas grandes, isso evita horas de debug por causa de um data que vinha undefined em uma condicao especifica.

Defina tipos explicitos para props de componentes

A maior dor de cabeca em projetos React com TypeScript vem de props mal definidas. A boa pratica e declarar o tipo das props sempre que o componente tiver mais de uma propriedade.

type ButtonProps = {
  label: string
  onClick: () => void
  variant?: 'primary' | 'secondary'
  disabled?: boolean
}

export function Button({ label, onClick, variant = 'primary', disabled }: ButtonProps) {
  return (
    <button onClick={onClick} disabled={disabled} className={`btn btn-${variant}`}>
      {label}
    </button>
  )
}

Quando o componente precisa receber todas as props de um elemento HTML, use ComponentProps para evitar redigitar tudo.

import type { ComponentProps } from 'react'

type ButtonProps = ComponentProps<'button'> & {
  variant?: 'primary' | 'secondary'
}

Evite o tipo any

any desliga o TypeScript e, na pratica, remove a principal vantagem de usar a linguagem. Quando voce nao sabe o tipo de algo, use unknown e faca a checagem antes de usar. Quando a funcao ou biblioteca realmente nao oferece tipo decente, prefira criar uma interface propria que descreva o que voce precisa, em vez de aceitar qualquer coisa.

// Ruim
function salvarDados(dados: any) { /* ... */ }

// Melhor
function salvarDados(dados: unknown) {
  if (typeof dados === 'object' && dados !== null && 'name' in dados) {
    // ...
  }
}

Use tipos para parametros de rota

No App Router, voce recebe parametros como params e searchParams. Tipa-los ajuda a evitar erros em rotas dinamicas como [id]/page.tsx.

type PageProps = {
  params: Promise<{ id: string }>
  searchParams: Promise<{ [key: string]: string | string[] | undefined }>
}

export default async function ProdutoPage({ params, searchParams }: PageProps) {
  const { id } = await params
  const query = await searchParams
  // ...
}

No Pages Router, o equivalente e usar GetServerSideProps, GetStaticProps ou GetStaticPaths, todos ja tipados pelo proprio Next.

Tipos para dados de API

Quando voce consome uma API, e comum receber dados no formato unknown ou any. O ideal e criar tipos explicitos que representem o contrato com o servidor.

type Produto = {
  id: string
  nome: string
  preco: number
  disponivel: boolean
}

async function listarProdutos(): Promise<Produto[]> {
  const response = await fetch('https://api.exemplo.com/produtos')
  if (!response.ok) throw new Error('Falha ao buscar produtos')
  const data = await response.json() as Produto[]
  return data
}

Se voce usa o React Query, TanStack Query ou SWR, mantenha os tipos alinhados com a resposta da API para que o autocomplete no editor funcione bem.

Configure caminhos de importacao com path aliases

Em vez de ../../../components/Button, prefira @/components/Button. Isso evita caminhos longos e fica mais facil de manter em projetos grandes.

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

O Next.js ja configura isso por padrao quando voce cria o projeto, mas e comum ver desenvolvedores ignorando o recurso e voltando a caminhos relativos.

Componentizacao e separacao de responsabilidades

Um erro frequente em projetos Next.js e misturar logica de negocio com interface. A pratica recomendada e separar em camadas:

• Componentes de apresentacao: recebem dados via props e renderizam. Sem fetch.
• sem regra de negocio. Componentes com container: fazem fetch e passam dados adiante. Hooks customizados: isolam logica reutilizavel.
• como autenticacao.
• lista de produtos ou calculos especificos. Libs: concentram integracoes externas.
• como cliente HTTP.
• conexao com banco ou servicos de pagamento.

Quando voce segue essa divisao, fica muito mais facil testar, trocar de biblioteca ou refatorar. Um sistema que mistura tudo em um arquivo so tende a virar um "monstro" em poucos meses.

Server Components versus Client Components

No App Router, voce precisa decidir quando um componente sera renderizado no servidor e quando sera renderizado no navegador. A regra geral e simples:

• Use Server Components por padrao. Eles sao renderizados no servidor.
• enviam menos JavaScript para o cliente e funcionam bem com SEO.
• Marque um componente com 'use client' apenas quando ele usa estado.
• eventos do navegador ou bibliotecas que dependem do cliente.

'use client'

import { useState } from 'react'

export function Contador() {
  const [valor, setValor] = useState(0)
  return <button onClick={() => setValor(valor + 1)}>{valor}</button>
}

Muitos iniciantes marcam tudo como 'use client' por medo de erro de hidratacao. Isso quebra os ganhos de performance do App Router. Use o recurso com criterio.

Performance: pontos de atenção

Boas praticas em Next.js com TypeScript tambem envolvem performance. Alguns pontos de atencao:

• Use o componente Image do proprio Next.
• que otimiza imagens automaticamente.
• Use next/font para fontes com carregamento otimizado e sem layout shift.
• Use next/dynamic para componentes pesados que nao precisam estar no carregamento inicial.
• Evite fetch em loop dentro de Server Components. Prefira uma chamada unica no servidor.
• Configure cache de rotas com cuidado.
• especialmente em paginas que mudam com frequencia.
• Em formularios.
• prefira Server Actions em vez de criar uma API so para isso.

Testes e qualidade de codigo

TypeScript sozinho nao substitui testes. Para um projeto profissional, considere:

• Unitarios: Vitest ou Jest para funcoes puras e componentes isolados. Integracao: Testing Library para simular interacoes do usuario. End-to-end: Playwright ou Cypress para fluxos completos. Linting: ESLint com a configuracao recomendada do Next.
• incluindo @typescript-eslint. Formatacao: Prettier para manter o codigo consistente.

Manter essa stack ajuda a evitar regressoes em projetos que recebem contribuicoes de varias pessoas.

Acessibilidade, SEO e LGPD em projetos Next.js

Em 2026, nao da para falar de boas praticas sem tocar em acessibilidade, SEO e privacidade. Pontos importantes:

• Use HTML semantico.
• com header, main, nav, footer e article no lugar certo.
• Configure metadata export em cada pagina para controlar titulo.
• descricao e Open Graph.
• Adicione alt em imagens e rotule campos de formulario com label.
• Em formularios.
• use validacao tanto no cliente quanto no servidor.
• Em relacao a LGPD.
• evite exibir dados pessoais desnecessarios.
• registre consentimento quando aplicavel e revise logs.

Essas praticas nao sao diferenciais, sao requisitos minimos para qualquer projeto brasileiro que recebe publico amplo.

Quando o time ainda usa Pages Router

Se voce herdou um projeto em Pages Router, nao precisa migrar tudo de uma vez. O Next.js permite usar as duas abordagens no mesmo projeto em casos especificos, mas o mais comum e manter consistencia ate ter tempo para migrar com calma. Para esse cenario:

• Mantenha os arquivos de tipos globais em src/types/.
• Centralize funcoes de fetch em src/lib/ para reuso.
• Continue tipando props e retornos de getServerSideProps e getStaticProps.
• Considere migrar paginas criticas para App Router aos poucos.

O importante e que a base esteja limpa, porque migracao se torna um processo quase mecanico quando o codigo ja segue boas praticas.

Armadilhas comuns e como evitar

Mesmo com todas as dicas acima, e facil cair em armadilhas classicas em Next.js com TypeScript. Listei algumas que aparecem em praticamente todo projeto:

• Esquecer de tipar params em rotas dinamicas.
• especialmente em projetos que migram para Next.js 15.
• onde params virou Promise.
• Usar useState para dados que poderiam vir do servidor.
• Marcar tudo como 'use client'.
• perdendo performance.
• Misturar fetch do navegador com fetch do servidor sem padronizar.
• Duplicar tipos entre back-end e front-end em vez de gerar a partir do mesmo contrato.
• Confiar em bibliotecas sem tipos e aceitar any por preguica.
• Esquecer key em listas.
• gerando warnings no React.
• Importar bibliotecas inteiras em vez de modulos especificos.

Resolver essas armadilhas e, muitas vezes, o que separa um projeto amador de um projeto profissional.

Perguntas Frequentes (FAQ)

Next.js funciona bem com TypeScript em 2026?

Sim. O Next.js ja nasceu preparado para TypeScript e oferece tipos oficiais para paginas, rotas, API Routes e configuracoes. Em 2026, a experiencia de uso e uma das mais maduras no ecossistema React.

Devo usar App Router ou Pages Router em projetos novos?

Para projetos novos em 2026, a recomendacao e usar App Router, que e o modelo oficial e tem maior investimento do time do Next. O Pages Router ainda e suportado, mas recebe apenas correcoes e melhorias pontuais.

Como evitar erros de hidratacao em Next.js?

Garanta que o HTML renderizado no servidor seja identico ao renderizado no cliente. Evite usar Date.now(), Math.random() ou window durante a renderizacao inicial. Quando precisar de dados do navegador, faca isso em useEffect ou em componentes marcados como 'use client'.

Qual a diferenca entre interface e type em TypeScript?

Funcionalmente, ambos descrevem a forma de um objeto. A diferenca pratica e que interface pode ser estendida via extends e sofre merge de declaracao, enquanto type e mais flexivel para unioes, intersecoes e tipos utilitarios. Em projetos Next.js, ambos funcionam bem e a escolha costuma ser uma questao de estilo do time.

Vale a pena usar Server Actions em formularios?

Em muitos casos, sim. Server Actions evitam a necessidade de criar uma rota de API especifica para cada formulario e simplificam o codigo. Porem, para sistemas com auditoria, logs ou filas, pode ser melhor manter uma rota de API tradicional para ter mais controle.

Conclusao

Adotar boas praticas em Next.js com TypeScript nao e sobre escrever o codigo mais rebuscado, e sobre evitar dor de cabeca. Quando o projeto tem tipagem consistente, estrutura clara, separacao entre servidor e cliente e atencao a performance, o resultado aparece em menos bugs, deploys mais tranquilos e um time mais produtivo.

Se voce esta comecando um projeto novo, comece pela estrutura de pastas e pelo tsconfig.json. Se voce ja tem um projeto em producao, escolha um modulo critico e refatore com calma. O ganho composto de boas praticas aparece em pocos meses.

Se voce precisa de ajuda para colocar isso em pratica, a Baita Site tem uma equipe especializada em sites, e-commerce, sistemas e inteligencia artificial, com dominio total de WordPress. Fale com a gente e veja como podemos acelerar o seu projeto.

Referencias consultadas, Next.js Docs. "TypeScript&quot. Disponivel em

https://nextjs.org/docs/app/api-reference/config/typescript, Next.js Docs. "Project Structure&quot. Disponivel em: https://nextjs.org/docs/app/getting-started/project-structure, TypeScript Docs. "TSConfig Reference&quot. Disponivel em: https://www.typescriptlang.org/tsconfig/, React Docs. "Server Components&quot. Disponivel em: https://react.dev/reference/rsc/server-components, Vercel Blog. "How to Use TypeScript with Next.js&quot. Disponivel em: https://vercel.com/guides/typescript-with-nextjs