vitral

Documentação · Começar · Por que o vitral · Benchmark · English

Junte micro-frontends de qualquer framework numa página só, sem configuração de build no host.

Cada equipe publica o próprio pedaço da página (um remote) com vite build. O host recebe a URL de cada remote e monta tudo no navegador.

Por que usar:

• Zero configuração no host. Sem plugin de build: só configure({ remotes }) com a URL de cada remote.
• Qualquer framework. React, Next, Vue, Nuxt, Angular, Svelte, Solid, Preact, Lit e JS puro na mesma página. Sem combinar versão de React entre equipes.
• Deploy independente. Cada equipe publica quando quiser. O host vê a versão nova sem novo build.
• CSS e erros isolados. O CSS de um remote não muda o resto da página. Um remote fora do ar mostra o próprio erro, e o resto continua funcionando.
• Seguro. O JS só roda se vier de uma origem permitida e se o hash SHA-384 bater.
• Leve e rápido. 3,4 kB de host. Primeira visita 57% mais rápida que o Module Federation e troca de área 4,6 vezes mais rápida que o Next.js Multi-Zones.

npm install vitral

Comparação

Medido no benchmark público (Chromium, rede Slow 4G, mediana de 7 visitas):

• 57% menos tempo na primeira visita que o Module Federation com React compartilhado (1157 ms contra 2673 ms, 1 remote).
• 4,6 vezes mais rápido para trocar de área que o Next.js Multi-Zones (184 ms contra 850 ms), com 63% menos bytes para abrir duas áreas.
• 10 frameworks cobertos por testes de ponta a ponta no CI, com host e remote de frameworks diferentes, em Chromium, Firefox, WebKit e mobile.

O método e as versões usadas estão na página do benchmark.

Começo rápido

Para gerar host e remote prontos: npm create vitral@latest.

1. No remote, exporte o componente e use o plugin:

// src/App.jsx (ou .vue, .svelte, .tsx…)
export default function Carrinho({ userId }) { … }

// vite.config.js
import react from '@vitejs/plugin-react'
import vitral from 'vitral/vite'

export default { plugins: [react(), vitral()] }

O plugin descobre o framework e embrulha o export default com o adaptador certo. A entrada padrão é src/remote.* ou src/App.*.

vite build gera o JS, o CSS e um vitral.json. Publique a pasta dist em qualquer CDN com CORS.

2. No host, registre a URL e use o componente:

import { configure } from 'vitral'
import { Remote } from 'vitral/react'

configure({
  remotes: { carrinho: 'https://cdn.empresa.com/carrinho/vitral.json' },
})

export function App() {
  return (
    <Remote
      name="carrinho"
      props={{ userId: 42 }}
      fallback={<p>Carregando…</p>}
      error={(erro, tentarDeNovo) => <button onClick={tentarDeNovo}>Tentar de novo</button>}
    />
  )
}

Pronto. Mudar props atualiza o remote sem remontar.

Sem build no host, numa página HTML qualquer:

<script type="module" src="https://cdn.jsdelivr.net/npm/vitral/dist/auto.js"></script>
<vitral-remote src="https://cdn.empresa.com/carrinho/vitral.json"></vitral-remote>

Todos os componentes de host aceitam src no lugar de name.

Rodar local

Cada remote roda no próprio vite dev, numa porta. O host aponta para essas portas:

cd carrinho && npm run dev   # vite --port 5174
cd busca && npm run dev      # vite --port 5175
cd loja && npm run dev       # vite --port 3000

// loja/public/remotes.json
{
  "carrinho": "http://localhost:5174/vitral.json",
  "busca": "http://localhost:5175/vitral.json"
}

// loja/src/main.jsx
configure({ remotes: '/remotes.json' })

Editar o remote atualiza o host sem recarregar a página (HMR). Para rodar só um remote local e pegar os outros de homologação, abra o host com ?vitral=carrinho@http://localhost:5174.

Docker e Kubernetes

Cada remote vira uma imagem nginx com o dist. O host lê a lista de remotes de uma variável de ambiente quando o contêiner sobe, então a mesma imagem serve em qualquer ambiente.

# compose.yaml
services:
  loja:                # host: http://localhost:8080
    build: ./loja
    ports: ["8080:80"]
    environment:
      VITRAL_REMOTES: '{"carrinho":"/mf/carrinho/vitral.json","busca":"/mf/busca/vitral.json"}'
  carrinho:            # remote React
    build: ./carrinho
  busca:               # remote Vue
    build: ./busca

O nginx do host repassa /mf/carrinho/ para o contêiner carrinho. Tudo fica na mesma origem: sem CORS e com uma porta só. Parar o contêiner carrinho mostra o erro só no lugar do carrinho.

