vitral 0.11.2 → 0.11.4

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
  ```
@@ -82,119 +86,117 @@ Os 10 frameworks têm testes de ponta a ponta no CI, com host e remote de framew
82
86
 
83
87
  ## Começo rápido
84
88
 
85
- Para gerar host e remote prontos: `npm create vitral@latest`.
89
+ Exemplo: uma loja em React que mostra o carrinho, feito por outra equipe.
86
90
 
87
- **1. No remote**, exporte o componente e use o plugin:
91
+ ### Hoje, com Module Federation
88
92
 
89
- ```jsx
90
- // src/App.jsx (ou .vue, .svelte, .tsx…)
91
- export default function Carrinho({ userId }) { … }
92
- ```
93
+ Loja e carrinho combinam a configuração no build dos dois: o que cada um expõe, o que pega do outro e quais versões dividem.
93
94
 
94
95
  ```js
95
- // vite.config.js
96
- import react from '@vitejs/plugin-react'
97
- import vitral from 'vitral/vite'
98
-
99
- export default { plugins: [react(), vitral()] }
96
+ // carrinho/webpack.config.js
97
+ new ModuleFederationPlugin({
98
+ name: 'carrinho',
99
+ filename: 'remoteEntry.js',
100
+ exposes: { './Carrinho': './src/Carrinho' },
101
+ shared: { react: { singleton: true }, 'react-dom': { singleton: true } },
102
+ })
100
103
  ```
101
104
 
102
- O plugin descobre o framework e embrulha o `export default` com o adaptador certo. A entrada padrão é `src/remote.*` ou `src/App.*`.
103
-
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:
105
+ ```js
106
+ // loja/webpack.config.js
107
+ new ModuleFederationPlugin({
108
+ name: 'loja',
109
+ remotes: { carrinho: 'carrinho@https://cdn.empresa.com/carrinho/remoteEntry.js' },
110
+ shared: { react: { singleton: true }, 'react-dom': { singleton: true } },
111
+ })
112
+ ```
107
113
 
108
114
  ```jsx
109
- import { configure } from 'vitral'
110
- import { Remote } from 'vitral/react'
111
-
112
- configure({
113
- remotes: { carrinho: 'https://cdn.empresa.com/carrinho/vitral.json' },
114
- })
115
+ // loja/src/App.jsx
116
+ const Carrinho = React.lazy(() => import('carrinho/Carrinho'))
115
117
 
116
118
  export function App() {
117
119
  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
- />
120
+ <ErrorBoundary fallback={<p>Erro</p>}>
121
+ <Suspense fallback={<p>Carregando…</p>}>
122
+ <Carrinho userId={42} />
123
+ </Suspense>
124
+ </ErrorBoundary>
124
125
  )
125
126
  }
126
127
  ```
127
128
 
128
- Pronto. Mudar `props` atualiza o remote sem remontar.
129
+ ### O mesmo app com vitral
129
130
 
130
- Sem build no host, numa página HTML qualquer:
131
+ Só o carrinho tem plugin. O build da loja não muda.
131
132
 
132
- ```html
133
- <script type="module" src="https://cdn.jsdelivr.net/npm/vitral/dist/auto.js"></script>
134
- <vitral-remote src="https://cdn.empresa.com/carrinho/vitral.json"></vitral-remote>
133
+ ```jsx
134
+ // carrinho/src/App.jsx (o mesmo componente)
135
+ export default function Carrinho({ userId }) { … }
135
136
  ```
136
137
 
137
- Todos os componentes de host aceitam `src` no lugar de `name`.
138
-
139
- ## Next.js e Nuxt como host
138
+ ```js
139
+ // carrinho/vite.config.js (no lugar do ModuleFederationPlugin)
140
+ import react from '@vitejs/plugin-react'
141
+ import vitral from 'vitral/vite'
140
142
 
141
- O remote é sempre um projeto Vite (React, Vue ou outro), como no Começo rápido acima. O host pode ser um app Next ou Nuxt.
143
+ export default { plugins: [react(), vitral()] }
144
+ ```
142
145
 
