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 +106 -341
- package/dist/next-server.d.ts +1 -1
- package/dist/next.d.ts +1 -1
- package/dist/sw.d.ts +2 -2
- package/dist/vue.d.ts +1 -1
- package/package.json +1 -1
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
|
-
|
|
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
|
|
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
|
-
|
|
106
|
+
`vite build` gera o JS, o CSS e um `vitral.json`. Publique a pasta `dist` em qualquer CDN.
|
|
103
107
|
|
|
104
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
-
//
|
|
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
|
-
|
|
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 (
|
|
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 (
|
|
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
|
-
//
|
|
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ó
|
|
281
|
-
| Configuração | `basePath` e `assetPrefix` na zona, `rewrites`
|
|
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
|
|
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
|
-
##
|
|
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
|
-
|
|
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/
|
|
417
|
-
<img src="https://raw.githubusercontent.com/joaogabriel15/vitral/main/docs/public/marca/
|
|
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
|
-
|
|
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/
|
|
577
|
-
<img src="https://raw.githubusercontent.com/joaogabriel15/vitral/main/docs/public/marca/
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
614
|
-
import { mockRemote, failingRemote } from 'vitral/testing'
|
|
368
|
+
## Rodar local e com Docker
|
|
615
369
|
|
|
616
|
-
|
|
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
|
-
|
|
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/).
|
package/dist/next-server.d.ts
CHANGED
|
@@ -18,7 +18,7 @@ interface RemotePropsOptions {
|
|
|
18
18
|
*/
|
|
19
19
|
staleWhileRevalidate?: number;
|
|
20
20
|
/**
|
|
21
|
-
* Origem para o `url` relativo do remote (`/
|
|
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>, "
|
|
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('/
|
|
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: ['/
|
|
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