Next.js: App Shell instantâneo com teste, não com palpite

ANÁLISE EDITORIAL

Uma rota pode abrir sem demora aparente e ainda entregar uma área vazia enquanto espera dados que não eram necessários para desenhar a estrutura da página. A Skill oficial next-cache-components-optimizer, publicada no repositório do Next.js, orienta uma investigação específica: definir qual interface deve aparecer imediatamente, escrever um teste de navegação que primeiro falhe e só então ajustar as fronteiras entre o App Shell e o conteúdo dinâmico. Ela não promete uma quantidade de milissegundos nem aplica uma otimização universal.

O problema que a Skill foi feita para resolver

O guia oficial de otimização do App Shell descreve a parte visual que pode ser entregue sem aguardar uma leitura dinâmica. Cabeçalho, navegação e estrutura útil da rota podem aparecer enquanto uma região dependente de dados atualiza depois. Se a aplicação bloqueia todo esse conjunto por uma consulta que pertence apenas a um painel, a primeira impressão vira uma tela vazia. A Skill ajuda a localizar essa dependência e a limitar a espera à menor região coerente.

O objetivo não é esconder carregamento com uma animação bonita. Uma estrutura sem conteúdo significativo, ou uma versão errada dos dados de outra pessoa, também falha no critério de qualidade. A documentação da Skill pede que a equipe defina o que constitui uma interface útil para aquela rota, com texto ou controles identificáveis, e preserve o comportamento funcional após a mudança.

Para quem serve, e para quem não serve

O público é a equipe que desenvolve uma aplicação Next.js com App Router e já adotou Cache Components. Um desenvolvedor pode usar a Skill para revisar uma rota de catálogo, conta ou painel em que parte da interface deveria ser imediata, mas um acesso a dados suspende a árvore inteira. Um revisor pode usá-la para exigir evidência de teste antes de aceitar uma alteração de cache. O proprietário do produto ainda precisa decidir qual conteúdo é significativo e quais estados de carregamento são aceitáveis.

Ela não é um instalador de Next.js, um monitor de Core Web Vitals nem um benchmark. Também não é a primeira etapa para um projeto que ainda usa outro modelo de renderização. Nesse caso, leia antes o guia oficial de migração para Cache Components. Aplicar trechos da Skill a uma versão ou configuração incompatível produziria testes enganosos, não uma adoção segura.

Compatibilidade verificada e pré-requisitos

O arquivo original declara Next.js 16.3 ou superior com cacheComponents: true. Verifique a versão instalada no projeto, não apenas a versão anunciada no site. A referência de cacheComponents mostra a configuração no arquivo next.config. O projeto também precisa de testes de ponta a ponta capazes de navegar pelas rotas reais. A Skill usa @next/playwright, da mesma linha de release do pacote next, e @playwright/test como executor.

É necessário poder gerar e iniciar uma build de teste semelhante à de produção, controlar as respostas das dependências dinâmicas e examinar o código da rota. Não se exige uma conta de produção no pacote. Se a rota só funciona após autenticação, prepare usuários e dados de teste isolados. Nunca entregue cookies, tokens ou credenciais reais ao agente para tornar o teste mais fácil.

O que há no ZIP do Bastidores

O card de download desta página aponta para um arquivo hospedado pelo Bastidores com a pasta next-cache-components-optimizer. Ela contém SKILL.md, rig-template.md, test-template.md, reference/red-test-robustness.md, LICENSE.md e ORIGEM.md. São apenas documentos Markdown. Não incluímos Next.js, Playwright, scripts executáveis, dependências, chaves nem código da aplicação. O manifesto lista origem, commit e SHA-256 de cada arquivo; confira também o hash do ZIP mostrado no card antes de usar.

O material acompanha a organização da pasta oficial da Skill, fixada em um commit. Essa fotografia ajuda a comparar o conteúdo auditado com a fonte. Uma versão posterior da documentação pode mudar exigências e exemplos. A cópia local não deve ser tratada como atualização automática.

Instalação no cliente de agente

