React Navigation 7: escolha stacks, tabs e drawers antes de codificar

ANÁLISE EDITORIAL

A Skill React Navigation, mantida no repositório Callstack Agent Skills, orienta agentes de programação a escolher e configurar stacks, tabs, drawers, headers, sheets e safe areas em projetos React Native. O ganho não está em produzir mais navegação. Está em escolher o navegador certo, respeitar a API já usada pelo aplicativo e evitar correções visuais que criam problemas de estado, layout ou comportamento entre plataformas.

A versão auditada se aplica somente ao React Navigation 7. Ela separa a decisão entre API estática e dinâmica, encaminha cada problema para uma referência específica e registra diferenças relevantes entre iOS, Android e web. O material é útil como guia de implementação e revisão, mas não substitui documentação oficial, teste em dispositivo nem decisão de arquitetura.

O que esta Skill faz de verdade

O arquivo principal funciona como um roteador de conhecimento. Ele manda verificar primeiro se o projeto já usa a API estática, baseada em objetos, ou a API dinâmica, baseada em componentes. Em aplicativo existente, a recomendação é preservar o estilo atual. Em projeto novo, a preferência é pela API estática. A documentação oficial de configuração estática explica como os criadores de navegadores recebem telas, grupos, opções e linking em uma estrutura que favorece inferência de tipos e configuração de links.

Depois dessa escolha, a Skill distribui o trabalho por oito referências. Há material próprio para native stack, bottom tabs, native bottom tabs, material top tabs, drawer, headers, form sheets e safe areas. Cada arquivo mostra exemplos nas duas APIs e aponta os limites da plataforma. Isso reduz a chance de copiar um trecho de stack para um drawer, ou de tratar uma barra de tabs como simples decoração.

A orientação também ajuda a revisar hierarquia. A navegação não é apenas um conjunto de botões. Cada navigator mantém histórico, opções, eventos e estado próprios. A referência oficial sobre navegadores aninhados mostra que ações e opções atuam no navigator que as contém. Uma árvore mal escolhida pode esconder a tab bar no lugar errado, duplicar headers ou tornar o botão voltar incoerente.

Para quem serve

Serve a desenvolvedores React Native, equipes mobile, revisores e agentes que precisam criar ou corrigir fluxos entre telas. É especialmente útil quando o pedido envolve modal, sheet, tabs responsivas, drawer, header customizado, safe area, deep linking ou uma combinação desses recursos.

Também serve para revisão de código. Em vez de aceitar uma navegação porque ela abre uma tela, o agente pode verificar a árvore dos navigators, a API escolhida, a origem dos parâmetros, o comportamento do botão voltar, o espaço ocupado por barras do sistema e a diferença entre mobile e web.

Ela não decide sozinha a arquitetura de informação, os nomes das rotas, o modelo de autenticação nem a política de analytics. Esses elementos dependem do produto. A Skill oferece padrões técnicos para implementar a decisão sem misturar responsabilidades.

Compatibilidade e pré-requisitos

O frontmatter declara compatibilidade com React Navigation 7. A página oficial de primeiros passos informa requisitos mínimos atuais de React Native 0.72, Expo 52 quando o projeto usa Expo Go e TypeScript 5 quando o projeto usa TypeScript. O aplicativo real pode exigir versões mais altas por causa do Expo SDK, do React Native ou de outros pacotes.

• Projeto React Native ou Expo identificado, com versões e gerenciador de pacotes registrados.
• React Navigation 7 confirmado no package.json e no lockfile.
• API estática ou dinâmica identificada no código existente.
• Estrutura de stacks, tabs e drawers inventariada antes de editar.
• Dispositivos ou simuladores disponíveis para iOS e Android, além de navegador quando houver suporte web.
• Branch de teste e comandos de validação conhecidos.

O núcleo usa @react-navigation/native. A documentação lista react-native-screens e react-native-safe-area-context entre as dependências usadas pela maioria dos navigators. Drawer e outras interfaces podem exigir pacotes adicionais, configuração nativa, pods ou ajustes Android. A referência oficial do Drawer deve ser consultada antes de instalar dependências ou mexer no entry point.

