vitral 0.13.1 → 0.13.2
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 +209 -194
- package/dist/next.d.ts +1 -1
- package/dist/vue.d.ts +1 -1
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,41 +1,45 @@
|
|
|
1
1
|
<p align="center">
|
|
2
2
|
<picture>
|
|
3
|
-
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/joaogabriel15/vitral/main/docs/public/marca/banner-escuro.png">
|
|
4
|
-
<img src="https://raw.githubusercontent.com/joaogabriel15/vitral/main/docs/public/marca/banner.png" width="640" alt="vitral.
|
|
3
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/joaogabriel15/vitral/main/docs/public/marca/banner-escuro-en.png">
|
|
4
|
+
<img src="https://raw.githubusercontent.com/joaogabriel15/vitral/main/docs/public/marca/banner-en.png" width="640" alt="vitral. Made of parts. Seen as a whole.">
|
|
5
5
|
</picture>
|
|
6
6
|
</p>
|
|
7
7
|
|
|
8
8
|
<p align="center">
|
|
9
9
|
<a href="https://github.com/joaogabriel15/vitral/actions/workflows/ci.yml"><img src="https://github.com/joaogabriel15/vitral/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
|
|
10
10
|
<a href="https://www.npmjs.com/package/vitral"><img src="https://img.shields.io/npm/v/vitral" alt="npm"></a>
|
|
11
|
-
<a href="https://bundlejs.com/?q=vitral"><img src="https://img.shields.io/bundlejs/size/vitral" alt="
|
|
12
|
-
<a href="https://github.com/joaogabriel15/vitral/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/vitral" alt="
|
|
11
|
+
<a href="https://bundlejs.com/?q=vitral"><img src="https://img.shields.io/bundlejs/size/vitral" alt="size"></a>
|
|
12
|
+
<a href="https://github.com/joaogabriel15/vitral/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/vitral" alt="MIT license"></a>
|
|
13
13
|
</p>
|
|
14
14
|
|
|
15
15
|
<p align="center">
|
|
16
|
-
<a href="https://joaogabriel15.github.io/vitral/">
|
|
17
|
-
<a href="https://joaogabriel15.github.io/vitral/aprender/configurar">
|
|
18
|
-
<a href="https://joaogabriel15.github.io/vitral/por-que">
|
|
19
|
-
<a href="https://joaogabriel15.github.io/vitral/aprender/benchmark">Benchmark</a> ·
|
|
20
|
-
<a href="
|
|
16
|
+
<a href="https://joaogabriel15.github.io/vitral/en/">Docs</a> ·
|
|
17
|
+
<a href="https://joaogabriel15.github.io/vitral/en/aprender/configurar">Get started</a> ·
|
|
18
|
+
<a href="https://joaogabriel15.github.io/vitral/en/por-que">Why vitral</a> ·
|
|
19
|
+
<a href="https://joaogabriel15.github.io/vitral/en/aprender/benchmark">Benchmark</a> ·
|
|
20
|
+
<a href="https://github.com/joaogabriel15/vitral/blob/main/README.md">Português</a>
|
|
21
21
|
</p>
|
|
22
22
|
|
|
23
|
-
Micro-frontends
|
|
23
|
+
Micro-frontends with any framework, with no build config on the host. React, Next.js, Vue, Nuxt, Angular, Svelte and more on one page.
|
|
24
24
|
|
|
25
|
-
**
|
|
25
|
+
**What it is:** a micro-frontend is a part of the page that one team builds and ships on its own, like the cart, the search or the account area. vitral puts those parts together on one page, even when each one uses a different framework.
|
|
26
26
|
|
|
27
|
-
**
|
|
27
|
+
**How it works:** each team builds its part (a *remote*) with `vite build` and deploys it to a CDN. The main page (the *host*) gets the URL of each remote and mounts them in the browser.
|
|
28
28
|
|
|
29
|
-
**
|
|
29
|
+
**Why use it:**
|
|
30
30
|
|
|
31
|
-
- **Zero
|
|
32
|
-
- **
|
|
33
|
-
- **
|
|
34
|
-
- **CSS
|
|
35
|
-
- **
|
|
36
|
-
- **
|
|
31
|
+
- **Zero host config.** No build plugin: just `configure({ remotes })` with the URL of each remote.
|
|
32
|
+
- **Any framework.** React, Next, Vue, Nuxt, Angular, Svelte, Solid, Preact, Lit and plain JS on the same page. No React version to agree on between teams.
|
|
33
|
+
- **Independent deploys.** Each team ships when it wants. The host picks up the new version without a new build.
|
|
34
|
+
- **Isolated CSS and errors.** A remote's CSS does not change the rest of the page. A remote that is down shows its own error, and the rest keeps working.
|
|
35
|
+
- **Secure.** The JS only runs if it comes from an allowed origin and its SHA-384 hash matches.
|
|
36
|
+
- **Small and fast.** 5.1 kB of host code. Opens the page in half the time of Module Federation and switches areas 4.5 times faster than Next.js Multi-Zones.
|
|
37
37
|
|
|
38
|
-
|
|
38
|
+
<p align="center">
|
|
39
|
+
<img src="https://raw.githubusercontent.com/joaogabriel15/vitral/main/docs/public/marca/demo-en.gif" width="720" alt="A plain HTML shop with two remotes: the catalog in Vue and the cart in React. Clicking Add in the catalog updates the cart. A third remote, Reviews, is offline and shows only its own error message, while the rest of the page keeps working.">
|
|
40
|
+
</p>
|
|
41
|
+
|
|
42
|
+
**When to use it:** when several teams work on the same site and each wants to ship at its own pace. With one team and one app, a regular bundle is simpler.
|
|
39
43
|
|
|
40
44
|
```bash
|
|
41
45
|
npm install vitral
|
|
@@ -43,70 +47,81 @@ npm install vitral
|
|
|
43
47
|
|
|
44
48
|
<p align="center">
|
|
45
49
|
<picture>
|
|
46
|
-
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/joaogabriel15/vitral/main/docs/public/marca/como-funciona-escuro.png">
|
|
47
|
-
<img src="https://raw.githubusercontent.com/joaogabriel15/vitral/main/docs/public/marca/como-funciona.png" width="900" alt="
|
|
50
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/joaogabriel15/vitral/main/docs/public/marca/como-funciona-escuro-en.png">
|
|
51
|
+
<img src="https://raw.githubusercontent.com/joaogabriel15/vitral/main/docs/public/marca/como-funciona-en.png" width="900" alt="Three teams (React, Vue, Angular) each publish a vitral.json to a CDN. The host reads the URLs with configure and mounts the three remotes on the same page.">
|
|
48
52
|
</picture>
|
|
49
53
|
</p>
|
|
50
54
|
|
|
51
|
-
##
|
|
55
|
+
## Comparison
|
|
52
56
|
|
|
53
57
|
| | Module Federation | single-spa | Next.js Multi-Zones | vitral |
|
|
54
58
|
|---|---|---|---|---|
|
|
55
|
-
|
|
|
56
|
-
| Frameworks |
|
|
57
|
-
|
|
|
58
|
-
|
|
|
59
|
-
|
|
|
60
|
-
| Remote
|
|
61
|
-
|
|
|
59
|
+
| Host config | Build plugin, matched with each remote | Root config and import map | One Next app per zone, plus rewrites | None. Just `configure()` |
|
|
60
|
+
| Frameworks | Agree on versions in `shared` | One adapter and lifecycle per framework | Next only | Any, no versions to agree on |
|
|
61
|
+
| Splits the page into | Parts | Apps per route | Routes (each zone is a page) | Parts or routes |
|
|
62
|
+
| Switching areas | No reload | No reload | Reloads the page and downloads Next and React again | No reload |
|
|
63
|
+
| CSS isolation | None | None | Per page | Automatic scope or Shadow DOM |
|
|
64
|
+
| Remote is down | An unhandled error takes the page down | The error screen is up to you | The whole zone is down | Only that remote shows an error, with `retry` |
|
|
65
|
+
| Host code (brotli) | 19.4 kB | 5.8 kB | Next runtime in each zone | 5.1 kB |
|
|
66
|
+
|
|
67
|
+
**Other tools:**
|
|
62
68
|
|
|
63
|
-
|
|
69
|
+
| | qiankun | micro-app | wujie | Native import maps | vitral |
|
|
70
|
+
|---|---|---|---|---|---|
|
|
71
|
+
| The remote publishes | HTML page and UMD build | HTML page | HTML page | ES modules | `vitral.json` and an ES module |
|
|
72
|
+
| Host setup | `registerMicroApps` and `start` | `microApp.start()` and `<micro-app>` | `startApp` or the wujie component | `<script type="importmap">` | `configure({ remotes })` |
|
|
73
|
+
| JS isolation | `Proxy` sandbox | `Proxy` sandbox or iframe | iframe: the JS runs in an iframe and the UI in the host | None | None by default. `isolate="iframe"` isolates, without passing functions in props |
|
|
74
|
+
| CSS isolation | Shadow DOM or prefix, if turned on | Prefix by default, Shadow DOM optional | Shadow DOM | None | Automatic scope or Shadow DOM |
|
|
75
|
+
| Mount, update, errors | `bootstrap`, `mount`, `unmount` | `<micro-app>` element | Component or `startApp` | You write it | `<Remote>` with `fallback`, `error` and `retry` |
|
|
76
|
+
| Repeated dependencies | Each app downloads its own | Each app downloads its own | Each app downloads its own | One URL per package in the import map | Each remote ships its own. A single copy with `dedupe` |
|
|
64
77
|
|
|
65
|
-
|
|
78
|
+
qiankun, micro-app and wujie isolate the JS of existing apps without changing them: wujie with a real iframe, qiankun and micro-app with a `Proxy`. vitral runs the remote's JS on the page itself, with the page's DOM and props of any type, and only isolates with `isolate="iframe"`.
|
|
66
79
|
|
|
67
|
-
|
|
80
|
+
## Speed
|
|
81
|
+
|
|
82
|
+
Measured in Chromium on a slow mobile network (Slow 4G). Median of 7 visits. Lower is better.
|
|
83
|
+
|
|
84
|
+
**Against Module Federation**, with React shared between remotes:
|
|
68
85
|
|
|
69
86
|
| | vitral | Module Federation |
|
|
70
87
|
|---|--:|--:|
|
|
71
|
-
|
|
|
72
|
-
|
|
|
73
|
-
|
|
|
88
|
+
| Open the page with 1 remote | **1.1 s** | 2.6 s |
|
|
89
|
+
| Open the page with 8 remotes | **2.1 s** | 4.5 s |
|
|
90
|
+
| Downloaded with 8 remotes | **153 kB** | 409 kB |
|
|
74
91
|
|
|
75
|
-
**
|
|
92
|
+
**Against Next.js Multi-Zones**, with the app split into two areas:
|
|
76
93
|
|
|
77
94
|
| | vitral | Multi-Zones |
|
|
78
95
|
|---|--:|--:|
|
|
79
|
-
|
|
|
80
|
-
|
|
|
81
|
-
|
|
|
82
|
-
|
|
83
|
-
[Como foi medido](https://joaogabriel15.github.io/vitral/aprender/benchmark): versões, máquina e o script para rodar de novo.
|
|
96
|
+
| Open the first area | **0.7 s** | 1.0 s |
|
|
97
|
+
| Switch areas | **0.2 s** | 0.8 s |
|
|
98
|
+
| Downloaded to open both areas | **83 kB** | 229 kB |
|
|
84
99
|
|
|
85
|
-
|
|
100
|
+
The minimal host code is 5.1 kB with brotli. [How it was measured](https://joaogabriel15.github.io/vitral/en/aprender/benchmark): versions, machine and the script to run it again.
|
|
86
101
|
|
|
87
|
-
##
|
|
102
|
+
## Quick start
|
|
88
103
|
|
|
89
|
-
|
|
104
|
+
Example: a React shop shows the cart, built by another team. Both sides below have the same files, in the same order.
|
|
90
105
|
|
|
91
|
-
###
|
|
106
|
+
### Today, with Module Federation
|
|
92
107
|
|
|
93
108
|
```jsx
|
|
94
|
-
//
|
|
95
|
-
export default function
|
|
96
|
-
return <p>
|
|
109
|
+
// cart/src/Cart.jsx
|
|
110
|
+
export default function Cart({ userId }) {
|
|
111
|
+
return <p>Cart for user {userId}</p>
|
|
97
112
|
}
|
|
98
113
|
```
|
|
99
114
|
|
|
100
115
|
```js
|
|
101
|
-
//
|
|
116
|
+
// cart/webpack.config.js
|
|
102
117
|
const { ModuleFederationPlugin } = require('webpack').container
|
|
103
118
|
|
|
104
119
|
module.exports = {
|
|
105
120
|
plugins: [
|
|
106
121
|
new ModuleFederationPlugin({
|
|
107
|
-
name: '
|
|
122
|
+
name: 'cart',
|
|
108
123
|
filename: 'remoteEntry.js',
|
|
109
|
-
exposes: { './
|
|
124
|
+
exposes: { './Cart': './src/Cart.jsx' },
|
|
110
125
|
shared: { react: { singleton: true }, 'react-dom': { singleton: true } },
|
|
111
126
|
}),
|
|
112
127
|
],
|
|
@@ -114,14 +129,14 @@ module.exports = {
|
|
|
114
129
|
```
|
|
115
130
|
|
|
116
131
|
```js
|
|
117
|
-
//
|
|
132
|
+
// shop/webpack.config.js
|
|
118
133
|
const { ModuleFederationPlugin } = require('webpack').container
|
|
119
134
|
|
|
120
135
|
module.exports = {
|
|
121
136
|
plugins: [
|
|
122
137
|
new ModuleFederationPlugin({
|
|
123
|
-
name: '
|
|
124
|
-
remotes: {
|
|
138
|
+
name: 'shop',
|
|
139
|
+
remotes: { cart: 'cart@https://cdn.example.com/cart/remoteEntry.js' },
|
|
125
140
|
shared: { react: { singleton: true }, 'react-dom': { singleton: true } },
|
|
126
141
|
}),
|
|
127
142
|
],
|
|
@@ -129,196 +144,196 @@ module.exports = {
|
|
|
129
144
|
```
|
|
130
145
|
|
|
131
146
|
```jsx
|
|
132
|
-
//
|
|
147
|
+
// shop/src/App.jsx
|
|
133
148
|
import { lazy, Suspense } from 'react'
|
|
134
149
|
|
|
135
|
-
const
|
|
150
|
+
const Cart = lazy(() => import('cart/Cart'))
|
|
136
151
|
|
|
137
152
|
export function App() {
|
|
138
153
|
return (
|
|
139
|
-
<Suspense fallback={<p>
|
|
140
|
-
<
|
|
154
|
+
<Suspense fallback={<p>Loading…</p>}>
|
|
155
|
+
<Cart userId={42} />
|
|
141
156
|
</Suspense>
|
|
142
157
|
)
|
|
143
158
|
}
|
|
144
159
|
```
|
|
145
160
|
|
|
146
|
-
###
|
|
161
|
+
### The same app with vitral
|
|
147
162
|
|
|
148
163
|
```jsx
|
|
149
|
-
//
|
|
150
|
-
export default function
|
|
151
|
-
return <p>
|
|
164
|
+
// cart/src/Cart.jsx (same)
|
|
165
|
+
export default function Cart({ userId }) {
|
|
166
|
+
return <p>Cart for user {userId}</p>
|
|
152
167
|
}
|
|
153
168
|
```
|
|
154
169
|
|
|
155
170
|
```js
|
|
156
|
-
//
|
|
171
|
+
// cart/vite.config.js (instead of webpack.config.js)
|
|
157
172
|
import react from '@vitejs/plugin-react'
|
|
158
173
|
import vitral from 'vitral/vite'
|
|
159
174
|
|
|
160
175
|
export default {
|
|
161
176
|
plugins: [
|
|
162
177
|
react(),
|
|
163
|
-
vitral({ name: '
|
|
178
|
+
vitral({ name: 'cart', entry: 'src/Cart.jsx', dedupe: ['react'] }),
|
|
164
179
|
],
|
|
165
180
|
}
|
|
166
181
|
```
|
|
167
182
|
|
|
168
183
|
```js
|
|
169
|
-
//
|
|
184
|
+
// shop/webpack.config.js (without ModuleFederationPlugin)
|
|
170
185
|
module.exports = {
|
|
171
186
|
plugins: [],
|
|
172
187
|
}
|
|
173
188
|
```
|
|
174
189
|
|
|
175
190
|
```jsx
|
|
176
|
-
//
|
|
191
|
+
// shop/src/App.jsx
|
|
177
192
|
import { configure } from 'vitral'
|
|
178
193
|
import { Remote } from 'vitral/react'
|
|
179
194
|
|
|
180
|
-
configure({ remotes: {
|
|
195
|
+
configure({ remotes: { cart: 'https://cdn.example.com/cart/vitral.json' } })
|
|
181
196
|
|
|
182
197
|
export function App() {
|
|
183
|
-
return <Remote name="
|
|
198
|
+
return <Remote name="cart" props={{ userId: 42 }} fallback={<p>Loading…</p>} />
|
|
184
199
|
}
|
|
185
200
|
```
|
|
186
201
|
|
|
187
|
-
`vite build`
|
|
202
|
+
`vite build` in the cart outputs the JS, the CSS and `vitral.json`. Publish the `dist` folder to any CDN. To generate a ready shop and cart: `npm create vitral@latest`.
|
|
188
203
|
|
|
189
|
-
###
|
|
204
|
+
### What changes
|
|
190
205
|
|
|
191
206
|
| | Module Federation | vitral |
|
|
192
207
|
|---|---|---|
|
|
193
|
-
|
|
|
194
|
-
|
|
|
195
|
-
| Framework |
|
|
208
|
+
| Shop build | Plugin with `remotes` and `shared` | No plugin |
|
|
209
|
+
| React version | Agreed between teams (`singleton`) | The cart uses the shop React when the version fits (`dedupe`), otherwise its own |
|
|
210
|
+
| Framework | The same on both sides | Any. A React shop can show a Vue cart |
|
|
196
211
|
|
|
197
|
-
|
|
212
|
+
On any HTML page, no build:
|
|
198
213
|
|
|
199
214
|
```html
|
|
200
215
|
<script type="module" src="https://cdn.jsdelivr.net/npm/vitral/dist/auto.js"></script>
|
|
201
|
-
<vitral-remote src="https://cdn.
|
|
216
|
+
<vitral-remote src="https://cdn.example.com/cart/vitral.json" props='{"userId": 42}'></vitral-remote>
|
|
202
217
|
```
|
|
203
218
|
|
|
204
|
-
|
|
219
|
+
Full guide: [Migrate from Module Federation](https://joaogabriel15.github.io/vitral/en/migracao/module-federation).
|
|
205
220
|
|
|
206
221
|
## Frameworks
|
|
207
222
|
|
|
208
223
|
| Framework | Remote | Host | Import |
|
|
209
224
|
|---|---|---|---|
|
|
210
225
|
| React 18/19 | `reactRemote(App)` | `<Remote>` | `vitral/react` |
|
|
211
|
-
| Next.js (App
|
|
226
|
+
| Next.js (App and Pages Router) | `reactRemote(App)` | `<Remote>` | `vitral/react` |
|
|
212
227
|
| Vue 3 | `vueRemote(App, { setup })` | `<VitralRemote>` | `vitral/vue` |
|
|
213
228
|
| Nuxt 3/4 | `vueRemote(App, { setup })` | `<VitralRemote>` | `vitral/vue` |
|
|
214
229
|
| Angular 17+ | `angularRemote(Component, { providers })` | `<vitral-remote>` + `provideVitral()` | `vitral/angular` |
|
|
215
230
|
| Svelte 5 | `svelteRemote(App)` | `use:remote` | `vitral/svelte` |
|
|
216
231
|
| Solid | `solidRemote(App)` | `<Remote>` | `vitral/solid` |
|
|
217
232
|
| Preact | `preactRemote(App)` | `<Remote>` | `vitral/preact` |
|
|
218
|
-
| Lit
|
|
219
|
-
| JS
|
|
233
|
+
| Lit and Web Components | `elementRemote('my-widget')` | `<vitral-remote>` | `vitral/element` |
|
|
234
|
+
| Plain JS and TypeScript | `component({ render })` | `<vitral-remote>` | `vitral` |
|
|
220
235
|
|
|
221
|
-
Host
|
|
236
|
+
Host and remote do not need to use the same framework.
|
|
222
237
|
|
|
223
|
-
## Next.js
|
|
238
|
+
## Next.js as host
|
|
224
239
|
|
|
225
|
-
|
|
240
|
+
Example: a Next.js shop with a "My account" area, built by another team. Both sides below have the same files, in the same order. With vitral, the shop gets one new file at the end.
|
|
226
241
|
|
|
227
242
|
<p align="center">
|
|
228
243
|
<picture>
|
|
229
|
-
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/joaogabriel15/vitral/main/docs/public/marca/multizonas-escuro.png">
|
|
230
|
-
<img src="https://raw.githubusercontent.com/joaogabriel15/vitral/main/docs/public/marca/multizonas.png" width="900" alt="
|
|
244
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/joaogabriel15/vitral/main/docs/public/marca/multizonas-escuro-en.png">
|
|
245
|
+
<img src="https://raw.githubusercontent.com/joaogabriel15/vitral/main/docs/public/marca/multizonas-en.png" width="900" alt="Left, Multi-Zones: two Next apps, rewrites, and the page reloads when switching areas (0.8 s). Right, vitral: one Next app with withVitral, the account is a remote inside the layout and switching does not reload (0.2 s).">
|
|
231
246
|
</picture>
|
|
232
247
|
</p>
|
|
233
248
|
|
|
234
|
-
###
|
|
249
|
+
### Today, with Multi-Zones
|
|
235
250
|
|
|
236
251
|
```
|
|
237
|
-
|
|
238
|
-
|
|
252
|
+
shop/ main Next app
|
|
253
|
+
account/ second Next app (the zone)
|
|
239
254
|
```
|
|
240
255
|
|
|
241
256
|
```tsx
|
|
242
|
-
//
|
|
243
|
-
export default function
|
|
244
|
-
return <h1>
|
|
257
|
+
// account/pages/index.tsx
|
|
258
|
+
export default function Account() {
|
|
259
|
+
return <h1>My account</h1>
|
|
245
260
|
}
|
|
246
261
|
```
|
|
247
262
|
|
|
248
263
|
```js
|
|
249
|
-
//
|
|
264
|
+
// account/next.config.js
|
|
250
265
|
module.exports = {
|
|
251
|
-
basePath: '/
|
|
252
|
-
assetPrefix: '/
|
|
266
|
+
basePath: '/account',
|
|
267
|
+
assetPrefix: '/account-static',
|
|
253
268
|
}
|
|
254
269
|
```
|
|
255
270
|
|
|
256
271
|
```js
|
|
257
|
-
//
|
|
272
|
+
// shop/next.config.js
|
|
258
273
|
module.exports = {
|
|
259
274
|
async rewrites() {
|
|
260
275
|
return [
|
|
261
|
-
{ source: '/
|
|
262
|
-
{ source: '/
|
|
263
|
-
{ source: '/
|
|
276
|
+
{ source: '/account', destination: `${process.env.ACCOUNT_URL}/account` },
|
|
277
|
+
{ source: '/account/:path+', destination: `${process.env.ACCOUNT_URL}/account/:path+` },
|
|
278
|
+
{ source: '/account-static/:path+', destination: `${process.env.ACCOUNT_URL}/account-static/:path+` },
|
|
264
279
|
]
|
|
265
280
|
},
|
|
266
281
|
}
|
|
267
282
|
```
|
|
268
283
|
|
|
269
284
|
```tsx
|
|
270
|
-
//
|
|
285
|
+
// shop/pages/_app.tsx
|
|
271
286
|
export default function App({ Component, pageProps }) {
|
|
272
287
|
return <Component {...pageProps} />
|
|
273
288
|
}
|
|
274
289
|
```
|
|
275
290
|
|
|
276
291
|
```tsx
|
|
277
|
-
//
|
|
278
|
-
// <a>,
|
|
279
|
-
<a href="/
|
|
292
|
+
// shop/components/Menu.tsx
|
|
293
|
+
// <a>, not <Link>: the page reloads and downloads Next and React again.
|
|
294
|
+
<a href="/account">My account</a>
|
|
280
295
|
```
|
|
281
296
|
|
|
282
|
-
###
|
|
297
|
+
### The same app with vitral
|
|
283
298
|
|
|
284
299
|
```
|
|
285
|
-
|
|
286
|
-
|
|
300
|
+
shop/ Next app (the host)
|
|
301
|
+
account/ the same code, built with Vite (the remote)
|
|
287
302
|
```
|
|
288
303
|
|
|
289
304
|
```tsx
|
|
290
|
-
//
|
|
291
|
-
export default function
|
|
292
|
-
return <h1>
|
|
305
|
+
// account/pages/index.tsx (same)
|
|
306
|
+
export default function Account() {
|
|
307
|
+
return <h1>My account</h1>
|
|
293
308
|
}
|
|
294
309
|
```
|
|
295
310
|
|
|
296
311
|
```js
|
|
297
|
-
//
|
|
312
|
+
// account/vite.config.js (instead of next.config.js)
|
|
298
313
|
import react from '@vitejs/plugin-react'
|
|
299
314
|
import vitral from 'vitral/vite'
|
|
300
315
|
|
|
301
316
|
export default {
|
|
302
317
|
plugins: [
|
|
303
318
|
react(),
|
|
304
|
-
vitral({ name: '
|
|
319
|
+
vitral({ name: 'account', entry: 'pages/index.tsx', next: { basePath: '/account' }, dedupe: ['react'] }),
|
|
305
320
|
],
|
|
306
321
|
}
|
|
307
322
|
```
|
|
308
323
|
|
|
309
324
|
```js
|
|
310
|
-
//
|
|
325
|
+
// shop/next.config.js (withVitral instead of rewrites)
|
|
311
326
|
const { withVitral } = require('vitral/next-config')
|
|
312
327
|
|
|
313
328
|
module.exports = withVitral({}, {
|
|
314
329
|
remotes: {
|
|
315
|
-
|
|
330
|
+
account: { url: 'https://cdn.example.com/account/vitral.json', basePath: '/account' },
|
|
316
331
|
},
|
|
317
332
|
})
|
|
318
333
|
```
|
|
319
334
|
|
|
320
335
|
```tsx
|
|
321
|
-
//
|
|
336
|
+
// shop/pages/_app.tsx (plus <VitralNext />)
|
|
322
337
|
import { VitralNext } from 'vitral/next-host'
|
|
323
338
|
|
|
324
339
|
export default function App({ Component, pageProps }) {
|
|
@@ -327,210 +342,210 @@ export default function App({ Component, pageProps }) {
|
|
|
327
342
|
```
|
|
328
343
|
|
|
329
344
|
```tsx
|
|
330
|
-
//
|
|
331
|
-
// <Link>:
|
|
332
|
-
<Link href="/
|
|
345
|
+
// shop/components/Menu.tsx
|
|
346
|
+
// <Link>: switching does not reload, and React is not downloaded again.
|
|
347
|
+
<Link href="/account">My account</Link>
|
|
333
348
|
```
|
|
334
349
|
|
|
335
350
|
```tsx
|
|
336
|
-
//
|
|
351
|
+
// shop/pages/account/[[...slug]].tsx (new file: the shop page that shows the account)
|
|
337
352
|
import { NextRemote } from 'vitral/next-host'
|
|
338
353
|
|
|
339
|
-
export default function
|
|
340
|
-
return <NextRemote name="
|
|
354
|
+
export default function Account() {
|
|
355
|
+
return <NextRemote name="account" fallback={<p>Loading…</p>} />
|
|
341
356
|
}
|
|
342
357
|
```
|
|
343
358
|
|
|
344
|
-
|
|
359
|
+
With `next: { basePath }`, the account code can keep using `next/link` and `useRouter`.
|
|
345
360
|
|
|
346
|
-
###
|
|
361
|
+
### What changes
|
|
347
362
|
|
|
348
363
|
| | Multi-Zones | vitral |
|
|
349
364
|
|---|---|---|
|
|
350
|
-
|
|
|
351
|
-
|
|
|
352
|
-
|
|
|
353
|
-
| React
|
|
354
|
-
|
|
|
365
|
+
| Next apps | One per area | Only the shop |
|
|
366
|
+
| Config | `basePath` and `assetPrefix` in the zone, `rewrites` in the shop | Plugin in the account, `withVitral` in the shop |
|
|
367
|
+
| Switching areas | Reloads the page (0.8 s in the benchmark) | No reload (0.2 s) |
|
|
368
|
+
| React and Next | Downloaded again in each area | One copy for the whole page |
|
|
369
|
+
| Shop layout | Each zone repeats its own | The account sits inside the shop layout |
|
|
355
370
|
|
|
356
|
-
|
|
371
|
+
Full guide, with per-route SSR and prefetch: [Migrate from Next.js Multi-Zones](https://joaogabriel15.github.io/vitral/en/migracao/multi-zones). With the App Router, the host uses `<Remote>` from `vitral/react` in a `'use client'` component: see [Next.js](https://joaogabriel15.github.io/vitral/en/frameworks/next#host-with-app-router).
|
|
357
372
|
|
|
358
|
-
## Nuxt
|
|
373
|
+
## Nuxt as host
|
|
359
374
|
|
|
360
|
-
|
|
375
|
+
Example: a Nuxt shop with a "Catalog" area, built by another team. Both sides below have the same files, in the same order. With vitral, the shop gets two new files at the end.
|
|
361
376
|
|
|
362
|
-
###
|
|
377
|
+
### Today, with two Nuxt apps
|
|
363
378
|
|
|
364
379
|
```
|
|
365
|
-
|
|
366
|
-
|
|
380
|
+
shop/ main Nuxt app
|
|
381
|
+
catalog/ second Nuxt app
|
|
367
382
|
```
|
|
368
383
|
|
|
369
384
|
```vue
|
|
370
|
-
<!--
|
|
385
|
+
<!-- catalog/app/pages/index.vue -->
|
|
371
386
|
<template>
|
|
372
|
-
<h1>
|
|
387
|
+
<h1>Catalog</h1>
|
|
373
388
|
</template>
|
|
374
389
|
```
|
|
375
390
|
|
|
376
391
|
```ts
|
|
377
|
-
//
|
|
392
|
+
// catalog/nuxt.config.ts
|
|
378
393
|
export default defineNuxtConfig({
|
|
379
|
-
app: { baseURL: '/
|
|
394
|
+
app: { baseURL: '/catalog/' },
|
|
380
395
|
})
|
|
381
396
|
```
|
|
382
397
|
|
|
383
398
|
```ts
|
|
384
|
-
//
|
|
399
|
+
// shop/nuxt.config.ts
|
|
385
400
|
export default defineNuxtConfig({
|
|
386
401
|
routeRules: {
|
|
387
|
-
'/
|
|
402
|
+
'/catalog/**': { proxy: `${process.env.CATALOG_URL}/catalog/**` },
|
|
388
403
|
},
|
|
389
404
|
})
|
|
390
405
|
```
|
|
391
406
|
|
|
392
407
|
```vue
|
|
393
|
-
<!--
|
|
394
|
-
<!-- <a>,
|
|
395
|
-
<a href="/
|
|
408
|
+
<!-- shop/app/components/Menu.vue -->
|
|
409
|
+
<!-- <a>, not <NuxtLink>: the page reloads and downloads Nuxt and Vue again. -->
|
|
410
|
+
<a href="/catalog">Catalog</a>
|
|
396
411
|
```
|
|
397
412
|
|
|
398
|
-
###
|
|
413
|
+
### The same app with vitral
|
|
399
414
|
|
|
400
415
|
```
|
|
401
|
-
|
|
402
|
-
|
|
416
|
+
shop/ Nuxt app (the host)
|
|
417
|
+
catalog/ the same component, built with Vite (the remote)
|
|
403
418
|
```
|
|
404
419
|
|
|
405
420
|
```vue
|
|
406
|
-
<!--
|
|
421
|
+
<!-- catalog/app/pages/index.vue (same) -->
|
|
407
422
|
<template>
|
|
408
|
-
<h1>
|
|
423
|
+
<h1>Catalog</h1>
|
|
409
424
|
</template>
|
|
410
425
|
```
|
|
411
426
|
|
|
412
427
|
```js
|
|
413
|
-
//
|
|
428
|
+
// catalog/vite.config.js (instead of nuxt.config.ts)
|
|
414
429
|
import vue from '@vitejs/plugin-vue'
|
|
415
430
|
import vitral from 'vitral/vite'
|
|
416
431
|
|
|
417
432
|
export default {
|
|
418
433
|
plugins: [
|
|
419
434
|
vue(),
|
|
420
|
-
vitral({ name: '
|
|
435
|
+
vitral({ name: 'catalog', entry: 'app/pages/index.vue', dedupe: ['vue'] }),
|
|
421
436
|
],
|
|
422
437
|
}
|
|
423
438
|
```
|
|
424
439
|
|
|
425
440
|
```ts
|
|
426
|
-
//
|
|
441
|
+
// shop/nuxt.config.ts (without the proxy)
|
|
427
442
|
export default defineNuxtConfig({})
|
|
428
443
|
```
|
|
429
444
|
|
|
430
445
|
```vue
|
|
431
|
-
<!--
|
|
432
|
-
<!-- <NuxtLink>:
|
|
433
|
-
<NuxtLink to="/
|
|
446
|
+
<!-- shop/app/components/Menu.vue -->
|
|
447
|
+
<!-- <NuxtLink>: switching does not reload. -->
|
|
448
|
+
<NuxtLink to="/catalog">Catalog</NuxtLink>
|
|
434
449
|
```
|
|
435
450
|
|
|
436
451
|
```ts
|
|
437
|
-
//
|
|
452
|
+
// shop/app/plugins/vitral.client.ts (new file: registers the catalog)
|
|
438
453
|
import * as Vue from 'vue'
|
|
439
454
|
import { configure } from 'vitral'
|
|
440
455
|
|
|
441
456
|
export default defineNuxtPlugin(() => {
|
|
442
457
|
configure({
|
|
443
|
-
remotes: {
|
|
444
|
-
dedupe: { vue: { version: Vue.version, modules: { vue: Vue } } }, //
|
|
458
|
+
remotes: { catalog: 'https://cdn.example.com/catalog/vitral.json' },
|
|
459
|
+
dedupe: { vue: { version: Vue.version, modules: { vue: Vue } } }, // the catalog uses this Vue
|
|
445
460
|
})
|
|
446
461
|
})
|
|
447
462
|
```
|
|
448
463
|
|
|
449
464
|
```vue
|
|
450
|
-
<!--
|
|
465
|
+
<!-- shop/app/pages/catalog/[...slug].vue (new file: the shop page that shows the catalog) -->
|
|
451
466
|
<script setup lang="ts">
|
|
452
467
|
import { VitralRemote } from 'vitral/vue'
|
|
453
468
|
</script>
|
|
454
469
|
|
|
455
470
|
<template>
|
|
456
|
-
<VitralRemote name="
|
|
457
|
-
<template #fallback><p>
|
|
471
|
+
<VitralRemote name="catalog">
|
|
472
|
+
<template #fallback><p>Loading…</p></template>
|
|
458
473
|
</VitralRemote>
|
|
459
474
|
</template>
|
|
460
475
|
```
|
|
461
476
|
|
|
462
|
-
|
|
477
|
+
The server renders the `fallback` and the catalog mounts in the browser. No `<ClientOnly>` needed.
|
|
463
478
|
|
|
464
|
-
###
|
|
479
|
+
### What changes
|
|
465
480
|
|
|
466
|
-
| |
|
|
481
|
+
| | Two Nuxt apps | vitral |
|
|
467
482
|
|---|---|---|
|
|
468
|
-
|
|
|
469
|
-
|
|
|
470
|
-
|
|
|
471
|
-
| Vue
|
|
472
|
-
|
|
|
483
|
+
| Nuxt apps | One per area | Only the shop |
|
|
484
|
+
| Config | `baseURL` in the catalog, `proxy` in the shop | Plugin in the catalog, `configure()` in the shop |
|
|
485
|
+
| Switching areas | Reloads the page | No reload |
|
|
486
|
+
| Vue and Nuxt | Downloaded again in each area | One copy of Vue for the whole page |
|
|
487
|
+
| Shop layout | Each app repeats its own | The catalog sits inside the shop layout |
|
|
473
488
|
|
|
474
|
-
##
|
|
489
|
+
## What else comes with it
|
|
475
490
|
|
|
476
|
-
**
|
|
491
|
+
**Shared dependencies.** With `vitral({ dedupe: ['react'] })`, the remote uses the React already on the page instead of downloading another copy.
|
|
477
492
|
|
|
478
493
|
<p align="center">
|
|
479
494
|
<picture>
|
|
480
|
-
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/joaogabriel15/vitral/main/docs/public/marca/dedupe-escuro.png">
|
|
481
|
-
<img src="https://raw.githubusercontent.com/joaogabriel15/vitral/main/docs/public/marca/dedupe.png" width="900" alt="
|
|
495
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/joaogabriel15/vitral/main/docs/public/marca/dedupe-escuro-en.png">
|
|
496
|
+
<img src="https://raw.githubusercontent.com/joaogabriel15/vitral/main/docs/public/marca/dedupe-en.png" width="900" alt="Without dedupe, each remote downloads its own React. With dedupe, remotes use the React already on the page when the version fits; one that doesn't fit loads its own.">
|
|
482
497
|
</picture>
|
|
483
498
|
</p>
|
|
484
499
|
|
|
485
|
-
**
|
|
500
|
+
**Communication between remotes.** `events` sends messages between remotes, and `provide` and `shared` hold common state, like the signed-in user.
|
|
486
501
|
|
|
487
502
|
<p align="center">
|
|
488
503
|
<picture>
|
|
489
|
-
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/joaogabriel15/vitral/main/docs/public/marca/comunicacao-escuro.png">
|
|
490
|
-
<img src="https://raw.githubusercontent.com/joaogabriel15/vitral/main/docs/public/marca/comunicacao.png" width="900" alt="
|
|
504
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/joaogabriel15/vitral/main/docs/public/marca/comunicacao-escuro-en.png">
|
|
505
|
+
<img src="https://raw.githubusercontent.com/joaogabriel15/vitral/main/docs/public/marca/comunicacao-en.png" width="900" alt="Three remotes in React, Vue and Angular. The cart emits an event, the search receives it on the same bus, and the account reads the user the host created with provide.">
|
|
491
506
|
</picture>
|
|
492
507
|
</p>
|
|
493
508
|
|
|
494
|
-
**
|
|
509
|
+
**Security.** The JS only runs if it comes from an allowed origin and, with `integrity`, if the hash matches.
|
|
495
510
|
|
|
496
511
|
<p align="center">
|
|
497
512
|
<picture>
|
|
498
|
-
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/joaogabriel15/vitral/main/docs/public/marca/seguranca-escuro.png">
|
|
499
|
-
<img src="https://raw.githubusercontent.com/joaogabriel15/vitral/main/docs/public/marca/seguranca.png" width="900" alt="
|
|
513
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/joaogabriel15/vitral/main/docs/public/marca/seguranca-escuro-en.png">
|
|
514
|
+
<img src="https://raw.githubusercontent.com/joaogabriel15/vitral/main/docs/public/marca/seguranca-en.png" width="900" alt="The host sets allowedOrigins and integrity. Before running, the library checks the origin and the SHA-384. If either fails, nothing runs and the error shows in place of the remote.">
|
|
500
515
|
</picture>
|
|
501
516
|
</p>
|
|
502
517
|
|
|
503
|
-
|
|
518
|
+
Also:
|
|
504
519
|
|
|
505
|
-
- **CSS
|
|
506
|
-
- **
|
|
507
|
-
- **
|
|
508
|
-
- **
|
|
509
|
-
- **
|
|
510
|
-
- **
|
|
520
|
+
- **CSS and Tailwind:** each remote's CSS only applies inside it, or use Shadow DOM with `isolate="shadow"`.
|
|
521
|
+
- **Loading:** `loading="lazy"`, `prefetch="hover"` and `keepAlive` to open and come back faster.
|
|
522
|
+
- **Errors:** every error has a code and a page with the cause and the fix, and `retry` mounts only that remote again.
|
|
523
|
+
- **Typed props:** `npx vitral types` makes a wrong prop fail to compile on the host.
|
|
524
|
+
- **Routes, SSR and deploys:** app shell per route, the remote's HTML from the server, canary and rollback.
|
|
525
|
+
- **Tests:** `mockRemote` and `failingRemote` test the host without the network.
|
|
511
526
|
|
|
512
|
-
##
|
|
527
|
+
## Local and Docker
|
|
513
528
|
|
|
514
|
-
|
|
529
|
+
Each remote runs its own `vite dev` on a port, and the host points at those ports:
|
|
515
530
|
|
|
516
531
|
```json
|
|
517
|
-
//
|
|
532
|
+
// shop/public/remotes.json
|
|
518
533
|
{
|
|
519
|
-
"
|
|
520
|
-
"
|
|
534
|
+
"cart": "http://localhost:5174/vitral.json",
|
|
535
|
+
"search": "http://localhost:5175/vitral.json"
|
|
521
536
|
}
|
|
522
537
|
```
|
|
523
538
|
|
|
524
539
|
```js
|
|
525
|
-
//
|
|
540
|
+
// shop/src/main.jsx
|
|
526
541
|
configure({ remotes: '/remotes.json' })
|
|
527
542
|
```
|
|
528
543
|
|
|
529
|
-
|
|
544
|
+
Editing a remote updates the host without a page reload. With Docker, each remote is an nginx image and the host reads its remote list from an environment variable, so one image works in every environment. Full example: [`examples/docker`](https://github.com/joaogabriel15/vitral/tree/main/examples/docker).
|
|
530
545
|
|
|
531
546
|
## Links
|
|
532
547
|
|
|
533
|
-
- [
|
|
534
|
-
- [
|
|
535
|
-
- [
|
|
536
|
-
-
|
|
548
|
+
- [Docs](https://joaogabriel15.github.io/vitral/en/): guides, reference and error pages. Also available in Portuguese.
|
|
549
|
+
- [Examples](https://github.com/joaogabriel15/vitral/tree/main/examples): the same remote in 8 frameworks and 9 hosts.
|
|
550
|
+
- [Contributing](https://github.com/joaogabriel15/vitral/blob/main/CONTRIBUTING.md)
|
|
551
|
+
- [MIT](https://github.com/joaogabriel15/vitral/blob/main/LICENSE) license. Made by [Pacheco Codes](https://pacheco.dev.br/).
|
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/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,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "vitral",
|
|
3
|
-
"version": "0.13.
|
|
4
|
-
"description": "Micro-frontends
|
|
3
|
+
"version": "0.13.2",
|
|
4
|
+
"description": "Micro-frontends for any framework with zero host build config. Mix React, Next.js, Vue, Nuxt, Angular, Svelte and more on one page.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"micro-frontend",
|
|
7
7
|
"micro-frontends",
|