use-dom

Visão geral da skill use-dom

O que a skill use-dom ajuda você a fazer

A use-dom skill mostra como usar componentes DOM do Expo para que código React web rode dentro de um app Expo no nativo via webview, continuando a renderizar normalmente na web. Na prática, o objetivo não é apenas “aprender um recurso” de forma isolada — é decidir se um componente, biblioteca ou layout pensado primeiro para web pode entrar no seu app sem exigir uma reescrita completa em React Native.

Para quem a skill use-dom é indicada

Esta use-dom skill é mais indicada para desenvolvedores frontend que:

• já têm componentes React web que querem reaproveitar no Expo
• precisam de bibliotecas exclusivas do navegador, como gráficos, editores, syntax highlighting, embeds ou interfaces baseadas em iframe
• estão migrando um app web para nativo de forma incremental
• precisam de recursos de DOM e CSS que o React Native não expõe diretamente

Se a sua interface é simples e sensível a performance, normalmente essa não é a melhor escolha.

O que diferencia use-dom de um prompt genérico sobre Expo

Um prompt genérico pode sugerir “é só usar um WebView” ou “porte para React Native”. O guia de use-dom é mais específico: ele se concentra no modelo de componentes DOM do Expo, na diretiva de arquivo 'use dom'; e nos limites de encaixe que mais importam antes da instalação — principalmente tradeoffs de performance, posicionamento de rota não suportado e quando o código web pode ser reaproveitado praticamente sem alterações.

O que os usuários normalmente querem saber primeiro

A maioria das pessoas avaliando use-dom quer resposta para quatro perguntas:

1. Posso manter meu componente web atual quase sem mudanças?
2. Minha biblioteca alvo vai funcionar se depender do DOM?
3. Quais são os tradeoffs de performance e UX no nativo?
4. Em que momento vale parar e construir um componente nativo em vez disso?

A skill é mais forte quando essas perguntas são o seu gargalo, e não quando você precisa de integração nativa avançada.

Cenários de boa e má aderência

Boas opções de use-dom for Frontend Development incluem:

• recharts, chart.js, editores rich text, syntax highlighters
• componentes com muito HTML/CSS
• embeds baseados em iframe
• código com canvas ou WebGL que espera APIs de navegador

Maus encaixes incluem:

• UI básica de app que o React Native já renderiza diretamente
• telas em que a performance nativa é crítica
• componentes que precisam de integração profunda com APIs de plataforma
• arquivos de rota _layout, que não devem ser componentes DOM

Como usar a skill use-dom

Instale a skill use-dom

Instale a partir do repositório de skills do Expo:

npx skills add https://github.com/expo/skills --skill use-dom

Isso dá ao seu agente ou fluxo de trabalho uma referência reutilizável de use-dom install e implementação, em vez de depender de um prompt avulso.

Leia este arquivo primeiro

Comece por:

• SKILL.md

Nesta skill, praticamente toda a orientação útil está concentrada ali. Você não precisa vasculhar uma árvore grande de arquivos de suporte antes de decidir se vale adotar.

Entenda o mecanismo central

O modelo de use-dom usage é simples, mas importante: crie um arquivo de componente com a diretiva 'use dom'; no topo. Isso marca o componente como baseado em DOM. Na web, ele renderiza normalmente. No nativo, roda em um contexto de webview.

Isso significa que a principal pergunta não é sobre sintaxe — e sim se o seu componente realmente precisa de APIs de navegador a ponto de justificar a fronteira da webview.

Saiba quais informações a skill precisa de você

Para obter uma saída útil da use-dom skill, informe:

• qual componente ou biblioteca você quer usar
• se ele já funciona em React web
• se depende de APIs DOM, canvas, iframes ou CSS avançado
• onde ele vai ficar no seu app Expo
• se performance é um requisito rígido
• se você precisa de módulos nativos ou integração profunda com o dispositivo

Sem esse contexto, as recomendações tendem a ficar genéricas demais para inspirar confiança.

Transforme um objetivo vago em um prompt forte

Prompt fraco:

• “Help me use use-dom.”

Prompt forte:

• “I have an Expo app and want to reuse a React web chart component built with recharts. It already works on web, uses responsive container sizing, and only needs passed-in data and click callbacks. Show me how to convert it into a DOM component with 'use dom';, explain prop shape expectations, and call out native performance tradeoffs.”

Por que isso funciona:

• nomeia a biblioteca real
• confirma compatibilidade com web
• descreve o fluxo de dados
• explicita as necessidades de interatividade
• pede orientação sobre tradeoffs, não só código

Padrão básico de implementação com use-dom

Um fluxo típico de use-dom guide se parece com isto:

1. Identifique um componente web que já funciona em React web.
2. Crie um arquivo de componente com 'use dom';.
3. Mantenha a renderização dependente de DOM dentro desse componente.
4. Passe props serializáveis e bem definidas a partir do lado Expo.
5. Teste o comportamento tanto na web quanto no nativo, especialmente dimensionamento e interação.

O exemplo da fonte mostra o componente DOM aceitando props comuns mais dom: import("expo/dom").DOMProps, o que é um bom indicativo ao modelar a interface do componente.

Comece por um componente pequeno, não por uma tela inteira

A adoção costuma ser mais tranquila se você mover primeiro um widget isolado:

• um gráfico
• um visualizador de código
• um bloco rich text
• um embed

Não comece envolvendo estrutura ampla do app ou navegação. O repositório destaca explicitamente as restrições de rotas de layout, então um componente pequeno e terminal é a forma mais segura de obter o primeiro ganho.

Decida cedo se o overhead de webview é aceitável

Este é o principal fator na decisão de instalar. use-dom é atraente porque evita uma reescrita, mas o tradeoff é o overhead de webview no nativo. Se o componente aparece em um caminho crítico de performance, renderiza muito conteúdo ou precisa ter sensação totalmente nativa, teste isso antes de se comprometer.

Para UI simples, React Native costuma ser a melhor escolha no longo prazo.

Caminho de leitura do repositório para decidir mais rápido

Para esta skill, siga esta ordem de leitura:

1. seção SKILL.md “What are DOM Components?”
2. seção SKILL.md “When to Use DOM Components”
3. seção SKILL.md “When NOT to Use DOM Components”
4. exemplo em SKILL.md sob “Basic DOM Component”

Essa sequência entrega aderência, restrições e formato de implementação com o mínimo de atrito.

Modelo prático de prompt para use-dom usage

Use um prompt como este ao pedir para um agente aplicar a skill:

Use the use-dom skill to evaluate whether this React web component should become an Expo DOM component.

Component purpose:
- [what it does]

Current library dependencies:
- [libraries]

Why React Native alone is not enough:
- [DOM APIs / CSS / iframe / canvas / WebGL]

Performance sensitivity:
- [low / medium / high]

Route placement:
- [where the component will be used]

What I need from you:
- fit assessment
- implementation outline
- example component file with 'use dom';
- risks and when not to use use-dom

Essa estrutura leva a resultados muito melhores do que pedir “ajuda com migração” de forma abstrata.

Bloqueios comuns de adoção para verificar antes de codar

Antes de implementar, confirme:

• se a biblioteca alvo realmente exige um ambiente DOM/navegador
• se o componente não está sendo pensado para uma rota _layout
• se você não precisa de APIs nativas profundas dentro da parte renderizada por DOM
• se sua equipe aceita a divisão de comportamento entre nativo e web
• se esse componente realmente vale mais a pena reaproveitar do que reescrever

Essas verificações poupam tempo porque atacam exatamente os casos de má aderência destacados pela skill.

FAQ da skill use-dom

use-dom é melhor do que um prompt normal?

Na maioria das vezes, sim — se o seu problema é especificamente “esse componente web consegue rodar no Expo sem reescrita?”. Um prompt comum pode sugerir várias abordagens sem relação direta entre si. A use-dom skill restringe a decisão aos componentes DOM do Expo e traz limites de aderência que reduzem tentativa e erro.

use-dom serve só para migrações?

Não. Migração é um caso de uso importante, mas não o único. use-dom também faz sentido em apps Expo novos quando você precisa de bibliotecas exclusivas do navegador, conteúdo baseado em iframe, comportamento CSS avançado, canvas ou WebGL que o React Native não oferece diretamente.