Instalação recomendada

O README do repositório documenta a instalação manual com Skills CLI. Para instalar somente esta Skill no projeto:

npx skills@latest add callstackincubator/agent-skills --skill react-navigation

O comando consulta a rede e executa um pacote por npx. Confira o pacote, o repositório, o destino e os arquivos antes de confirmar. A instrução oficial fixada no commit também descreve um bundle para Codex e instalação manual para outros assistentes.

O download local do Bastidores é documental e contém doze arquivos textuais: SKILL.md, oito referências Markdown, agents/openai.yaml, LICENSE e ORIGEM.md. Não inclui React Native, React Navigation, Expo, Node.js, gerenciador de pacotes, dependência, aplicativo, script executável, binário, credencial, segredo, configuração do usuário ou dado.

Configuração antes do primeiro uso

Comece pedindo inventário, não edição. O agente deve localizar o container raiz, os criadores de navigators, as telas, os tipos de parâmetros, o linking e as opções compartilhadas. Registre se a configuração é estática ou dinâmica e quais telas pertencem a cada nível.

Defina o resultado esperado por plataforma. Uma tab pode permanecer na parte inferior no celular e virar sidebar em tela larga. Um native stack pode oferecer apresentação diferente no iOS e no Android. A documentação de bottom tabs diferencia a barra cross platform da opção nativa. A Skill também mantém referência própria para native bottom tabs, que não deve ser tratada como troca automática.

Estabeleça limites para a primeira passada: não instalar pacote, não executar prebuild, não alterar projeto nativo, não apagar rota e não renomear deep link. O primeiro resultado deve ser uma árvore proposta, arquivos afetados, versões, dependências, riscos e plano de teste.

Primeiro uso seguro

Escolha um fluxo pequeno, como uma tela de detalhes aberta a partir de uma lista. Peça ao agente para explicar se a rota pertence ao stack raiz ou a um stack dentro das tabs. Solicite duas alternativas somente quando houver diferença real de comportamento.

Se o aplicativo já usa API dinâmica, mantenha esse padrão no teste. Migrar toda a navegação para API estática é outra tarefa, com outro diff. Para projeto novo, a preferência da Skill pela API estática deve ser confirmada com o suporte necessário a o

Faça a primeira edição em branch descartável. Rode o typecheck, os testes de navegação e o aplicativo em cada plataforma relevante. Verifique entrada, volta, gesto, rotação, teclado, acessibilidade e restauração de estado. Um fluxo que funciona no simulador iOS ainda pode falhar no botão voltar do Android ou no histórico do navegador.

Como o fluxo deve funcionar

1. Inventariar versões, dependências, API, árvore de navigators, telas, tipos e linking.
2. Classificar o problema como stack, tab, drawer, header, sheet ou safe area.
3. Abrir a referência específica da Skill e a documentação oficial correspondente.
4. Propor a menor mudança estrutural capaz de produzir o comportamento desejado.
5. Explicar efeitos em histórico, botão voltar, gesto, header, tab bar e deep link.
6. Aplicar um diff pequeno sem misturar upgrade de dependência ou migração ampla.
7. Executar typecheck, testes e navegação manual nas plataformas declaradas.
8. Registrar evidências, diferenças por plataforma e pendências antes do merge.

Safe area merece uma verificação própria. A documentação recomenda aplicar insets ao conteúdo que precisa deles, em vez de envolver todo o aplicativo indiscriminadamente. Headers, tabs e drawers nativos já tratam parte dos insets, mas componentes customizados ainda precisam ser testados em recortes, barras e modo paisagem.

Resultado esperado

Uma boa entrega inclui a árvore de navegação antes e depois, a justificativa do navigator escolhido, o diff, as dependências tocadas e uma matriz simples por plataforma. O relatório deve dizer quais rotas foram abertas, como o usuário voltou, se o header e a tab bar apareceram no nível correto e como safe areas foram verificadas.

Quando o fluxo usa native stack, compare o comportamento com a referência oficial do Native Stack. Modal, form sheet, animação e gesto têm limites próprios. A conclusão precisa registrar o que foi observado no dispositivo, não apenas o que o código parece fazer.

