Como migrar de pages para app router no Next.js com Chakra UI sem perder a sanidade
Chegou a hora de evoluir: leve seu projeto Next.js das velhas pages para o app router, aprendendo cada detalhe sem medo, de rotas a temas escuros e fontes modernas, do login ao loading, com zero enrolação.
Por que isso é importante
A evolução do Next.js obriga todos que têm projetos antigos a migrar da estrutura de pages para app router. Ignorar isso significa perder performance, funções modernas e até suporte futuro. Saber migrar rápido e sem perdas é o diferencial que separa quem segue crescendo no mercado de quem fica para trás.
Migração: a coragem de sair do velho
Se seu projeto ainda roda em Next.js 12 e usa a clássica pasta pages, a hora de mudar é agora. O novo Next.js (v15+) exige app router para recursos de servidor otimizados, loading independente e meta SEO potente nativo. Migrar parece assustador, mas é só seguir a trilha certa: renomeie pages para legacy-pages, crie a pasta app e vá transportando, adaptando rotas e layouts, sem colidir as estruturas antigas.
⚠️Atenção
Não apague sua pasta pages de imediato. Renomeie para legacy-pages para garantir rollback rápido caso algo quebre.
Roteamento: o segredo das rotas inteligentes
O novo sistema de rotas do Next.js é revolucionário: cada pasta dentro de app é uma rota, e arquivos como layout.tsx, loading.tsx e page.tsx trazem controle total do fluxo. Comece pela rota raiz. Em vez de _app.tsx e _document.tsx, agora tudo é distribuído em layouts e providers.
ℹ️Dica técnica
Use layout.tsx para wrappers globais (temas, fontes, contextos) e loading.tsx para controladores de estado de carregamento específicos por rota.
Layouts: nunca mais reescreva boilerplate
Com o layout.tsx global, todas as páginas têm cabeçalho, providers de contexto e tema automaticamente. Adicione o ChakraProvider, garanta que fontes e cores do sistema fiquem num só lugar e acabe com repetição. Torne League Spartan ou a fonte da sua escolha padrão do projeto inteiro sem gambiarra.
❌Evite Erros
Não tente importar pageProps ou Component como antes. Eles não existem na nova arquitetura do App Router.
Providers: contexto, temas e a dor do Chakra UI
Centralize todos os Providers (Chakra, Theme, Auth etc) em providers.tsx dentro da pasta app. Copie o que funcionava na arquitetura antiga e adapte para o mundo SSR do Next.js 15+. Use use client no topo do arquivo se o contexto precisar do lado do cliente.
⚠️Atenção Extra
O ChakraProvider precisa ser importado e funcionar sem conflitos. Se der dor de cabeça, quebre em pequenos providers e adicione-os um a um.
Fontes: fugindo do Arial seco, criando personalidade
Nada de fonte padrão sem graça. Agora é hora de trazer identidade. Instale fontes modernas – como League Spartan, Inter ou Pops – usando o sistema do Next.js (next/font) e as integre direto no layout global. Chega de mexer na fonte toda rota!
✅Boas Práticas
Exporte a fonte customizada como variável e use-a globalmente no className do html ou do body.
Temas: definindo as cores do seu produto
Aproveite para abandonar o roxo pronto de outros projetos. Crie seu próprio tema: escolha primary, secondary, tertiary e uma escala de cinza (grayscale). Deixe o Chakra UI refletir sua identidade visual e torne o dark mode real.
⚠️Atenção
Não mantenha variáveis de cores que não são usadas – limpe os temas antigos para evitar confusões futuras e bugs visuais.
Loading aprimorado: carregamento sob controle granular
O loading.tsx está em cada rota, incluindo global. Ele permite spinners sob medida, backgrounds personalizados e controle total sobre UX durante a renderização SSR e CSR.
ℹ️Alerta Técnico
O loading.tsx global cobre todas as rotas onde não há um loading específico. Ganhe experiência customizando o loading por página para garantir consistência e rapidez percebida.
Meta SEO: o segredo da nova meta optimization
Adeus document.tsx, adeus tags soltas! O Next.js 15+ gerencia metadata por arquivo, com tipagem, SEO otimizado e flexibilidade para titles dinâmicos, descriptions e tags sociais.
✅SEO na veia
Use o objeto Metadata em cada page.tsx para definir títulos, descrição, keywords e openGraph – tudo pronto para ranquear alto no Google.
Funções utilitárias: cookies sem dor e sem libs a mais
A manipulação de cookies mudou: agora a função cookies do Next.js lê cookies no SSR. Crie utilitários em utils como parseCookies e getCookies para acessar cookies do servidor sem usar o oldschool nookies.
ℹ️Dica prática
Use try/catch nos hooks de leitura dos cookies para ignorar erros de ambiente ou SSR.
Login page: comece sempre pelo fluxo simples
Evite complicar. Migre antes o login page para garantir rota principal e autenticação. O segredo do novo Next é: código componentizável roda em qualquer arquitetura, então use seus antigos screens prontos, importando direto no novo page.tsx.
⚠️Evite retrabalho
Componente bem escrito não quebra ao migrar: só ajuste sintaxe de rota e SSR/CSR.
Redirect: controle absoluto de navegação
Saia de next/router, entre em next/navigation. Toda navegação, inclusive redirect após login, logout, precisa ser adaptada para a nova abordagem – e atenção: ela é server e client side ao mesmo tempo.
❌Evite bugs de navegação
Não confunda uso do redirect no servidor com hooks de navegação do client. Consulte sempre a doc antes de usar múltiplos redirects no mesmo fluxo.
SSR/CSR: quando usar server e quando usar client
Hooks como useContext e cookies só rodam no client. Toda função que precisa renderizar algo no lado do servidor não pode depender de estado global do client. Equilibre e use use client sempre que necessário.
⚠️Atenção arquitetura
Importou provider? Lembre-se de colocar use client ANTES de qualquer chamada – senão seu contexto quebra e nada funciona.
Container responsivo: componentização é vida longa!
Padronize containers (como Container sm=320) em um único local. Atualize todos os componentes para usar essas versões consistentes. Sucesso = menos retrabalho futuro e responsividade automática.
✅Padrão é tudo
Quanto mais componentizado seu projeto, mais rápido e seguro é migrar entre frameworks e versões.
Conclusão: menos medo, mais adaptação
Migrar do pages para o app router do Next.js é uma maratona, mas sem segredo. Revise cada etapa: rotas, layouts, providers, fontes, tema, login, loading e cookies. Faça com calma, teste em partes e nunca apague a estrutura antiga antes dos testes finais.
✅Novidade ao seu alcance
Quer aprender migrações avançadas ao vivo? Explore também o canal de vídeo para devs hands-on com dicas contínuas de Next.js, React e muito mais.