Extraia o ZIP em uma pasta temporária, confirme os hashes de ORIGEM.md e leia o SKILL.md antes de permitir qualquer comando. Copie a pasta inteira para o diretório de Skills reconhecido pelo cliente de agente escolhido. Mantenha rig-template.md, test-template.md e a referência na posição relativa original, pois o arquivo principal aponta para eles. A localização exata do diretório varia entre clientes; confirme-a na documentação do seu agente e verifique qual cópia foi carregada, sobretudo se já houver uma Skill com o mesmo nome.

Como alternativa, o guia oficial mostra npx skills add vercel/next.js --skill next-cache-components-optimizer. Essa instalação busca o repositório oficial e é distinta do download auditado do Bastidores. Não rode ambos automaticamente. Escolha um caminho, revise os arquivos e registre a versão usada na tarefa.

Configuração do teste antes da otimização

A Skill pede uma build que reproduza o comportamento de produção, porque uma execução de desenvolvimento pode resolver uma rota bloqueada de modo diferente. Para permitir a instrumentação do teste, ela orienta habilitar experimental.exposeTestingApiInProductionBuild de forma controlada nessa build. A referência oficial da opção deve ser lida antes de ativá-la. Restrinja-a ao ambiente de teste e não exponha recursos de teste indiscriminadamente no tráfego público.

Instale as dependências de teste segundo o gerenciador do projeto e confira que next e @next/playwright pertencem à mesma linha de versão. Prepare um baseURL para a instância isolada, uma rota-alvo e o modo de bloquear apenas a chamada dinâmica relevante. Os modelos rig-template.md e test-template.md são ponto de partida, não arquivos prontos para colar sem adaptação.

Primeiro uso: um pedido de leitura, não de escrita

Uma primeira instrução segura ao agente seria: “Leia esta Skill e a rota /rota-real. Identifique a interface que deveria aparecer sem esperar dados, mostre qual operação bloqueia o App Shell, proponha um teste de navegação rígido e não altere arquivos ainda”. Substitua o caminho fictício pela rota real. Peça indicação dos componentes, limites de autenticação e fontes de dados examinados. Se o agente não conseguir demonstrar a dependência, a resposta correta é registrar essa incerteza.

O resultado esperado dessa rodada é um plano verificável: elementos do Shell, região dinâmica, navegação inicial e navegação interna, estratégia para segurar a resposta dinâmica e comportamento que deve continuar correto. Não é uma medição de velocidade. Só depois de revisar esse diagnóstico autorize criação de testes e alterações em uma branch de desenvolvimento.

RED: provar a falha antes do conserto

A documentação de navegação instantânea explica o uso do instant() de @next/playwright. O teste deve navegar enquanto uma dependência dinâmica permanece travada e verificar que o Shell significativo aparece. Se o Shell não aparece, a fase RED documenta o problema. A Skill insiste em verificar que o teste falha pelo motivo certo, e não por seletor quebrado, rota incorreta, autenticação ausente ou um servidor que nem iniciou.

Teste tanto a entrada direta na rota quanto uma navegação interna que a aplicação realmente oferece. As duas podem ter caminhos de pré-busca e renderização distintos. Não substitua a asserção por um cronômetro improvisado: instant() é uma verificação lógica sob bloqueio controlado, não uma promessa de tempo de carregamento para todo usuário e toda rede. O documento reference/red-test-robustness.md detalha como evitar falsos resultados.

GREEN: liberar a interface certa

Com a falha reproduzida, examine o menor limite que precisa continuar dinâmico. A solução pode manter elementos estáticos fora de uma espera, envolver a região apropriada em Suspense ou armazenar trabalho reutilizável de maneira compatível com a política de atualização. O guia oficial apresenta esses padrões e seus limites. Escolher cache por conveniência, sem considerar o ciclo de vida dos dados, pode entregar informações desatualizadas ou privadas.

Depois da mudança, rode novamente o mesmo cenário travado. O Shell deve aparecer enquanto a área realmente dependente dos dados espera. Em seguida, solte a resposta e confira que o conteúdo final é correto. A fase GREEN só vale se o comportamento completo sobreviver. Não substitua texto real por caixas genéricas apenas para satisfazer um seletor, nem remova dados importantes da primeira tela sem uma decisão de produto.

