Integração com Frameworks

A integração base é feita com Web Components. Os wrappers Angular, React e Vue só adaptam essa mesma API para convenções do framework, mantendo os componentes e os estilos no pacote principal.

O pacote @govbr-ds/core fornece tokens e estilos compartilhados. O pacote @govbr-ds/webcomponents fornece os Custom Elements, eventos, métodos, slots e CSS Parts. Use um wrapper quando precisar de tipagem, bindings ou integração específica com o ciclo de vida do framework.

Para mais detalhes sobre como o Stencil faz a integração, consulte a documentação do Stencil sobre integrações.

Note que, em determinadas situações, pode não ser possível fazer essa integração. Isso depende muito da evolução da especificação de Web Components e do suporte dos frameworks.

Web Components vs Frameworks

Critério	Web Components	Wrappers do GovBR-DS
Renderização	Custom Elements e Shadow DOM	Os mesmos elementos, conectados ao framework
Dados	Atributos para valores simples e propriedades para objetos/arrays	Props e bindings do framework, conforme o wrapper
Eventos	Eventos DOM customizados	Callbacks/eventos adaptados ao framework
Formulários	Integração direta com a API do componente	Suporte adicional a formulários do Angular, React ou Vue
SSR	Use o pacote hydrate quando a stack suportar	React SSR e os guias de SSR mostram as configurações necessárias
Portabilidade	Qualquer stack com suporte à Web Platform	Projetos que já adotam Angular, React ou Vue
Dependências	Pacote core e Web Components	Framework, wrapper e mesma versão do core

Estrutura e Filosofia

• A biblioteca em Stencil utiliza a abordagem de Web Components nativos, proporcionando melhor compatibilidade e reutilização em diferentes frameworks.
• O transporte de dados assíncronos pertence à aplicação consumidora. Ela controla fetch, autenticação, debounce, cache e cancelamento; o componente recebe o estado e comunica interações por eventos.

Tipo de Dados

• Stencil usa decorators do TypeScript, oferecendo tipagem mais rigorosa e suporte a IDEs, o que facilita o desenvolvimento e a manutenção.

Ciclo de Vida

• Os métodos do ciclo de vida dos componentes em Stencil diferem dos hooks em Vue. Familiarize-se com os métodos como componentWillLoad, componentDidLoad, e outros.

Recomendações

• Avalie cuidadosamente as necessidades do projeto antes de escolher uma ferramenta.
• Considere a curva de aprendizado e a experiência da equipe de desenvolvimento.
• Experimente diferentes ferramentas para encontrar a mais adequada ao projeto.

Quickstarts oficiais

Use os quickstarts como referência de estrutura de projeto, instalação e bootstrap. Consulte a página central de quickstarts para acessar demonstrações, versões validadas e orientação de escolha.

Stack	Projeto	Comando local
JavaScript	govbr-ds-wbc-quickstart-js	pnpm dev
Angular	govbr-ds-wbc-quickstart-angular	pnpm start
React	govbr-ds-wbc-quickstart-react	pnpm dev
Vue	govbr-ds-wbc-quickstart-vue	pnpm dev

Guias Relacionados

• Navegação dos componentes: como integrar links dos componentes com roteadores de frameworks sem quebrar a navegação nativa.