143
- **Next.js (App Router):**
146
+ `vite build` gera o JS, o CSS e um `vitral.json`. Publique a pasta `dist` em qualquer CDN.
144
147
 
145
- ```tsx
146
- // app/carrinho.tsx
147
- 'use client'
148
+ ```jsx
149
+ // loja/src/App.jsx (sem plugin no build da loja)
148
150
  import { configure } from 'vitral'
149
151
  import { Remote } from 'vitral/react'
150
152
 
151
- if (typeof window !== 'undefined') {
152
- configure({ remotes: { carrinho: 'https://cdn.empresa.com/carrinho/vitral.json' } })
153
- }
153
+ configure({ remotes: { carrinho: 'https://cdn.empresa.com/carrinho/vitral.json' } })
154
154
 
155
- export function Carrinho({ userId }: { userId: number }) {
156
- return <Remote name="carrinho" props={{ userId }} fallback={<p>Carregando…</p>} />
155
+ export function App() {
156
+ return <Remote name="carrinho" props={{ userId: 42 }} fallback={<p>Carregando…</p>} />
157
157
  }
158
158
  ```
159
159
 
160
- ```tsx
161
- // app/page.tsx
162
- import { Carrinho } from './carrinho'
160
+ Pronto. Mudar `props` atualiza o remote sem remontar. Para gerar loja e carrinho prontos: `npm create vitral@latest`.
163
161
 
164
- export default function Page() {
165
- return <main><Carrinho userId={42} /></main>
166
- }
167
- ```
162
+ ### O que muda
168
163
 
169
- **Nuxt 3 e 4:**
164
+ | | Module Federation | vitral |
165
+ |---|---|---|
166
+ | Build da loja | Plugin com `remotes` e `shared` | Não muda |
167
+ | Versão do React | Combinada entre as equipes (`singleton`) | Cada um usa a sua. Uma cópia só com [`dedupe`](https://joaogabriel15.github.io/vitral/aprender/dedupe) |
168
+ | Carregando e erro | `Suspense` e `ErrorBoundary` | `fallback` e `error` do `<Remote>` |
169
+ | Framework | O mesmo nos dois lados | Qualquer um. A loja em React pode mostrar um carrinho em Vue |
170
170
 
171
- ```ts
172
- // app/plugins/vitral.client.ts
173
- import { configure } from 'vitral'
171
+ Numa página HTML qualquer, sem build:
174
172
 
175
- export default defineNuxtPlugin(() => {
176
- configure({ remotes: { catalogo: 'https://cdn.empresa.com/catalogo/vitral.json' } })
177
- })
173
+ ```html
174
+ <script type="module" src="https://cdn.jsdelivr.net/npm/vitral/dist/auto.js"></script>
175
+ <vitral-remote src="https://cdn.empresa.com/carrinho/vitral.json"></vitral-remote>
178
176
  ```
179
177
 
180
- ```vue
181
- <!-- app/pages/index.vue -->
182
- <script setup lang="ts">
183
- import { VitralRemote } from 'vitral/vue'
184
- </script>
178
+ Guia completo: [Migrar do Module Federation](https://joaogabriel15.github.io/vitral/migracao/module-federation).
185
179
 
186
- <template>
187
- <VitralRemote name="catalogo" :props="{ userId: 42 }">
188
- <template #fallback><p>Carregando…</p></template>
189
- </VitralRemote>
190
- </template>
191
- ```
180
+ ## Frameworks
192
181
 
193
- Nos dois, o servidor renderiza o `fallback` e o remote monta no navegador. Não precisa de `dynamic(..., { ssr: false })` nem de `<ClientOnly>`.
182
+ | Framework | Remote | Host | Import |
183
+ |---|---|---|---|
184
+ | React 18/19 | `reactRemote(App)` | `<Remote>` | `vitral/react` |
185
+ | Next.js (App e Pages Router) | `reactRemote(App)` | `<Remote>` | `vitral/react` |
186
+ | Vue 3 | `vueRemote(App, { setup })` | `<VitralRemote>` | `vitral/vue` |
187
+ | Nuxt 3/4 | `vueRemote(App, { setup })` | `<VitralRemote>` | `vitral/vue` |
188
+ | Angular 17+ | `angularRemote(Component, { providers })` | `<vitral-remote>` + `provideVitral()` | `vitral/angular` |
189
+ | Svelte 5 | `svelteRemote(App)` | `use:remote` | `vitral/svelte` |
190
+ | Solid | `solidRemote(App)` | `<Remote>` | `vitral/solid` |
191
+ | Preact | `preactRemote(App)` | `<Remote>` | `vitral/preact` |
192
+ | Lit e Web Components | `elementRemote('meu-widget')` | `<vitral-remote>` | `vitral/element` |
193
+ | JS e TypeScript puro | `component({ render })` | `<vitral-remote>` | `vitral` |
194
+
195
+ 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).
194
196
 