Não espere uma árvore universal. Aplicativos com autenticação, links externos, web, tablets ou múltiplas janelas têm restrições diferentes. O resultado correto é o menor desenho que preserva estado e comportamento do produto.

Permissões, privacidade e riscos

O pacote local é somente texto. O uso funcional pode ler e modificar código, instalar dependências, alterar arquivos nativos, executar CocoaPods ou Gradle, iniciar simuladores e acessar rede. Nenhum desses efeitos é concedido pela Skill. Cada comando depende das permissões do agente e deve ser aprovado no contexto do projeto.

Parâmetros de rota podem conter identificadores, dados pessoais ou chaves de negócio. Não coloque token, segredo ou objeto sensível em URL, estado persistido, log de analytics ou captura de tela. Revise deep links e analytics como superfícies separadas.

Mudanças de hierarquia podem quebrar links existentes, restauração de estado e rastreamento de telas. Alterações em dependências nativas podem regenerar projetos ou exigir rebuild. Preserve lockfile, revise o diff e mantenha rollback antes de atualizar pacotes.

Erros comuns

Misturar API estática e dinâmica sem motivo. A Skill manda preservar o estilo do aplicativo existente. Mistura deliberada precisa de justificativa e teste.

Esconder a tab bar por estilo em uma tela filha. Muitas vezes a tela deveria estar em um stack acima das tabs. A hierarquia resolve o comportamento com menos exceções.

Adicionar padding fixo para safe area. Recortes, orientação e barras mudam por dispositivo. Use insets e teste o conteúdo customizado.

Ignorar dependências do drawer. Gesture handler, Reanimated e configuração nativa precisam corresponder ao ambiente real.

Tratar rota como armazenamento global. Passe parâmetros mínimos e serializáveis. Estado complexo pertence a uma camada apropriada.

Confiar apenas no typecheck. Tipos não validam gesto, header duplicado, botão voltar, teclado, paisagem ou histórico web.

Atualizar React Navigation durante a correção. Upgrade e mudança de fluxo são alterações distintas. Separe os riscos e as evidências.

Versão, licença e origem verificadas

A curadoria consultou a API oficial do GitHub em 02/09/2026. O repositório callstackincubator/agent-skills registrava 1.633 estrelas, estava público e não arquivado. Estrelas indicam adoção relativa, não provam segurança, qualidade ou compatibilidade.

A Skill não declara um número próprio de release no frontmatter. Ela declara escopo para React Navigation 7. O conteúdo foi fixado no commit 2766baa46ca0fe7c16cc5ab4d0077ccec2e95fb9, de 08/08/2026. O caminho auditado é skills/react-navigation. O SKILL.md fixado encaminha para oito referências locais.

A licença é MIT e permite redistribuição com preservação do aviso. O ZIP local contém doze arquivos textuais permitidos. SHA-256: c885af540f2cb35673e2bd1427857cd0a73d0d4b183febfe9ffa341c519748eb.

Checklist antes de automatizar

• Fixe commit da Skill e versões de React Navigation, React Native, Expo e TypeScript.
• Inventarie API, árvore, rotas, parâmetros, linking, headers, tabs e drawers.
• Comece com análise sem edição e mantenha o primeiro diff pequeno.
• Confirme dependências e passos nativos antes de instalar pacotes.
• Teste entrada, volta, gesto, teclado, rotação e safe areas.
• Valide iOS, Android e web quando cada plataforma fizer parte do produto.
• Proteja parâmetros, deep links, logs e analytics contra dados sensíveis.
• Separe correção de navegação, upgrade de dependência e mudança nativa.

Fontes primárias

• Repositório oficial Callstack Agent Skills.
• SKILL.md de React Navigation fixado no commit.
• Instalação documentada pelo mantenedor.
• Licença MIT do repositório.
• Primeiros passos e requisitos do React Navigation.
• Configuração estática oficial.
• Navegadores aninhados.
• Native Stack Navigator.
• Bottom Tabs Navigator.
• Drawer Navigator.
• Safe areas no React Navigation.
• Solução de problemas oficial.