Skip to content

Commit 2cd7c7d

Browse files
FlorianRapplFlorianRappl
committed
Extended docs for 0.3.0
1 parent ee2e9f5 commit 2cd7c7d

File tree

7 files changed

+260
-1
lines changed

7 files changed

+260
-1
lines changed

‎.vitepress/config.mts‎

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,7 @@ export default defineConfig({
5050
{ text: "Guide", link: "/guide/" },
5151
{ text: "API", link: "/api/" },
5252
{
53-
text: "0.2.3",
53+
text: "0.3.0",
5454
items: [
5555
{
5656
text: "Changelog",
@@ -73,6 +73,7 @@ export default defineConfig({
7373
{ text: "Why Picard.js?", link: "/guide/why" },
7474
{ text: "Features", link: "/guide/features" },
7575
{ text: "Comparisons", link: "/guide/comparisons" },
76+
{ text: "FAQ", link: "/guide/faq" },
7677
],
7778
},
7879
{
@@ -142,6 +143,23 @@ export default defineConfig({
142143
{ text: "Runtime Services", link: "/api/configuration/services" },
143144
],
144145
},
146+
{
147+
text: "Discovery Services",
148+
items: [
149+
{
150+
text: "Piral Feed Service",
151+
link: "/api/discovery/piral-feed-service",
152+
},
153+
{
154+
text: "Discovery Schema",
155+
link: "/api/discovery/discovery-schema",
156+
},
157+
{
158+
text: "Native Federation Manifest",
159+
link: "/api/discovery/native-federation-manifest",
160+
},
161+
],
162+
},
145163
{
146164
text: "Lifecycle",
147165
items: [{ text: "Generic Lifecycle", link: "/api/lifecycle/" }],

‎api/discovery/discovery-schema.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# Discovery Schema
2+
3+
Discovery service responses following [the MFWG schema specification](https://github.com/awslabs/frontend-discovery) are directly supported.
4+
5+
::: tip
6+
Follow the JSON schema defined in the linked [GitHub repository](https://github.com/awslabs/frontend-discovery/blob/main/schema/v1-pre.json) for making your own discovery service compatible with Picard.
7+
:::
8+
9+
## Schema Description
10+
11+
The returned response has either to be an object with a property named `microFrontends`, which is an object again - consisting of a mapping of names of micro frontends to their different definitions (i.e., one or more definitions per version).
12+
13+
## Mapping of Properties
14+
15+
### Module Federation
16+
17+
To be recognized as a micro frontend using Module Federation the entry needs to have a section `modulefederation` placed on `extras` of the definition. Alternatively, if the URL ends with `.js` and no other type has been recognized Picard.js will fall back to Module Federation.
18+
19+
| Property | Description |
20+
| ------------------------- | --------------------------------------------------- |
21+
| `[key]` | Name of the micro frontend |
22+
| `[value]` | The micro frontend definition |
23+
| `def.url` | Link to the remote entry manifest |
24+
| `def.extras.id` | The global name of the remote |
25+
| `def.extras.metaData` | The `metaData` section of the remote entry manifest |
26+
| `def.extras.exposes` | The `exposes` section of the remote entry manifest |
27+
| `def.extras.remotes` | The `remotes` section of the remote entry manifest |
28+
| `def.extras.shared` | The `shared` section of the remote entry manifest |
29+
| `def.extras.runtime` | The MF runtime version (e.g., `1.0` or `2.0`) |
30+
| `def.extras.type` | The type (`esm` / `module` or `var` / `global`) |
31+
32+
::: warning
33+
It is crucial that the right runtime version of Module Federation is transported. While a missing `runtime` value could still be inferred correctly, an incorrect one will almost certainly lead to a wrong interpretation of the micro frontend.
34+
:::
35+
36+
### Native Federation
37+
38+
To be recognized as a micro frontend using Native Federation the entry needs to have a section `nativefederation` placed on `extras` of the definition.
39+
40+
| Property | Description |
41+
| ------------------------- | --------------------------------------------------- |
42+
| `[key]` | Name of the micro frontend |
43+
| `[value]` | The micro frontend definition |
44+
| `def.url` | Link to the remote entry JSON |
45+
| `def.extras.exposes` | The `exposes` section of the remote entry JSON |
46+
| `def.extras.dependencies` | The `dependencies` section of the remote entry JSON |
47+
48+
### Pilets
49+
50+
To be recognized as a micro frontend using Piral (i.e., a pilet) the entry needs to have a section `pilet` placed on `extras` of the definition.
51+
52+
| Property | Description |
53+
| ------------------------- | --------------------------------------------------- |
54+
| `[key]` | Name of the micro frontend |
55+
| `[value]` | The micro frontend definition |
56+
| `def.url` | Link to the entry module |
57+
| `def.extras.dependencies` | The `dependencies` section of pilet |
58+
| `def.extras.config` | The `config` section of the pilet |
59+
| `def.extras.pilet.spec` | The `spec` section of the pilet |
60+
| `def.version` | The `version` of the pilet |
61+
| `def.integrity` | The `integrity` section of the pilet |
62+
63+
### Anything Else
64+
65+
**This is not supported** (right now).
66+
67+
All values in the discovery schema are interepreted as one of the previously three mentioned formats. If you know another format that can be / is transported commonly then let us know!

‎api/discovery/index.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Discovery Response Overview
2+
3+
The following sections on accepted discovery responses exist:
4+
5+
- [Piral Feed Service](./piral-feed-service.md)
6+
- [Discovery Schema](./discovery-schema.md)
7+
- [Native Federation Manifest](./native-federation-manifest.md)

‎api/discovery/native-federation-manifest.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# Native Federation Manifest
2+
3+
Discovery service responses following [the Native Federation manifest](https://github.com/angular-architects/module-federation-plugin/blob/main/libs/native-federation/README.md#initializing-the-host) are directly supported.
4+
5+
## Schema Description
6+
7+
The returned response has to be an object mapping a string (name of the micro frontend) to a string (URL of the micro frontend manifest given as a JSON).
8+
9+
## Mapping of Properties
10+
11+
### Module Federation
12+
13+
**This is not supported**.
14+
15+
All values in the Native Federation manifest are interpreted as remote entries describing a micro frontend using Native Federation.
16+
17+
### Native Federation
18+
19+
| Property | Description |
20+
| --------- | ----------------------------- |
21+
| `[key]` | Name of the micro frontend |
22+
| `[value]` | Link to the remote entry JSON |
23+
24+
### Pilets
25+
26+
**This is not supported**.
27+
28+
All values in the Native Federation manifest are interpreted as remote entries describing a micro frontend using Native Federation.
29+
30+
### Anything Else
31+
32+
**This is not supported**.
33+
34+
All values in the Native Federation manifest are interpreted as remote entries describing a micro frontend using Native Federation.

‎api/discovery/piral-feed-service.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# Piral Feed Service
2+
3+
Discovery service responses following [the Piral Feed Service specification](https://docs.piral.io/reference/specifications/feed-api-specification) are directly supported.
4+
5+
::: tip
6+
You can get access to a *free* (for personal and non-production payloads) discovery service at [feed.piral.cloud](https://feed.piral.cloud). If you like to use this on-premise you can even get a licensed version with support. For more information, see [www.piral.cloud](https://www.piral.cloud).
7+
8+
This document describes the *default* response from the Piral Cloud Feed Service - following the [specification](https://docs.piral.io/reference/specifications/feed-api-specification). Note, that the Piral Cloud Feed Service also supports providing responses in other formats, such as [the discovery schema](./discovery-schema.md).
9+
:::
10+
11+
## Schema Description
12+
13+
The returned response has either to be an array consisting of objects following the schema (i.e., they need to have a `name`, `version`, `spec` and `link` property), or must be an object with an `items` property that is an array with the previously mentioned array items.
14+
15+
While pilets are directly supported, other micro frontends such as Module Federation or Native Federation powered micro frontends are covered with a special property called `custom`.
16+
17+
## Mapping of Properties
18+
19+
### Module Federation
20+
21+
| Property | Description |
22+
| ------------------------- | --------------------------------------------------- |
23+
| `name` | Name of the micro frontend |
24+
| `spec` | Needs to be set to `mf` |
25+
| `link` | Link to the remote entry (manifest or JS) |
26+
| `custom.id` | The global name of the remote |
27+
| `custom.metaData` | The `metaData` section of the remote entry manifest |
28+
| `custom.exposes` | The `exposes` section of the remote entry manifest |
29+
| `custom.remotes` | The `remotes` section of the remote entry manifest |
30+
| `custom.shared` | The `shared` section of the remote entry manifest |
31+
| `custom.runtime` | The MF runtime version (e.g., `1.0` or `2.0`) |
32+
| `custom.type` | The type (`esm` / `module` or `var` / `global`) |
33+
34+
::: warning
35+
It is crucial that the right runtime version of Module Federation is transported. While a missing `runtime` value could still be inferred correctly, an incorrect one will almost certainly lead to a wrong interpretation of the micro frontend.
36+
:::
37+
38+
### Native Federation
39+
40+
| Property | Description |
41+
| ------------------------- | --------------------------------------------------- |
42+
| `name` | Name of the micro frontend |
43+
| `spec` | Needs to be set to `nf` |
44+
| `link` | Link to the JSON definition |
45+
| `custom.exposes` | The `exposes` section of JSON definition |
46+
| `custom.dependencies` | The `dependencies` section of the JSON definition |
47+
48+
### Pilets
49+
50+
| Property | Description |
51+
| ------------------------- | --------------------------------------------------- |
52+
| `name` | Name of the micro frontend |
53+
| `version` | The version of the micro frontend |
54+
| `link` | The URL of the entry module |
55+
| `dependencies` | The `dependencies` section of pilet |
56+
| `config` | The `config` section of pilet |
57+
| `spec` | The `spec` section of the pilet |
58+
| `integrity` | The `integrity` section of the pilet |
59+
60+
### Anything Else
61+
62+
**This is not supported** (right now).
63+
64+
All values in the discovery schema are interepreted as one of the previously three mentioned formats. If you know another format that can be / is transported commonly then let us know!

‎api/lifecycle/index.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,10 @@
1212
| `bootstrap` | Server | | `Promise<void>` |
1313
| `stringify` | Server | `props` (1) | `Promise<string>` |
1414

15+
::: info
16+
Hydration scenarios are covered via `mount` by looking either into `container` (would be non-empty in a hydration scenario) or into `locals` (which would contain a truthy value for `hydrate`, i.e., `!!locals.hydrate` would be `true`).
17+
:::
18+
1519
(1) the `props` are the deserialized object from the `data` property
1620

1721
(2) the `locals` is an (initially) empty object that can be used at will to transport information between the different lifecycle methods; it is created per component instance

‎guide/faq.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# Frequently Asked Questions
2+
3+
**What else is missing for now?**
4+
5+
> Not much - Picard.js is close to being feature complete. Right now we are tuning the packaging, API, and some of the covered functionality such as what formats are supported.
6+
7+
**When is Picard.js feature complete?**
8+
9+
> Presumably end of July / start of August 2024.
10+
11+
**When is Picard.js ready for production?**
12+
13+
> In September 2024.
14+
15+
**How does SSR work with web components?**
16+
17+
> When the HTML is streamed out we'll look at the code and replace the configured web components with the rendering done by the referenced micro frontend(s).
18+
19+
**What formats (micro frontend frameworks) are supported?**
20+
21+
> Picard.js supports micro frontends using SystemJS like Piral, but also Module Federation (v1 and v2), Native Federation, as well as plain native esm modules.
22+
23+
**What UI libraries (frameworks) are supported?**
24+
25+
> Picard.js supports every UI library as long as it can be converted to Picard's own [lifecycle definition](../api/lifecycle/index.md) or to an integrated target [such as single-spa](./frameworks/single-spa.md).
26+
27+
**Can dependencies be shared between the different formats, such as module federation and native federation?**
28+
29+
> Yes.
30+
31+
**Is native federation also capable of rendering server-side?**
32+
33+
> In general yes - that, of course, depends if your component is capable of being server-side rendered.
34+
35+
**How can I contribute to the project?**
36+
37+
> Reporting issues, writing fixes or new features, writing an article or sharing your success story. There are multiple ways to contribute!
38+
39+
**What's the story behind Picard.js and Piral? Is Picard.js the successor of Piral?**
40+
41+
> No, but it will be the base library for Piral v2 - effectively replacing `piral-base` in the process.
42+
43+
**Can the Piral Cloud Feed Service work with Picard.js?**
44+
45+
> Yes, it works with anything that you can throw into Picard.js.
46+
47+
**What micro frontend discovery services can work with Picard?**
48+
49+
> Any service providing one of the known [discovery formats](../api/discovery/index.md) works out of the box. For anything else you can use a callback and convert the response.
50+
51+
**Can you go into details regarding how Picard.js loads and orchestrates the micro frontends?**
52+
53+
> Sure, have a look at our [architecture documentation](https://github.com/picardjs/picard/blob/develop/ARCHITECTURE.md) in the repo.
54+
55+
**Why should I use module federation with Picard.js over just plain module federation?**
56+
57+
> There can be multiple reasons, such as (1) you also need to integrate micro frontends using something else (2) you need to be flexible regarding the choice of tooling (3) you want to fully embrace a powerful micro frontend discovery service without needing to know Module Federation internals (4) you want to be loosely coupled and fully resiliant in your application
58+
59+
**Do I need to integrate Picard.js from the get-go or can I just wait / use it when necessary?**
60+
61+
> You can also wait and progressively go into Picard.js. The beauty of web components is that you can already use them - in the worst case they would just not render (yet).
62+
63+
**Will there be articles available for Picard.js?**
64+
65+
Yes! And there will be [more videos](https://www.youtube.com/watch?v=_XPytuQrKaY), too.

0 commit comments

Comments
 (0)