195
- ## Multi-Zones ou vitral
197
+ ## Next.js como host
196
198
 
197
- O mesmo app Next dividido em duas áreas: a loja (app principal) e a conta, de outra equipe.
199
+ Exemplo: uma loja em Next.js com a área "Minha conta", feita por outra equipe.
198
200
 
199
201
  <p align="center">
200
202
  <picture>
@@ -203,18 +205,32 @@ O mesmo app Next dividido em duas áreas: a loja (app principal) e a conta, de o
203
205
  </picture>
204
206
  </p>
205
207
 
206
- **Com Multi-Zones**, a conta é um segundo app Next, e o app principal repassa as URLs para ele:
208
+ ### Hoje, com Multi-Zones
209
+
210
+ São dois apps Next. A loja repassa as URLs de `/conta` para o app da conta.
211
+
212
+ ```
213
+ loja/ app Next principal
214
+ conta/ segundo app Next (a zona)
215
+ ```
207
216
 
208
217
  ```js
209
- // conta/next.config.js (a zona)
218
+ // conta/next.config.js
210
219
  module.exports = {
211
220
  basePath: '/conta',
212
221
  assetPrefix: '/conta-static',
213
222
  }
214
223
  ```
215
224
 
225
+ ```tsx
226
+ // conta/pages/index.tsx
227
+ export default function Conta() {
228
+ return <h1>Minha conta</h1>
229
+ }
230
+ ```
231
+
216
232
  ```js
217
- // loja/next.config.js (o app principal)
233
+ // loja/next.config.js
218
234
  module.exports = {
219
235
  async rewrites() {
220
236
  return [
@@ -227,22 +243,37 @@ module.exports = {
227
243
  ```
228
244
 
229
245
  ```tsx
230
- // links entre zonas: <a>, não <Link>. A página recarrega e baixa Next e React de novo.
246
+ // loja/components/Menu.tsx
247
+ // <a>, não <Link>: a página recarrega e baixa Next e React de novo.
231
248
  <a href="/conta">Minha conta</a>
232
249
  ```
233
250
 
234
- **Com vitral**, a conta é um remote (projeto Vite) e a loja continua sendo o único app Next:
251
+ ### O mesmo app com vitral
252
+
253
+ A loja continua sendo o único app Next. A conta vira um remote: um projeto Vite com o mesmo componente.
254
+
255
+ ```
256
+ loja/ app Next (o host)
257
+ conta/ projeto Vite (o remote)
258
+ ```
235
259
 
236
260
  ```js
237
- // conta/vite.config.js (o remote)
261
+ // conta/vite.config.js (no lugar do next.config.js da zona)
238
262
  import react from '@vitejs/plugin-react'
239
263
  import vitral from 'vitral/vite'
240
264
 
241
265
  export default { plugins: [react(), vitral({ name: 'conta', dedupe: ['react'] })] }
242
266
  ```
