vitral 0.11.2 → 0.11.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -22,7 +22,9 @@
22
22
 
23
23
  Micro-frontends com qualquer framework, sem configurar build no host. React, Next.js, Vue, Nuxt, Angular, Svelte e outros na mesma página.
24
24
 
25
- 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.
25
+ **O que é:** um micro-frontend é um pedaço da página que uma equipe constrói e publica sozinha, como o carrinho, a busca ou a área do cliente. O vitral junta esses pedaços numa página só, mesmo que cada um use um framework diferente.
26
+
27
+ **Como funciona:** cada equipe gera o seu pedaço (um *remote*) com `vite build` e publica num CDN. A página principal (o *host*) recebe a URL de cada remote e monta tudo no navegador.
26
28
 
27
29
  **Por que usar:**
28
30
 
@@ -33,6 +35,8 @@ Cada equipe publica o próprio pedaço da página (um remote) com `vite build`.
33
35
  - **Seguro.** O JS só roda se vier de uma origem permitida e se o hash SHA-384 bater.
34
36
  - **Leve e rápido.** 5,1 kB de host. Abre a página na metade do tempo do Module Federation e troca de área 4,5 vezes mais rápido que o Next.js Multi-Zones.
35
37
 
38
+ **Quando usar:** quando várias equipes mexem no mesmo site e cada uma quer publicar no próprio ritmo. Com uma equipe e um app só, um bundle comum é mais simples.
39
+
36
40
  ```bash
37
41
  npm install vitral
38
42
  ```
@@ -84,7 +88,7 @@ Os 10 frameworks têm testes de ponta a ponta no CI, com host e remote de framew
84
88
 
85
89
  Para gerar host e remote prontos: `npm create vitral@latest`.
86
90
 
87
- **1. No remote**, exporte o componente e use o plugin:
91
+ **1. No remote**, exporte o componente e ligue o plugin:
88
92
 
89
93
  ```jsx
90
94
  // src/App.jsx (ou .vue, .svelte, .tsx…)
@@ -99,42 +103,46 @@ import vitral from 'vitral/vite'
99
103
  export default { plugins: [react(), vitral()] }
100
104
  ```
101
105
 
102
- O plugin descobre o framework e embrulha o `export default` com o adaptador certo. A entrada padrão é `src/remote.*` ou `src/App.*`.
106
+ `vite build` gera o JS, o CSS e um `vitral.json`. Publique a pasta `dist` em qualquer CDN.
103
107
 
104
- `vite build` gera o JS, o CSS e um `vitral.json`. Publique a pasta `dist` em qualquer CDN com CORS.
105
-
106
- **2. No host**, registre a URL e use o componente:
108
+ **2. No host**, registre a URL e mostre o remote:
107
109
 
108
110
  ```jsx
109
111
  import { configure } from 'vitral'
110
112
  import { Remote } from 'vitral/react'
111
113
 
112
- configure({
113
- remotes: { carrinho: 'https://cdn.empresa.com/carrinho/vitral.json' },
114
- })
114
+ configure({ remotes: { carrinho: 'https://cdn.empresa.com/carrinho/vitral.json' } })
115
115
 
116
116
  export function App() {
117
- return (
118
- <Remote
119
- name="carrinho"
120
- props={{ userId: 42 }}
121
- fallback={<p>Carregando…</p>}
122
- error={(erro, tentarDeNovo) => <button onClick={tentarDeNovo}>Tentar de novo</button>}
123
- />
124
- )
117
+ return <Remote name="carrinho" props={{ userId: 42 }} fallback={<p>Carregando…</p>} />
125
118
  }
126
119
  ```
127
120
 
128
121
  Pronto. Mudar `props` atualiza o remote sem remontar.
129
122
 
130
- Sem build no host, numa página HTML qualquer:
123
+ Numa página HTML qualquer, sem build:
131
124
 
132
125
  ```html
133
126
  <script type="module" src="https://cdn.jsdelivr.net/npm/vitral/dist/auto.js"></script>
134
127
  <vitral-remote src="https://cdn.empresa.com/carrinho/vitral.json"></vitral-remote>
135
128
  ```
136
129
 
