Ir para o conteúdo principal

React – @govbr-ds/webcomponents-react

npm (next)

Este é um wrapper React que encapsula os Web Components GovBR-DS, permitindo seu uso como componentes nativos do React.

Por que usar este wrapper? 🤔​

  • Bindings JSX para props/eventos.
  • Tipagens e autocomplete nos IDEs.
  • Soluciona limitações de passagem de objetos/arrays e captura de eventos em custom elements no React.

Para mais detalhes, consulte a documentação oficial do Stencil e o Custom Elements Everywhere.

Instalação 📦​

npm install @govbr-ds/webcomponents-react
# ou
pnpm add @govbr-ds/webcomponents-react
# ou
yarn add @govbr-ds/webcomponents-react

peerDependencies​

peerDependencies são pacotes que este wrapper não instala automaticamente — o seu projeto precisa tê-los instalados.

Observe que algumas peerDependencies podem ter suas próprias peerDependencies que também precisam ser atendidas. Consulte a documentação de cada pacote para garantir que todas as dependências necessárias estejam presentes.

Por que existem: Garantem que o seu app e o wrapper compartilhem a mesma instância do React e dos Web Components. Versões duplicadas podem causar erros em tempo de execução ou comportamentos inesperados.

O que isso implica: Se as peers não estiverem instaladas ou forem incompatíveis, componentes podem não funcionar.

As peers declaradas neste pacote são:

PacoteVersão compatível
react^18 || ^19
react-dom^18 || ^19
@govbr-ds/webcomponents^2

Nota importante: pnpm e tree-shaking​

Se ao consumir estes pacotes você notar que o bundler não está removendo código não utilizado (tree‑shaking), pode haver uma incompatibilidade com o layout padrão do pnpm.

Solução rápida (opcional, somente se precisar): crie um arquivo .npmrc na raiz do seu projeto com:

node-linker=hoisted

Por que isso ajuda: por padrão, o pnpm organiza as dependências em pastas isoladas com symlinks. Alguns bundlers/otimizadores se baseiam na estrutura de node_modules e no campo sideEffects para decidir o que pode ser eliminado. O layout hoisted aproxima o formato “achatado” (similar ao npm/yarn), facilitando essa análise e, em muitos casos, restaurando o tree‑shaking. Observações:

  • Use apenas se o tree‑shaking realmente não estiver funcionando.
  • Pode aumentar o uso de disco e alterar a resolução de dependências do seu projeto.

Uso 📚​

Fontes e ícones​

Importe os estilos base no CSS global do app:

@import '~@govbr-ds/core/dist/core-tokens.min.css';

Exemplo​

import React from 'react'
import { BrButton } from '@govbr-ds/webcomponents-react'

function App() {
  const handleButtonClick = (ev: CustomEvent) => {
    console.log(ev.detail)
  }

  return (
    <BrButton emphasis="primary" onBrClick={handleButtonClick}>
      Clique aqui
    </BrButton>
  )
}

export default App

Desenvolvimento 👨‍💻​

Estrutura do projeto​

├── 📁 src
│   ├── 📁 stencil-generated
│   └── 📄 index.ts
├── 📁 ssr
│   ├── 📁 stencil-generated
│   └── 📄 index.ts

[!WARNING] Tudo dentro de stencil-generated é sobrescrito ao gerar o build de Web Components.

Scripts/Build​

Gere os Web Components antes de compilar o wrapper:

nx build webcomponents
nx build react

Gerenciar baseline de tamanho:

# Da raiz do monorepo:
pnpm run baseline:update:react    # Atualizar baseline
pnpm run baseline:compare:react   # Comparar com baseline atual

SSR (Server-Side Rendering)​

O wrapper React possui suporte a SSR via o subpath ssr/. Para projetos Next.js ou outros frameworks com SSR:

import { BrButton } from '@govbr-ds/webcomponents-react/ssr'

Componentes importados pelo subpath ssr são renderizados de forma segura no servidor, sem dependência de APIs do navegador durante o build.

Formatos do build 📦​

A tarefa nx build react compila o wrapper e gera a saída em dist/react/. Abaixo estão os artefatos produzidos e quando utilizá-los.

Estrutura do dist/react/​

dist/react/
├── src/
│   ├── index.js          ← Entrada principal (ESM)
│   ├── index.d.ts        ← Tipos TypeScript
│   └── stencil-generated/
│       └── components.js ← Componentes proxy (gerados pelo Stencil)
├── ssr/
│   ├── index.js          ← Entrada SSR (ESM)
│   └── stencil-generated/
│       └── components.server.js ← Componentes SSR (hydrate)
├── package.json
└── README.md

Quando usar cada formato​

ArtefatoQuando usarObservações
src/index.jsAplicações React CSR (client-side)Importação padrão via @govbr-ds/webcomponents-react
ssr/index.jsAplicações React com SSR (Next.js, Remix)Importação via @govbr-ds/webcomponents-react/ssr; usa dist/hydrate do pacote webcomponents
src/index.d.tsAutocomplete e tipagem TypeScriptResolvido automaticamente pelo campo types do package.json

CSR vs SSR​

  • CSR (Client-Side Rendering): importação padrão. Os componentes são registrados e renderizados no browser.
  • SSR (Server-Side Rendering): os componentes são pré-renderizados no servidor usando o script hydrate do pacote @govbr-ds/webcomponents. No cliente, o Stencil faz a hidratação do HTML pré-renderizado.
// CSR — uso padrão
import { BrButton } from '@govbr-ds/webcomponents-react'

// SSR — Next.js / Remix / frameworks com SSR
import { BrButton } from '@govbr-ds/webcomponents-react/ssr'

[!NOTE] O subpath ssr/ depende de @govbr-ds/webcomponents/dist/hydrate. Certifique-se de que o pacote @govbr-ds/webcomponents está instalado.

Documentações Complementares 📖​

Contribuindo 🤝​

Reportar Bugs/Problemas 🐛​

Abra uma issue: gitlab.com/.../issues/new

Commits 📝​

Padrões de branches e commits: gov.br/ds/wiki

Precisa de ajuda? 🆘​

Créditos 🎉​

Desenvolvido pelo SERPRO com a comunidade.