243
267
 
268
+ ```tsx
269
+ // conta/src/App.tsx (o mesmo componente da página)
270
+ export default function Conta() {
271
+ return <h1>Minha conta</h1>
272
+ }
273
+ ```
274
+
244
275
  ```js
245
- // loja/next.config.js (o host)
276
+ // loja/next.config.js (no lugar das rewrites)
246
277
  const { withVitral } = require('vitral/next-config')
247
278
 
248
279
  module.exports = withVitral({}, {
@@ -253,7 +284,7 @@ module.exports = withVitral({}, {
253
284
  ```
254
285
 
255
286
  ```tsx
256
- // loja/pages/_app.tsx
287
+ // loja/pages/_app.tsx (só acrescenta <VitralNext />)
257
288
  import { VitralNext } from 'vitral/next-host'
258
289
 
259
290
  export default function App({ Component, pageProps }) {
@@ -262,7 +293,7 @@ export default function App({ Component, pageProps }) {
262
293
  ```
263
294
 
264
295
  ```tsx
265
- // loja/pages/conta/[[...slug]].tsx
296
+ // loja/pages/conta/[[...slug]].tsx (arquivo novo: a página que mostra a conta)
266
297
  import { NextRemote } from 'vitral/next-host'
267
298
 
268
299
  export default function Conta() {
@@ -271,305 +302,136 @@ export default function Conta() {
271
302
  ```
272
303
 
273
304
  ```tsx
274
- // links: <Link> normal. A troca é sem recarregar, e o React não baixa de novo.
305
+ // loja/components/Menu.tsx
306
+ // <Link> normal: a troca é sem recarregar, e o React não baixa de novo.
275
307
  <Link href="/conta">Minha conta</Link>
276
308
  ```
277
309
 
310
+ 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.
311
+
312
+ ### O que muda
313
+
278
314
  | | Multi-Zones | vitral |
279
315
  |---|---|---|
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 |
316
+ | Apps Next | Um por área | Só a loja |
317
+ | Configuração | `basePath` e `assetPrefix` na zona, `rewrites` na loja | `withVitral` na loja, plugin na conta |
282
318
  | Trocar de área | Recarrega a página (0,8 s no benchmark) | Sem recarregar (0,2 s) |
283
319
  | 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 |
320
+ | Layout da loja | Cada zona repete o seu | A conta fica dentro do layout da loja |
285
321
 
