Skip to content

Commit 6abfb5f

Browse files
FlorianRapplFlorianRappl
committed
Updated docs
1 parent 11a36a7 commit 6abfb5f

File tree

6 files changed

+236
-6
lines changed

6 files changed

+236
-6
lines changed

‎.vitepress/config.mts

+1-1
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.1.0",
53+
text: "0.2.3",
5454
items: [
5555
{
5656
text: "Changelog",

‎api/configuration/options.md

+111-1
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,113 @@
11
# Initialization Options
22

3-
...
3+
## Browser
4+
5+
In the browser Picard.js automatically runs - all you need to do is follow [the installation guide](../../guide/variants/browser.md).
6+
7+
To set the initial configuration you can use a callback, e.g., on the `load` event:
8+
9+
```html
10+
<script>
11+
function configure({ target }) {
12+
// Place a `config` property on the associated `<script>` element, e.g.,:
13+
target.config = {
14+
// ...
15+
};
16+
}
17+
</script>
18+
<script src="./dist/picard.js" onload="configure(event)"></script>
19+
```
20+
21+
The provided configuration has to follow the definition for the client. All options except `feed` and `state` can be set.
22+
23+
## Client
24+
25+
The `initializePicard` function can be called with an options object respecting the following interface:
26+
27+
```ts
28+
interface PicardOptions {
29+
/**
30+
* The name of the pi-component.
31+
* @default pi-component
32+
*/
33+
componentName?: string;
34+
/**
35+
* The name of the pi-slot.
36+
* @default pi-slot
37+
*/
38+
slotName?: string;
39+
/**
40+
* The name of the pi-part.
41+
* @default pi-part
42+
*/
43+
partName?: string;
44+
/**
45+
* The micro frontend discovery service URL,
46+
* data from calling it, or callback function
47+
* to call it manually.
48+
*/
49+
feed?: FeedDefinition;
50+
/**
51+
* The initial state of Picard.js - if resumed.
52+
*/
53+
state?: any;
54+
/**
55+
* The application's meta data.
56+
*/
57+
meta?: any;
58+
/**
59+
* The additional services to register.
60+
*/
61+
services?: Record<string, any>;
62+
/**
63+
* The centrally shared dependencies to use.
64+
*/
65+
dependencies?: Record<string, () => Promise<any>>;
66+
}
67+
```
68+
69+
## Node
70+
71+
The `initializePicard` function can be called with an options object respecting the following interface:
72+
73+
```ts
74+
interface PicardOptions {
75+
/**
76+
* The name of the pi-component.
77+
* @default pi-component
78+
*/
79+
componentName?: string;
80+
/**
81+
* The name of the pi-slot.
82+
* @default pi-slot
83+
*/
84+
slotName?: string;
85+
/**
86+
* The name of the pi-part.
87+
* @default pi-part
88+
*/
89+
partName?: string;
90+
/**
91+
* The URL of the fragment service, if any.
92+
*/
93+
fragmentUrl?: string;
94+
/**
95+
* The micro frontend discovery service URL,
96+
* data from calling it, or callback function
97+
* to call it manually.
98+
*/
99+
feed?: FeedDefinition;
100+
/**
101+
* The initial state of Picard.js - if resumed.
102+
*/
103+
state?: any;
104+
/**
105+
* The additional services to register.
106+
*/
107+
services?: Record<string, any>;
108+
/**
109+
* The centrally shared dependencies to use.
110+
*/
111+
dependencies?: Record<string, () => Promise<any>>;
112+
}
113+
```

‎api/configuration/services.md

+38-1
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,40 @@
11
# Runtime Services
22

3-
...
3+
Picard.js comes with a set of services that can be extended to provide more or augmented functionality.
4+
5+
## Service Definitions
6+
7+
Right now the following extensible services exist:
8+
9+
| Service Key Structure | Example | Interface | Notes |
10+
| --------------------- | ----------------- | --------------------- | ------------- |
11+
| `framework.{type}` | `framework.react` | `ConverterService` | |
12+
| `format.{name}` | `format.module` | `ContainerService` | |
13+
| `slotRel.{name}` | `slotRel.router` | `SlotBehaviorService` | |
14+
| `part.{name}` | `part.style` | `PartService` | SSR only |
15+
16+
## Interfaces
17+
18+
```ts
19+
interface ConverterService {
20+
convert(component: any, opts: any): ComponentLifecycle;
21+
}
22+
```
23+
24+
```ts
25+
interface ContainerService {
26+
createContainer(details: any): Promise<ComponentGetter>;
27+
}
28+
```
29+
30+
```ts
31+
interface SlotBehaviorService {
32+
apply(attribs: Record<string, string>): [name: string, data: any];
33+
}
34+
```
35+
36+
```ts
37+
interface PartService {
38+
getReplacement(document: Document, attribs: Record<string, string>): Promise<string>;
39+
}
40+
```

‎guide/formats/module-federation.md

+56-1
Original file line numberDiff line numberDiff line change
@@ -6,4 +6,59 @@ Module Federation allows JavaScript applications to share and load code dynamica
66

77
## Using Module Federation
88

9-
...
9+
Module Federation can be used either as part of a discovery service response or directly by referencing a component using a `source` with `format` set to `module`. Depending on the version and variant of Module Federation more parameters such as `remote-name` and `remote-type` might be necessary.
10+
11+
### Module Federation v1 with Globals
12+
13+
```html
14+
<pi-component
15+
name="MyComponent"
16+
source="https://yourcompany.com/example/remoteEntry.js"
17+
format="module"
18+
remote-name="example"
19+
></pi-component>
20+
```
21+
22+
Required:
23+
24+
- `format` has to be set to `module`
25+
- `remote-name` has to be set to the global defined by the micro frontend
26+
27+
Optional:
28+
29+
- `remote-type` has to be set to `var`
30+
31+
### Module Federation v1 with ESModules
32+
33+
```html
34+
<pi-component
35+
name="MyComponent"
36+
source="https://yourcompany.com/example/remoteEntry.mjs"
37+
format="module"
38+
remote-name="example"
39+
remote-type="esm"
40+
></pi-component>
41+
```
42+
43+
Required:
44+
45+
- `format` has to be set to `module`
46+
- `remote-name` has to be set to the global defined by the micro frontend
47+
- `remote-type` has to be set to `esm`
48+
49+
### Module Federation v2 with Manifest
50+
51+
Here, you reference the manifest.
52+
53+
```html
54+
<pi-component
55+
name="MyComponent"
56+
source="https://yourcompany.com/example/mf-manifest.json"
57+
format="module"
58+
></pi-component>
59+
```
60+
61+
Required:
62+
63+
- `format` has to be set to `module`
64+
- `remote-name` has to be left unspecified

‎guide/formats/native-federation.md

+15-1
Original file line numberDiff line numberDiff line change
@@ -6,4 +6,18 @@ Native Federation is a microfrontend architecture for mobile apps, allowing dyna
66

77
## Using Native Federation
88

9-
...
9+
Native Federation modules can be used either as part of a discovery service response or directly by referencing a component using a `source` with `format` set to `native`.
10+
11+
### Native Federation
12+
13+
```html
14+
<pi-component
15+
name="MyComponent"
16+
source="https://yourcompany.com/example/remoteEntry.json"
17+
format="native"
18+
></pi-component>
19+
```
20+
21+
Required:
22+
23+
- `format` has to be set to `native`

‎guide/formats/pilet-v2.md

+15-1
Original file line numberDiff line numberDiff line change
@@ -6,4 +6,18 @@ Pilets are the building blocks of microfrontends in Piral, a framework for creat
66

77
## Using Pilets
88

9-
...
9+
Pilets can be used either as part of a discovery service response or directly by referencing a component using a `source` with `format` set to `pilet`. Depending on the pilet specification more parameters might be necessary.
10+
11+
### Pilet v2
12+
13+
```html
14+
<pi-component
15+
name="MyComponent"
16+
source="https://yourcompany.com/example/index.meta.json"
17+
format="pilet"
18+
></pi-component>
19+
```
20+
21+
Required:
22+
23+
- `format` has to be set to `pilet`

0 commit comments

Comments
 (0)