No Kubernetes, as mesmas imagens funcionam com um Service por remote; o Ingress pode fazer o papel do nginx do host. Se os remotes ficam num CDN, troque VITRAL_REMOTES pelas URLs do CDN.

Exemplo completo, com Dockerfiles e configuração do nginx: examples/docker.

Frameworks

No Next e no Nuxt o componente renderiza o fallback no servidor e monta o remote no cliente.

Host em Vue

<script setup>
import { VitralRemote } from 'vitral/vue'
</script>

<template>
  <VitralRemote name="carrinho" :props="{ userId: 42 }">
    <template #fallback>Carregando…</template>
    <template #error="{ retry }"><button @click="retry">Tentar de novo</button></template>
  </VitralRemote>
</template>

Host em qualquer outro lugar

<vitral-remote> funciona em HTML puro, Angular, Svelte, Astro ou HTML gerado no servidor:

<script type="module">
  import { configure } from 'vitral'
  import { defineVitralElement } from 'vitral/element'

  configure({ remotes: { carrinho: 'https://cdn.empresa.com/carrinho/vitral.json' } })
  defineVitralElement()
</script>

<vitral-remote name="carrinho" props='{"userId": 42}'>
  <p slot="fallback">Carregando…</p>
  <p slot="error">Indisponível</p>
</vitral-remote>

Remote sem framework

import { component, html } from 'vitral'

export default component<{ nome: string }>({
  state: { cliques: 0 },
  render: ({ nome }, state) => html`
    <p>Olá, ${nome}</p>
    <button onclick=${() => state.cliques++}>cliques: ${state.cliques}</button>
  `,
})

O que entra em ${} é escapado. Mudar state ou as props atualiza a tela.

Desenvolvimento

• HMR: com o remote em vite dev, aponte o host para http://localhost:5174/vitral.json. Editar o remote atualiza o host sem recarregar a página.
• Overrides: http://localhost:3000/?vitral=carrinho@http://localhost:5174 troca a URL de um remote sem mexer no host. Só vale em localhost ou com configure({ devOverrides: true }). Para guardar no navegador, use devtools() de vitral/devtools.
• Tipos das props: o build publica vitral.d.ts. No host, npx vitral types gera vitral-env.d.ts, e uma prop errada passa a não compilar.

Comunicação entre remotes

import { events } from 'vitral'

events.emit('carrinho:total', 120)
const parar = events.on('carrinho:total', (total) => console.log(total))
events.last('carrinho:total') // 120

Todos os remotes usam o mesmo barramento. O que um remote assina é cancelado quando ele desmonta.

Para estado comum (usuário, tema, carrinho), use o contexto compartilhado:

import { provide, shared } from 'vitral'

provide('usuario', { id: 42 })                    // host: cria e é o dono
provide('tema', 'claro', { writable: false })     // só o dono altera
shared('tema').subscribe((tema) => console.log(tema))
const nome = useShared('usuario', (u) => u?.nome) // React, Preact, Vue e Solid

Angular usa injectShared, Svelte usa $tema e Lit usa SharedController. Detalhes em Contexto compartilhado.

Para mudar de página de dentro de um remote, use navigate('/pedidos/42'). Todos os roteadores da página recebem a mudança.

CSS e Tailwind

Use Tailwind ou qualquer CSS no remote. O plugin prefixa o CSS para valer só dentro do remote, então o CSS de um remote não muda o host nem os outros remotes.

Para isolar por completo, use Shadow DOM:

<Remote name="carrinho" isolate="shadow" />

Com Shadow DOM, as regras @property e @font-face sobem para o documento, então sombras, rings, gradientes e fontes do Tailwind v4 funcionam. O plugin já faz essa separação no build (campo shadow do vitral.json): a página só adota o CSS pronto. Manifestos antigos continuam funcionando, com a separação feita no navegador.

O remote também pode usar o tema do host:

vitral({ theme: 'host' })                                  // var(--x) usa o valor do host, se existir
configure({ styles: { inherit: ['/assets/base.css'] } })   // CSS base do host dentro do Shadow DOM

Tema com Tailwind v4, dark mode, CSS legado e Tailwind v3 no host: Estilos.

Configuração

configure({
  remotes: '/remotes.json',                    // ou { nome: url }
  allowedOrigins: ['https://cdn.empresa.com'], // padrão: a página e as origens registradas
  timeout: 15000,                              // ms por download
  retries: 1,                                  // novas tentativas em erro de rede
  isolate: 'none',                             // ou 'shadow'
})

Cada remote também aceita um objeto:

configure({
  remotes: {
    carrinho: { url: 'https://cdn.empresa.com/carrinho/vitral.json', integrity: 'sha384-…' },
    menu: { module: () => import('./menu') }, // remote local, sem rede
  },
})