286
322
  Guia completo, com SSR por rota e prefetch: [Migrar do Next.js Multi-Zones](https://joaogabriel15.github.io/vitral/migracao/multi-zones).
287
323
 
288
- ## Rodar local
324
+ No App Router, o host usa `<Remote>` de `vitral/react` num componente `'use client'`. Exemplo em [Next.js](https://joaogabriel15.github.io/vitral/frameworks/next#host-com-app-router).
289
325
 
290
- Cada remote roda no próprio `vite dev`, numa porta. O host aponta para essas portas:
326
+ ## Nuxt como host
291
327
 
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
- ```
328
+ Exemplo: uma loja em Nuxt com a área "Catálogo", feita por outra equipe.
297
329
 
298
- ```json
299
- // loja/public/remotes.json
300
- {
301
- "carrinho": "http://localhost:5174/vitral.json",
302
- "busca": "http://localhost:5175/vitral.json"
303
- }
304
- ```
330
+ ### Hoje, com dois apps Nuxt
305
331
 
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`.
332
+ A loja repassa as URLs de `/catalogo` para o app do catálogo.
312
333
 
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
334
  ```
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).
336
-
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>
335
+ loja/ app Nuxt principal
336
+ catalogo/ segundo app Nuxt
369
337
  ```
370
338
 
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>
339
+ ```ts
340
+ // catalogo/nuxt.config.ts
341
+ export default defineNuxtConfig({
342
+ app: { baseURL: '/catalogo/' },
343
+ })
388
344
  ```
389
345
 
390
- ### Remote sem framework
346
+ ```vue
347
+ <!-- catalogo/app/pages/index.vue -->
348
+ <template><h1>Catálogo</h1></template>
349
+ ```
391
350
 
392
351
  ```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
- `,
352
+ // loja/nuxt.config.ts
353
+ export default defineNuxtConfig({
354
+ routeRules: {
355
+ '/catalogo/**': { proxy: `${process.env.CATALOGO_URL}/catalogo/**` },
356
+ },
401
357
  })
402
358
  ```
403
359
 
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
413
-
414
- <p align="center">
415
- <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.">
418
- </picture>
419
- </p>
420
-
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
360
+ ```vue
361
+ <!-- loja/app/components/Menu.vue -->
362
+ <!-- <a>, não <NuxtLink>: a página recarrega e baixa Nuxt e Vue de novo. -->
363
+ <a href="/catalogo">Catálogo</a>
427
364
  ```
428
365
 
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:
366
+ ### O mesmo app com vitral
432
367
 
433
- ```js
434
- import { provide, shared } from 'vitral'
368
+ A loja continua sendo o único app Nuxt. O catálogo vira um remote: um projeto Vite com o mesmo componente.
435
369
 
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
370
  ```
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" />
371
+ loja/ app Nuxt (o host)
372
+ catalogo/ projeto Vite (o remote)
454
373
  ```
455
374
 
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
375
  ```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
376
+ // catalogo/vite.config.js (no lugar do app Nuxt do catálogo)
377
+ import vue from '@vitejs/plugin-vue'
378
+ import vitral from 'vitral/vite'
468
379
 
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
- })
380
+ export default { plugins: [vue(), vitral({ name: 'catalogo', dedupe: ['vue'] })] }
477
381
  ```
478
382
 
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
- })
383
+ ```vue
384
+ <!-- catalogo/src/App.vue (o mesmo componente da página) -->
385
+ <template><h1>Catálogo</h1></template>
488
386
  ```
489
387
 
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">`).
388
+ ```ts
389
+ // loja/app/plugins/vitral.client.ts (no lugar do proxy)
390
+ import * as Vue from 'vue'
391
+ import { configure } from 'vitral'
515
392
 
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 })
393
+ export default defineNuxtPlugin(() => {
394
+ configure({
395
+ remotes: { catalogo: 'https://cdn.empresa.com/catalogo/vitral.json' },
396
+ dedupe: { vue: { version: Vue.version, modules: { vue: Vue } } }, // o catálogo usa este Vue
397
+ })
398
+ })
520
399
  ```
521
400
 
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
- ```
401
+ ```vue
402
+ <!-- loja/app/pages/catalogo.vue (arquivo novo: a página que mostra o catálogo) -->
403
+ <script setup lang="ts">
404
+ import { VitralRemote } from 'vitral/vue'
405
+ </script>
532
406
 
533
- ```jsx
534
- <Remote name="checkout" loading="lazy" prefetch="visible" keepAlive />
407
+ <template>
408
+ <VitralRemote name="catalogo">
409
+ <template #fallback><p>Carregando…</p></template>
410
+ </VitralRemote>
411
+ </template>
535
412
  ```
536
413
 
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
- }
414
+ ```vue
415
+ <!-- loja/app/components/Menu.vue -->
416
+ <!-- <NuxtLink> normal: a troca é sem recarregar. -->
417
+ <NuxtLink to="/catalogo">Catálogo</NuxtLink>
551
418
  ```
552
419
 
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:
420
+ O servidor renderiza o `fallback` e o catálogo monta no navegador. Não precisa de `<ClientOnly>`.
558
421
 