Quando devo evitar a use-dom skill?

Evite use-dom quando:

• sua UI é simples o suficiente para React Native
• performance é altamente sensível
• você precisa de forte sensação nativa e integração profunda
• o componente pertence a _layout
• uma biblioteca nativa ou cross-platform já resolve o problema de forma limpa

use-dom é amigável para iniciantes?

Moderadamente. A ideia é direta, mas a qualidade da decisão depende de entender os tradeoffs entre web e nativo. Iniciantes conseguem usar bem se começarem com um componente isolado e testarem em dispositivo logo cedo.

use-dom substitui componentes React Native?

Não. É uma válvula de escape pontual, não uma estratégia padrão de UI. O melhor uso de use-dom for Frontend Development é o reaproveitamento seletivo de código dependente de navegador, e não reconstruir um app inteiro dentro de componentes DOM.

Que tipos de bibliotecas têm melhor encaixe?

Os candidatos mais fortes são bibliotecas que assumem um ambiente de navegador, como:

• bibliotecas de gráficos
• bibliotecas de syntax highlighting
• editores rich text
• widgets baseados em iframe/embed
• ferramentas de visualização com uso intenso de DOM

Se a biblioteca já tem uma alternativa React Native sólida, compare essa opção primeiro.

Como melhorar a skill use-dom

Dê ao agente um alvo no nível de componente

A forma mais rápida de melhorar os resultados de use-dom é definir um componente concreto, e não um objetivo vago de migração. Nomeie o arquivo, a biblioteca, as props e a tela onde ele ficará. Isso permite ao agente avaliar se a fronteira DOM é aceitável.

Descreva explicitamente as dependências de navegador

Não diga apenas “isso é um componente web”. Diga o que o torna específico de web:

• window ou document
• renderização em canvas
• embeds com iframe
• exigências de layout em CSS
• pacotes de terceiros que assumem DOM

Isso melhora diretamente a avaliação de aderência, porque a skill foi construída em torno dessas restrições.

Inclua as expectativas de performance logo no início

Muitos resultados fracos com use-dom guide vêm de descobrir tarde demais que o componente está em um caminho crítico de interação. Informe se o componente é:

• above the fold
• rerenderizado com frequência
• carregado de scroll
• interativo
• aceitável dentro de uma webview

Isso muda materialmente a recomendação.

Peça uma decisão de seguir ou não, não só código

Um prompt melhor é:

• “Should I use use-dom here, and why?”

E não apenas:

• “Write the component.”

Isso aumenta o valor da skill porque um de seus principais pontos fortes é justamente definir fronteiras: quando usar componentes DOM e quando não usar.

Peça uma revisão do design das props

O padrão da fonte sugere passar props para um componente DOM de forma limpa. Peça ao agente para revisar:

• quais props devem cruzar a fronteira
• se os dados devem ser simplificados antes
• se os callbacks são mínimos e realmente necessários
• quais valores podem causar complexidade evitável

Entradas claras normalmente importam mais do que uma implementação engenhosa.

Itere depois da primeira resposta

Depois do primeiro rascunho, refine com perguntas objetivas:

• “Reduce this to the minimum DOM-dependent surface.”
• “What part should remain native?”
• “What would make this too slow on native?”
• “Can you rewrite this example so the DOM component only handles the chart body?”

Essas perguntas melhoram mais a qualidade da adoção do que simplesmente pedir uma amostra maior de código.

Fique atento aos modos de falha mais comuns

Erros comuns de use-dom usage incluem:

• usar para UI básica que deveria continuar nativa
• tentar colocar componentes DOM em rotas de layout não suportadas
• subestimar o overhead de webview
• mover partes grandes demais de uma tela para a camada DOM
• pular testes em dispositivo porque a versão web já funciona

Se você perceber algum desses padrões, reduza o escopo antes de continuar.

Aumente a confiança testando primeiro a coisa certa

Seu primeiro teste não deve ser apenas de paridade visual. Verifique:

• correção de renderização no nativo
• dimensionamento e comportamento do container
• comportamento de input e interação
• atualizações de dados
• performance percebida nos dispositivos-alvo

Essa é a forma mais rápida de validar se use-dom install merece continuar na sua stack.