Erros

Todo erro é um RemoteError com code, o nome do remote e docs, o link da página do erro com causas e correção. Um remote que falha mostra o próprio erro e não derruba a página. retry monta só aquele remote de novo.

Performance

Remote com import() também gera dist/split/: o navegador baixa só o que o remote usa ao abrir, e o resto chega no import(), conferido pelo mesmo hash. Hosts antigos continuam usando o arquivo único.

No CDN, sirva vitral.json com Cache-Control: no-cache e o resto (nome com hash) com public, max-age=31536000, immutable.

Assim que o manifesto chega, o JS e o CSS do remote baixam juntos. A montagem espera os dois, para o remote não aparecer sem estilo. configure() abre a conexão com a origem de cada remote (<link rel="preconnect">).

import { preload } from 'vitral'
// Baixa JS e CSS sem montar, por exemplo no hover de um link
link.addEventListener('pointerenter', () => preload('checkout'), { once: true })

Nos componentes de host e no <vitral-remote>:

<!-- monta perto de aparecer na tela; reserve o espaço para a página não pular -->
<vitral-remote name="comentarios" loading="lazy" style="display:block;min-height:400px"></vitral-remote>
<!-- monta com o navegador ocioso, mas já baixa no hover -->
<vitral-remote name="checkout" loading="idle" prefetch="hover"></vitral-remote>
<!-- remote que aparece logo ao abrir a página -->
<vitral-remote name="cabecalho" priority="high"></vitral-remote>

<Remote name="checkout" loading="lazy" prefetch="visible" keepAlive />

Com keep-alive, o remote pode pausar timers e assinaturas:

mount(el, props, ctx) {
  ctx.onDeactivate?.(() => clearInterval(timer))
  ctx.onActivate?.(() => (timer = setInterval(tick, 1000)))
}

Métricas

Cada etapa do carregamento vira um performance.measure com o nome vitral:<remote>:<etapa>. As etapas são manifest, js, css e mount. Elas aparecem na aba Performance do DevTools. Para mandar ao seu RUM:

configure({
  onMetric: ({ name, stage, duration }) => rum.send(`vitral.${stage}`, duration, { remote: name }),
})

O evento vitral-ready (e o ready do componente Vue) traz os tempos em detail.timings, por exemplo { manifest: 12.3, js: 40.1, css: 8, mount: 2.4 }. Um remote local (module) só mede css e mount. Erros dentro do onMetric são ignorados.

Dependências compartilhadas

Para não baixar React ou Vue mais de uma vez, liste-os em dedupe no remote:

vitral({ dedupe: ['react'] })

O remote usa a cópia que já está na página quando a versão serve (padrão: ^ da versão instalada no remote) e baixa a própria só quando não serve. Os componentes de host em React oferecem o React do host sem configuração.

Mais formas de usar

Vários componentes por remote (<Remote name="carrinho/MiniCarrinho" />), módulos sem UI (loadModule('carrinho/api')), deploy novo sem recarregar a página (watchUpdates() e refresh('carrinho')) e app shell por rota (routes() e <vitral-outlet>, em vitral/routes). Veja Exposes, Atualização sem reload e Rotas.

Segurança

• Só importa JS de origens permitidas, mesmo que o vitral.json aponte para outra. O src de um componente de host entra na allowlist; o atributo src do <vitral-remote> não entra quando há allowedOrigins.
• Com integrity, nada roda sem o hash conferir. A lib usa o primeiro caminho que o navegador garante: import map com integrity (Chrome 133+, Safari 18.4+), <link rel="modulepreload" integrity> (Firefox 115+) ou, nos outros, baixa, confere e executa exatamente os bytes conferidos via blob:. Aceita sha256, sha384 e sha512, e vários hashes separados por espaço (vale o mais forte). O CSS do manifesto também é conferido.
• Com CSP, a lib copia o nonce de um <script nonce> da página para o import map. Sem nonce, cai para o modulepreload.
• O hash só protege contra CDN comprometido se vier de outro lugar: fixe integrity no host ou embuta o manifesto ({ url, manifest }).
• Sem eval e sem iframes.
• Shadow DOM isola o CSS, não o JS. Para código de terceiros em que você não confia, use iframe.

Testes do host

import { mockRemote, failingRemote } from 'vitral/testing'

const carrinho = mockRemote('carrinho', (el, props) => (el.textContent = `itens: ${props.itens}`))
// renderize o host
expect(carrinho.lastProps).toEqual({ itens: 2 })

failingRemote('recomendacoes') // testa a tela de erro

Links

• Exemplos: o mesmo remote em 8 frameworks e 9 hosts.
• Como contribuir
• Licença MIT. Feito por Pacheco Codes.