559
- ```js
560
- configure({
561
- onMetric: ({ name, stage, duration }) => rum.send(`vitral.${stage}`, duration, { remote: name }),
562
- })
563
- ```
422
+ ### O que muda
564
423
 
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.
424
+ | | Dois apps Nuxt | vitral |
425
+ |---|---|---|
426
+ | Apps Nuxt | Um por área | Só a loja |
427
+ | Configuração | `baseURL` no catálogo, `proxy` na loja | Plugin no catálogo, `configure()` na loja |
428
+ | Trocar de área | Recarrega a página | Sem recarregar |
429
+ | Vue e Nuxt | Baixados de novo em cada área | Uma cópia do Vue para a página toda |
430
+ | Layout da loja | Cada app repete o seu | O catálogo fica dentro do layout da loja |
569
431
 
570
- ## Dependências compartilhadas
432
+ ## O que mais vem junto
571
433
 
572
- Para não baixar React ou Vue mais de uma vez, liste-os em `dedupe` no remote:
434
+ **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)
573
435
 
574
436
  <p align="center">
575
437
  <picture>
@@ -578,21 +440,16 @@ Para não baixar React ou Vue mais de uma vez, liste-os em `dedupe` no remote:
578
440
  </picture>
579
441
  </p>
580
442
 
581
- ```js
582
- vitral({ dedupe: ['react'] })
583
- ```
443
+ **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)
584
444
 
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).
445
+ <p align="center">
446
+ <picture>
447
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/joaogabriel15/vitral/main/docs/public/marca/comunicacao-escuro.png">
448
+ <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.">
449
+ </picture>
450
+ </p>
594
451
 
595
- ## Segurança
452
+ **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
453
 
597
454
  <p align="center">
598
455
  <picture>
@@ -601,27 +458,37 @@ página (`watchUpdates()` e `refresh('carrinho')`) e app shell por rota
601
458
  </picture>
602
459
  </p>
603
460
 
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.
461
+ E também:
610
462
 
611
- ## Testes do host
463
+ - **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)
464
+ - **Carregamento:** `loading="lazy"`, `prefetch="hover"` e `keepAlive` para abrir e voltar mais rápido. [Carregamento](https://joaogabriel15.github.io/vitral/aprender/carregamento)
465
+ - **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/)
466
+ - **Props tipadas:** `npx vitral types` faz uma prop errada não compilar no host. [Contratos](https://joaogabriel15.github.io/vitral/aprender/contratos)
467
+ - **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)
468
+ - **Testes:** `mockRemote` e `failingRemote` testam o host sem rede. [Testes](https://joaogabriel15.github.io/vitral/aprender/testes)
612
469
 
613
- ```ts
614
- import { mockRemote, failingRemote } from 'vitral/testing'
470
+ ## Rodar local e com Docker
615
471
 
616
- const carrinho = mockRemote('carrinho', (el, props) => (el.textContent = `itens: ${props.itens}`))
617
- // renderize o host
618
- expect(carrinho.lastProps).toEqual({ itens: 2 })
472
+ Cada remote roda no próprio `vite dev`, numa porta, e o host aponta para essas portas:
473
+
474
+ ```json
475
+ // loja/public/remotes.json
476
+ {
477
+ "carrinho": "http://localhost:5174/vitral.json",
478
+ "busca": "http://localhost:5175/vitral.json"
479
+ }
480
+ ```
619
481
 
620
- failingRemote('recomendacoes') // testa a tela de erro
482
+ ```js
483
+ // loja/src/main.jsx
484
+ configure({ remotes: '/remotes.json' })
621
485
  ```
622
486
 
487
+ 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).
488
+
623
489
  ## Links
624
490
 
491
+ - [Documentação](https://joaogabriel15.github.io/vitral/): guias, referência e páginas de erro.
625
492
  - [Exemplos](https://github.com/joaogabriel15/vitral/tree/main/examples): o mesmo remote em 8 frameworks e 9 hosts.
626
493
  - [Como contribuir](https://github.com/joaogabriel15/vitral/blob/main/CONTRIBUTING.md)
627
494
  - 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.4",
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",