Paridade, diferencial e revisão humana

A Skill vai além de obter um teste verde: ela pede paridade entre a rota antiga e a nova quanto a conteúdo, interação e atualização. O teste diferencial compara uma situação que deve continuar falhando com a nova implementação que deve passar, reduzindo a chance de um teste que nunca captou o problema. A revisão humana deve ler o diff do componente e do teste, verificar seletor, bloqueio da dependência, autorização dos dados e efeito de cache. Se o projeto usa dados por usuário, confirme que o Shell não inclui conteúdo particular compartilhado entre sessões.

Registre a build, a versão de Next.js, o comando de teste e quais cenários passaram. Uma aprovação local não equivale a certificação em produção, nem prova melhoria de métricas de campo. Se a equipe monitora desempenho real, mantenha essa medição separada do resultado lógico do teste. A Skill é um método para prevenir regressão de interface imediata, não um selo de desempenho.

Permissões, privacidade e risco de cache

O ZIP não solicita permissões ao sistema, mas o agente que o lê pode ter terminal, escrita no repositório e acesso à rede. Comece com leitura, depois autorize somente a branch e o ambiente de teste necessários. Não permita que o agente altere a configuração de produção ou publique uma build com a API de teste exposta sem revisão. Credenciais, cookies, parâmetros de conta e respostas de API devem ser simulados ou isolados. Revise redirecionamentos de login e fronteiras entre conteúdo público e particular após qualquer mudança de Suspense ou cache.

Se uma sugestão tornar o Shell visível às custas de dados de outra sessão, a alteração está errada, mesmo que instant() passe. Se uma resposta cacheada não respeitar atualização exigida pelo produto, a rota também está errada. A aprovação depende da política de dados e de uma verificação funcional, não apenas da intenção de acelerar a tela.

Erros comuns e como investigar

Se instant() não estiver disponível, confira primeiro as versões instaladas de next e @next/playwright e a configuração da build, em vez de substituir a API por espera arbitrária. Se o teste passa antes da mudança, confirme que a chamada dinâmica realmente ficou travada, que o teste observa um elemento significativo e que o navegador não reutilizou um estado já carregado. Se o RED falha por autenticação ou seletor ausente, conserte o cenário antes de mexer no App Shell.

Se a rota continua vazia após mover um componente, procure outras leituras dinâmicas em layouts e pais da árvore. Se um fallback aparece mas o conteúdo final não chega, investigue o fluxo de dados e a liberação do bloqueio. Se a navegação interna difere da entrada direta, mantenha testes separados. Quando a build local não reproduz o problema, revise as diferenças de configuração antes de concluir que o defeito sumiu. Não altere expectativas para fazer o teste passar sem explicar o comportamento.

Versão, licença e procedência

Esta curadoria fixa o commit d8c1c1b0002db8ccb63b58095f338e8bf423fa99 do repositório vercel/next.js. Na consulta de 11/10/2026, às 18h de São Paulo, ele tinha 143.138 estrelas no GitHub. A contagem pertence ao projeto, não mede instalações desta Skill. O repositório é mantido pela Vercel, e o arquivo de licença MIT permite redistribuição conforme seus termos, preservados integralmente no pacote.

O Bastidores verificou o caminho, os arquivos e a licença, mas não executou o teste em uma aplicação do leitor nem mediu ganho de desempenho. A capa é uma ilustração editorial exclusiva, não captura do Next.js ou evidência de resultado. Antes de aplicar a Skill a uma versão futura, compare o material fixado com a origem oficial e a documentação vigente.

Download próprio e botão do repositório

Use o card de download local para obter o ZIP documental, conferir o SHA-256 e ler ORIGEM.md. O botão separado “Abrir repositório oficial” leva diretamente à pasta da Skill mantida pela Vercel, em nova aba. O primeiro caminho fornece a cópia auditada; o segundo permite comparar a fonte e acompanhar alterações. Nenhum dos dois prepara uma build, concede permissão de produção ou dispensa revisão de código e teste com dados isolados.