137
- Todos os componentes de host aceitam `src` no lugar de `name`.
130
+ ## Frameworks
131
+
132
+ | Framework | Remote | Host | Import |
133
+ |---|---|---|---|
134
+ | React 18/19 | `reactRemote(App)` | `<Remote>` | `vitral/react` |
135
+ | Next.js (App e Pages Router) | `reactRemote(App)` | `<Remote>` | `vitral/react` |
136
+ | Vue 3 | `vueRemote(App, { setup })` | `<VitralRemote>` | `vitral/vue` |
137
+ | Nuxt 3/4 | `vueRemote(App, { setup })` | `<VitralRemote>` | `vitral/vue` |
138
+ | Angular 17+ | `angularRemote(Component, { providers })` | `<vitral-remote>` + `provideVitral()` | `vitral/angular` |
139
+ | Svelte 5 | `svelteRemote(App)` | `use:remote` | `vitral/svelte` |
140
+ | Solid | `solidRemote(App)` | `<Remote>` | `vitral/solid` |
141
+ | Preact | `preactRemote(App)` | `<Remote>` | `vitral/preact` |
142
+ | Lit e Web Components | `elementRemote('meu-widget')` | `<vitral-remote>` | `vitral/element` |
143
+ | JS e TypeScript puro | `component({ render })` | `<vitral-remote>` | `vitral` |
144
+
145
+ Host e remote não precisam ser do mesmo framework. Cada um tem uma página com exemplo completo em [Frameworks](https://joaogabriel15.github.io/vitral/frameworks/react).
138
146
 
139
147
  ## Next.js e Nuxt como host
140
148
 
@@ -194,7 +202,7 @@ Nos dois, o servidor renderiza o `fallback` e o remote monta no navegador. Não
194
202
 
195
203
  ## Multi-Zones ou vitral
196
204
 
197
- O mesmo app Next dividido em duas áreas: a loja (app principal) e a conta, de outra equipe.
205
+ Exemplo: uma loja em Next.js com a área "Minha conta", feita por outra equipe.
198
206
 
199
207
  <p align="center">
200
208
  <picture>
@@ -203,18 +211,32 @@ O mesmo app Next dividido em duas áreas: a loja (app principal) e a conta, de o
203
211
  </picture>
204
212
  </p>
205
213
 
206
- **Com Multi-Zones**, a conta é um segundo app Next, e o app principal repassa as URLs para ele:
214
+ ### Hoje, com Multi-Zones
215
+
216
+ São dois apps Next. A loja repassa as URLs de `/conta` para o app da conta.
217
+
218
+ ```
219
+ loja/ app Next principal
220
+ conta/ segundo app Next (a zona)
221
+ ```
207
222
 
208
223
  ```js
209
- // conta/next.config.js (a zona)
224
+ // conta/next.config.js
210
225
  module.exports = {
211
226
  basePath: '/conta',
212
227
  assetPrefix: '/conta-static',
213
228
  }
214
229
  ```
215
230
 
231
+ ```tsx
232
+ // conta/pages/index.tsx
233
+ export default function Conta() {
234
+ return <h1>Minha conta</h1>
235
+ }
236
+ ```
237
+
216
238
  ```js
217
- // loja/next.config.js (o app principal)
239
+ // loja/next.config.js
218
240
  module.exports = {
219
241
  async rewrites() {
220
242
  return [
@@ -227,22 +249,37 @@ module.exports = {
227
249
  ```
228
250
 
229
251
  ```tsx
230
- // links entre zonas: <a>, não <Link>. A página recarrega e baixa Next e React de novo.
252
+ // loja/components/Menu.tsx
253
+ // <a>, não <Link>: a página recarrega e baixa Next e React de novo.
231
254
  <a href="/conta">Minha conta</a>
232
255
  ```
233
256
 
234
- **Com vitral**, a conta é um remote (projeto Vite) e a loja continua sendo o único app Next:
257
+ ### O mesmo app com vitral
258
+
259
+ A loja continua sendo o único app Next. A conta vira um remote: um projeto Vite com o mesmo componente.
260
+
261
+ ```
262
+ loja/ app Next (o host)
263
+ conta/ projeto Vite (o remote)
264
+ ```
235
265
 
236
266
  ```js
237
- // conta/vite.config.js (o remote)
267
+ // conta/vite.config.js (no lugar do next.config.js da zona)
238
268
  import react from '@vitejs/plugin-react'
239
269
  import vitral from 'vitral/vite'
240
270
 
241
271
  export default { plugins: [react(), vitral({ name: 'conta', dedupe: ['react'] })] }
242
272
  ```
243
273
 
274
+ ```tsx
275
+ // conta/src/App.tsx (o mesmo componente da página)
276
+ export default function Conta() {
277
+ return <h1>Minha conta</h1>
278
+ }
279
+ ```
280
+
244
281
  ```js
245
- // loja/next.config.js (o host)
282
+ // loja/next.config.js (no lugar das rewrites)
246
283
  const { withVitral } = require('vitral/next-config')
247
284
 
248
285
  module.exports = withVitral({}, {
@@ -253,7 +290,7 @@ module.exports = withVitral({}, {
253
290
  ```
254
291
 
255
292
  ```tsx
256
- // loja/pages/_app.tsx
293
+ // loja/pages/_app.tsx (só acrescenta <VitralNext />)
257
294
  import { VitralNext } from 'vitral/next-host'
258
295
 
259
296
  export default function App({ Component, pageProps }) {
@@ -262,7 +299,7 @@ export default function App({ Component, pageProps }) {
262
299
  ```
263
300
 
264
301
  ```tsx
265
- // loja/pages/conta/[[...slug]].tsx
302
+ // loja/pages/conta/[[...slug]].tsx (arquivo novo: a página que mostra a conta)
266
303
  import { NextRemote } from 'vitral/next-host'
267
304
 
268
305
  export default function Conta() {
@@ -271,328 +308,46 @@ export default function Conta() {
271
308
  ```
272
309
 
273
310
  ```tsx
274
- // links: <Link> normal. A troca é sem recarregar, e o React não baixa de novo.
311
+ // loja/components/Menu.tsx
312
+ // <Link> normal: a troca é sem recarregar, e o React não baixa de novo.
275
313
  <Link href="/conta">Minha conta</Link>
276
314
  ```
277
315
 
316
+ Se o código da conta já usa `next/link` ou `useRouter`, não precisa reescrever: `vitral({ name: 'conta', next: { basePath: '/conta' } })` builda esse código com o Vite.
317
+
318
+ ### O que muda
319
+
278
320
  | | Multi-Zones | vitral |
279
321
  |---|---|---|
280
- | Apps Next | Um por área | Só o host |
281
- | Configuração | `basePath` e `assetPrefix` na zona, `rewrites` no app principal | `withVitral` no host, plugin no remote |
322
+ | Apps Next | Um por área | Só a loja |
323
+ | Configuração | `basePath` e `assetPrefix` na zona, `rewrites` na loja | `withVitral` na loja, plugin na conta |
282
324
  | Trocar de área | Recarrega a página (0,8 s no benchmark) | Sem recarregar (0,2 s) |
283
325
  | React e Next | Baixados de novo em cada área | Uma cópia para a página toda |
284
- | Layout do app principal | Cada zona repete o seu | O remote fica dentro do layout do host |
326
+ | Layout da loja | Cada zona repete o seu | A conta fica dentro do layout da loja |
285
327
 
286
328
  Guia completo, com SSR por rota e prefetch: [Migrar do Next.js Multi-Zones](https://joaogabriel15.github.io/vitral/migracao/multi-zones).
287
329
 
288
- ## Rodar local
289
-
290
- Cada remote roda no próprio `vite dev`, numa porta. O host aponta para essas portas:
291
-
292
- ```bash
293
- cd carrinho && npm run dev # vite --port 5174
294
- cd busca && npm run dev # vite --port 5175
295
- cd loja && npm run dev # vite --port 3000
296
- ```
297
-
298
- ```json
299
- // loja/public/remotes.json
300
- {
301
- "carrinho": "http://localhost:5174/vitral.json",
302
- "busca": "http://localhost:5175/vitral.json"
303
- }
304
- ```
305
-
306
- ```js
307
- // loja/src/main.jsx
308
- configure({ remotes: '/remotes.json' })
309
- ```
310
-
311
- 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`.
312
-
313
- ## Docker e Kubernetes
314
-
315
- 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.
316
-
317
- ```yaml
318
- # compose.yaml
319
- services:
320
- loja: # host: http://localhost:8080
321
- build: ./loja
322
- ports: ["8080:80"]
323
- environment:
324
- VITRAL_REMOTES: '{"carrinho":"/mf/carrinho/vitral.json","busca":"/mf/busca/vitral.json"}'
325
- carrinho: # remote React
326
- build: ./carrinho
327
- busca: # remote Vue
328
- build: ./busca
329
- ```
330
-
331
- 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.
332
-
333
- 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.
334
-
335
- Exemplo completo, com Dockerfiles e configuração do nginx: [`examples/docker`](https://github.com/joaogabriel15/vitral/tree/main/examples/docker).
330
+ ## O que mais vem junto
336
331
 
337
- ## Frameworks
338
-
339
- | Framework | Remote | Host | Import |
340
- |---|---|---|---|
341
- | React 18/19 | `reactRemote(App)` | `<Remote>` | `vitral/react` |
342
- | Next.js (App e Pages Router) | `reactRemote(App)` | `<Remote>` | `vitral/react` |
343
- | Vue 3 | `vueRemote(App, { setup })` | `<VitralRemote>` | `vitral/vue` |
344
- | Nuxt 3/4 | `vueRemote(App, { setup })` | `<VitralRemote>` | `vitral/vue` |
345
- | Angular 17+ | `angularRemote(Component, { providers })` | `<vitral-remote>` + `provideVitral()` | `vitral/angular` |
346
- | Svelte 5 | `svelteRemote(App)` | `use:remote` | `vitral/svelte` |
347
- | Solid | `solidRemote(App)` | `<Remote>` | `vitral/solid` |
348
- | Preact | `preactRemote(App)` | `<Remote>` | `vitral/preact` |
349
- | Lit e Web Components | `elementRemote('meu-widget')` | `<vitral-remote>` | `vitral/element` |
350
- | JS e TypeScript puro | `component({ render })` | `<vitral-remote>` | `vitral` |
351
-
352
- No Next e no Nuxt o componente renderiza o `fallback` no servidor e monta o remote no cliente.
353
-
354
- Uma zona do Multi-Zones vira remote sem reescrever o código Next (`vitral({ next: true })`), e o app Next principal vira host com `withVitral` e `<NextRemote>`, trocando de área sem recarregar. Veja [Next.js](https://joaogabriel15.github.io/vitral/frameworks/next).
355
-
356
- ### Host em Vue
357
-
358
- ```vue
359
- <script setup>
360
- import { VitralRemote } from 'vitral/vue'
361
- </script>
362
-
363
- <template>
364
- <VitralRemote name="carrinho" :props="{ userId: 42 }">
365
- <template #fallback>Carregando…</template>
366
- <template #error="{ retry }"><button @click="retry">Tentar de novo</button></template>
367
- </VitralRemote>
368
- </template>
369
- ```
370
-
371
- ### Host em qualquer outro lugar
372
-
373
- `<vitral-remote>` funciona em HTML puro, Angular, Svelte, Astro ou HTML gerado no servidor:
374
-
375
- ```html
376
- <script type="module">
377
- import { configure } from 'vitral'
378
- import { defineVitralElement } from 'vitral/element'
379
-
380
- configure({ remotes: { carrinho: 'https://cdn.empresa.com/carrinho/vitral.json' } })
381
- defineVitralElement()
382
- </script>
383
-
384
- <vitral-remote name="carrinho" props='{"userId": 42}'>
385
- <p slot="fallback">Carregando…</p>
386
- <p slot="error">Indisponível</p>
387
- </vitral-remote>
388
- ```
389
-
390
- ### Remote sem framework
391
-
392
- ```ts
393
- import { component, html } from 'vitral'
394
-
395
- export default component<{ nome: string }>({
396
- state: { cliques: 0 },
397
- render: ({ nome }, state) => html`
398
- <p>Olá, ${nome}</p>
399
- <button onclick=${() => state.cliques++}>cliques: ${state.cliques}</button>
400
- `,
401
- })
402
- ```
403
-
404
- O que entra em `${}` é escapado. Mudar `state` ou as props atualiza a tela.
405
-
406
- ## Desenvolvimento
407
-
408
- - **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.
409
- - **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`.
410
- - **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.
411
-
412
- ## Comunicação entre remotes
332
+ **Dependências compartilhadas.** Com `vitral({ dedupe: ['react'] })`, o remote usa o React que já está na página e não baixa outra cópia. [Dedupe](https://joaogabriel15.github.io/vitral/aprender/dedupe)
413
333
 
414
334
  <p align="center">
415
335
  <picture>
416
- <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/joaogabriel15/vitral/main/docs/public/marca/comunicacao-escuro.png">
417
- <img src="https://raw.githubusercontent.com/joaogabriel15/vitral/main/docs/public/marca/comunicacao.png" width="900" alt="Três remotes em React, Vue e Angular. O carrinho emite um evento, a busca recebe pelo mesmo barramento, e a conta lê o usuário que o host criou com provide.">
336
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/joaogabriel15/vitral/main/docs/public/marca/dedupe-escuro.png">
337
+ <img src="https://raw.githubusercontent.com/joaogabriel15/vitral/main/docs/public/marca/dedupe.png" width="900" alt="Sem dedupe, cada remote baixa o próprio React. Com dedupe, os remotes usam o React que já está na página quando a versão serve; o que não serve baixa o próprio.">
418
338
  </picture>
419
339
  </p>
420
340
 
421
- ```js
422
- import { events } from 'vitral'
423
-
424
- events.emit('carrinho:total', 120)
425
- const parar = events.on('carrinho:total', (total) => console.log(total))
426
- events.last('carrinho:total') // 120
427
- ```
428
-
429
- Todos os remotes usam o mesmo barramento. O que um remote assina é cancelado quando ele desmonta.
430
-
431
- Para estado comum (usuário, tema, carrinho), use o contexto compartilhado:
432
-
433
- ```js
434
- import { provide, shared } from 'vitral'
435
-
436
- provide('usuario', { id: 42 }) // host: cria e é o dono
437
- provide('tema', 'claro', { writable: false }) // só o dono altera
438
- shared('tema').subscribe((tema) => console.log(tema))
439
- const nome = useShared('usuario', (u) => u?.nome) // React, Preact, Vue e Solid
440
- ```
441
-
442
- Angular usa `injectShared`, Svelte usa `$tema` e Lit usa `SharedController`. Detalhes em [Contexto compartilhado](https://joaogabriel15.github.io/vitral/aprender/contexto).
443
-
444
- Para mudar de página de dentro de um remote, use `navigate('/pedidos/42')`. Todos os roteadores da página recebem a mudança.
445
-
446
- ## CSS e Tailwind
447
-
448
- 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.
449
-
450
- Para isolar por completo, use Shadow DOM:
451
-
452
- ```jsx
453
- <Remote name="carrinho" isolate="shadow" />
454
- ```
455
-
456
- 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.
457
-
458
- O remote também pode usar o tema do host:
459
-
460
- ```js
461
- vitral({ theme: 'host' }) // var(--x) usa o valor do host, se existir
462
- configure({ styles: { inherit: ['/assets/base.css'] } }) // CSS base do host dentro do Shadow DOM
463
- ```
464
-
465
- Tema com Tailwind v4, dark mode, CSS legado e Tailwind v3 no host: [Estilos](https://joaogabriel15.github.io/vitral/aprender/estilos).
466
-
467
- ## Configuração
468
-
469
- ```js
470
- configure({
471
- remotes: '/remotes.json', // ou { nome: url }
472
- allowedOrigins: ['https://cdn.empresa.com'], // padrão: a página e as origens registradas
473
- timeout: 15000, // ms por download
474
- retries: 1, // novas tentativas em erro de rede
475
- isolate: 'none', // ou 'shadow'
476
- })
477
- ```
478
-
479
- Cada remote também aceita um objeto:
480
-
481
- ```js
482
- configure({
483
- remotes: {
484
- carrinho: { url: 'https://cdn.empresa.com/carrinho/vitral.json', integrity: 'sha384-…' },
485
- menu: { module: () => import('./menu') }, // remote local, sem rede
486
- },
487
- })
488
- ```
489
-
490
- ## Erros
491
-
492
- Todo erro é um `RemoteError` com `code`, o nome do remote e `docs`, o link da [página do erro](https://github.com/joaogabriel15/vitral/tree/main/docs/erros) 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.
493
-
494
- | `code` | Quando |
495
- |---|---|
496
- | `NOT_REGISTERED` | Nome não registrado em `configure` |
497
- | `ORIGIN_BLOCKED` | URL fora de `allowedOrigins` |
498
- | `TIMEOUT` | Não respondeu dentro de `timeout` |
499
- | `INTEGRITY` | O hash do JS não confere |
500
- | `INVALID_MODULE` | O arquivo não exporta `mount()` |
501
- | `LOAD_FAILED` | Erro de rede ou HTTP |
502
- | `MOUNT_FAILED` | O remote lançou erro ao montar |
503
- | `RENDER_FAILED` | O remote quebrou depois de montado |
504
-
505
- ## Performance
506
-
507
- 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.
508
-
509
- No CDN, sirva `vitral.json` com `Cache-Control: no-cache` e o resto (nome com hash) com `public, max-age=31536000, immutable`.
510
-
511
-
512
- Assim que o manifesto chega, o JS e o CSS do remote baixam juntos. A montagem
513
- espera os dois, para o remote não aparecer sem estilo. `configure()` abre a
514
- conexão com a origem de cada remote (`<link rel="preconnect">`).
515
-
516
- ```js
517
- import { preload } from 'vitral'
518
- // Baixa JS e CSS sem montar, por exemplo no hover de um link
519
- link.addEventListener('pointerenter', () => preload('checkout'), { once: true })
520
- ```
521
-
522
- Nos componentes de host e no `<vitral-remote>`:
523
-
524
- ```html
525
- <!-- monta perto de aparecer na tela; reserve o espaço para a página não pular -->
526
- <vitral-remote name="comentarios" loading="lazy" style="display:block;min-height:400px"></vitral-remote>
527
- <!-- monta com o navegador ocioso, mas já baixa no hover -->
528
- <vitral-remote name="checkout" loading="idle" prefetch="hover"></vitral-remote>
529
- <!-- remote que aparece logo ao abrir a página -->
530
- <vitral-remote name="cabecalho" priority="high"></vitral-remote>
531
- ```
532
-
533
- ```jsx
534
- <Remote name="checkout" loading="lazy" prefetch="visible" keepAlive />
535
- ```
536
-
537
- | Opção | Valores | O que faz |
538
- | --- | --- | --- |
539
- | `loading` | `lazy`, `idle` | Monta a 200px de aparecer na tela, ou com o navegador ocioso |
540
- | `prefetch` | `hover`, `visible`, `idle` | Chama `preload()` antes de montar |
541
- | `priority` | `high` | `fetchpriority` alto no manifesto, no JS e no CSS |
542
- | `keepAlive` (`keep-alive`) | `true` ou o máximo | Ao sair da página, o remote vai para um contêiner oculto (LRU, padrão 5); na volta só recebe as props novas |
543
-
544
- Com keep-alive, o remote pode pausar timers e assinaturas:
545
-
546
- ```js
547
- mount(el, props, ctx) {
548
- ctx.onDeactivate?.(() => clearInterval(timer))
549
- ctx.onActivate?.(() => (timer = setInterval(tick, 1000)))
550
- }
551
- ```
552
-
553
- ### Métricas
554
-
555
- Cada etapa do carregamento vira um `performance.measure` com o nome
556
- `vitral:<remote>:<etapa>`. As etapas são `manifest`, `js`, `css` e `mount`.
557
- Elas aparecem na aba Performance do DevTools. Para mandar ao seu RUM:
558
-
559
- ```js
560
- configure({
561
- onMetric: ({ name, stage, duration }) => rum.send(`vitral.${stage}`, duration, { remote: name }),
562
- })
563
- ```
564
-
565
- O evento `vitral-ready` (e o `ready` do componente Vue) traz os tempos em
566
- `detail.timings`, por exemplo `{ manifest: 12.3, js: 40.1, css: 8, mount: 2.4 }`.
567
- Um remote local (`module`) só mede `css` e `mount`. Erros dentro do
568
- `onMetric` são ignorados.
569
-
570
- ## Dependências compartilhadas
571
-
572
- Para não baixar React ou Vue mais de uma vez, liste-os em `dedupe` no remote:
341
+ **Comunicação entre remotes.** `events` manda mensagens entre remotes, e `provide` e `shared` guardam estado comum, como o usuário logado. [Props e eventos](https://joaogabriel15.github.io/vitral/aprender/props-eventos) e [Contexto compartilhado](https://joaogabriel15.github.io/vitral/aprender/contexto)
573
342
 
574
343
  <p align="center">
575
344
  <picture>
576
- <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/joaogabriel15/vitral/main/docs/public/marca/dedupe-escuro.png">
577
- <img src="https://raw.githubusercontent.com/joaogabriel15/vitral/main/docs/public/marca/dedupe.png" width="900" alt="Sem dedupe, cada remote baixa o próprio React. Com dedupe, os remotes usam o React que já está na página quando a versão serve; o que não serve baixa o próprio.">
345
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/joaogabriel15/vitral/main/docs/public/marca/comunicacao-escuro.png">
346
+ <img src="https://raw.githubusercontent.com/joaogabriel15/vitral/main/docs/public/marca/comunicacao.png" width="900" alt="Três remotes em React, Vue e Angular. O carrinho emite um evento, a busca recebe pelo mesmo barramento, e a conta lê o usuário que o host criou com provide.">
578
347
  </picture>
579
348
  </p>
580
349
 
581
- ```js
582
- vitral({ dedupe: ['react'] })
583
- ```
584
-
585
- 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.
586
-
587
- ### Mais formas de usar
588
-
589
- Vários componentes por remote (`<Remote name="carrinho/MiniCarrinho" />`),
590
- módulos sem UI (`loadModule('carrinho/api')`), deploy novo sem recarregar a
591
- página (`watchUpdates()` e `refresh('carrinho')`) e app shell por rota
592
- (`routes()` e `<vitral-outlet>`, em `vitral/routes`). Veja
593
- [Exposes](https://joaogabriel15.github.io/vitral/aprender/exposes), [Atualização sem reload](https://joaogabriel15.github.io/vitral/aprender/atualizacoes) e [Rotas](https://joaogabriel15.github.io/vitral/aprender/rotas).
594
-
595
- ## Segurança
350
+ **Segurança.** O JS só roda se vier de uma origem permitida e, com `integrity`, se o hash bater. [SRI e origens](https://joaogabriel15.github.io/vitral/aprender/seguranca)
596
351
 
597
352
  <p align="center">
598
353
  <picture>
@@ -601,27 +356,37 @@ página (`watchUpdates()` e `refresh('carrinho')`) e app shell por rota
601
356
  </picture>
602
357
  </p>
603
358
 
604
- - 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`.
605
- - 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.
606
- - Com CSP, a lib copia o `nonce` de um `<script nonce>` da página para o import map. Sem nonce, cai para o `modulepreload`.
607
- - O hash só protege contra CDN comprometido se vier de outro lugar: fixe `integrity` no host ou embuta o manifesto (`{ url, manifest }`).
608
- - Sem `eval` e sem iframes.
609
- - Shadow DOM isola o CSS, não o JS. Para código de terceiros em que você não confia, use iframe.
359
+ E também:
610
360
 
611
- ## Testes do host
361
+ - **CSS e Tailwind:** o CSS de cada remote vale só dentro dele, ou use Shadow DOM com `isolate="shadow"`. [Estilos](https://joaogabriel15.github.io/vitral/aprender/estilos)
362
+ - **Carregamento:** `loading="lazy"`, `prefetch="hover"` e `keepAlive` para abrir e voltar mais rápido. [Carregamento](https://joaogabriel15.github.io/vitral/aprender/carregamento)
363
+ - **Erros:** cada erro tem um código e uma página com causa e correção, e `retry` monta só aquele remote de novo. [Erros](https://joaogabriel15.github.io/vitral/erros/)
364
+ - **Props tipadas:** `npx vitral types` faz uma prop errada não compilar no host. [Contratos](https://joaogabriel15.github.io/vitral/aprender/contratos)
365
+ - **Rotas, SSR e deploy:** app shell por rota, HTML do remote no servidor, canary e rollback. [Rotas](https://joaogabriel15.github.io/vitral/aprender/rotas), [SSR](https://joaogabriel15.github.io/vitral/aprender/ssr) e [Canary](https://joaogabriel15.github.io/vitral/aprender/canary)
366
+ - **Testes:** `mockRemote` e `failingRemote` testam o host sem rede. [Testes](https://joaogabriel15.github.io/vitral/aprender/testes)
612
367
 
613
- ```ts
614
- import { mockRemote, failingRemote } from 'vitral/testing'
368
+ ## Rodar local e com Docker
615
369
 
616
- const carrinho = mockRemote('carrinho', (el, props) => (el.textContent = `itens: ${props.itens}`))
617
- // renderize o host
618
- expect(carrinho.lastProps).toEqual({ itens: 2 })
370
+ Cada remote roda no próprio `vite dev`, numa porta, e o host aponta para essas portas:
619
371
 
620
- failingRemote('recomendacoes') // testa a tela de erro
372
+ ```json
373
+ // loja/public/remotes.json
374
+ {
375
+ "carrinho": "http://localhost:5174/vitral.json",
376
+ "busca": "http://localhost:5175/vitral.json"
377
+ }
621
378
  ```
622
379
 
380
+ ```js
381
+ // loja/src/main.jsx
382
+ configure({ remotes: '/remotes.json' })
383
+ ```
384
+
385
+ Editar o remote atualiza o host sem recarregar a página. Com Docker, cada remote vira uma imagem nginx e o host lê a lista de remotes de uma variável de ambiente, então a mesma imagem serve em qualquer ambiente. [Local e Docker](https://joaogabriel15.github.io/vitral/aprender/local-e-docker) e o exemplo [`examples/docker`](https://github.com/joaogabriel15/vitral/tree/main/examples/docker).
386
+
623
387
  ## Links
624
388
 
389
+ - [Documentação](https://joaogabriel15.github.io/vitral/): guias, referência e páginas de erro.
625
390
  - [Exemplos](https://github.com/joaogabriel15/vitral/tree/main/examples): o mesmo remote em 8 frameworks e 9 hosts.
626
391
  - [Como contribuir](https://github.com/joaogabriel15/vitral/blob/main/CONTRIBUTING.md)
627
392
  - Licença [MIT](https://github.com/joaogabriel15/vitral/blob/main/LICENSE). Feito por [Pacheco Codes](https://pacheco.dev.br/).
@@ -18,7 +18,7 @@ interface RemotePropsOptions {
18
18
  */
19
19
  staleWhileRevalidate?: number;
20
20
  /**
21
- * Origem para o `url` relativo do remote (`/delivery-remote/vitral.json`).
21
+ * Origem para o `url` relativo do remote (`/conta/vitral.json`).
22
22
  * Padrão: `VITRAL_ORIGIN` do ambiente, ou o próprio servidor Next em
23
23
  * `http://127.0.0.1:$PORT`. O header `Host` da requisição nunca é usado: um
24
24
  * cliente poderia apontar o servidor para outra máquina.
package/dist/next.d.ts CHANGED
@@ -118,7 +118,7 @@ type ImageProps = Omit<ImgHTMLAttributes<HTMLImageElement>, 'src' | 'width' | 'h
118
118
  }) => string;
119
119
  onLoadingComplete?: (img: HTMLImageElement) => void;
120
120
  };
121
- declare const Image: react.ForwardRefExoticComponent<Omit<ImgHTMLAttributes<HTMLImageElement>, "height" | "width" | "loading" | "src"> & {
121
+ declare const Image: react.ForwardRefExoticComponent<Omit<ImgHTMLAttributes<HTMLImageElement>, "loading" | "src" | "width" | "height"> & {
122
122
  src: string | StaticImage;
123
123
  alt: string;
124
124
  width?: number | string;
package/dist/sw.d.ts CHANGED
@@ -8,7 +8,7 @@ import './errors-kjBv6IH_.js';
8
8
  * // sw.js do host
9
9
  * import { remoteFiles } from 'vitral/sw'
10
10
  * self.addEventListener('install', (e) => e.waitUntil(
11
- * remoteFiles('/delivery-remote/vitral.json').then((urls) => caches.open('remotes').then((c) => c.addAll(urls))),
11
+ * remoteFiles('/conta/vitral.json').then((urls) => caches.open('remotes').then((c) => c.addAll(urls))),
12
12
  * ))
13
13
  */
14
14
 
@@ -48,7 +48,7 @@ interface Scope {
48
48
  *
49
49
  * // sw.js do host
50
50
  * import { remoteWorker } from 'vitral/sw'
51
- * remoteWorker(self, { manifests: ['/delivery-remote/vitral.json'] })
51
+ * remoteWorker(self, { manifests: ['/conta/vitral.json'] })
52
52
  */
53
53
  declare function remoteWorker(self: Scope, o: RemoteWorkerOptions): void;
54
54
 
package/dist/vue.d.ts CHANGED
@@ -127,9 +127,9 @@ declare const VitralRemote: vue.DefineComponent<vue.ExtractPropTypes<{
127
127
  onError?: ((...args: any[]) => any) | undefined;
128
128
  onReady?: ((...args: any[]) => any) | undefined;
129
129
  }>, {
130
- name: string;
131
130
  isolate: Isolation;
132
131
  priority: RequestPriority;
132
+ name: string;
133
133
  loading: Loading;
134
134
  src: string;
135
135
  props: Props;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "vitral",
3
- "version": "0.11.2",
3
+ "version": "0.11.3",
4
4
  "description": "Micro-frontends com qualquer framework, sem configurar build no host. React, Next.js, Vue, Nuxt, Angular, Svelte e outros na mesma página.",
5
5
  "keywords": [
6
6
  "micro-frontend",