Polyfea microfrontend core library and browser driver
This package is the backbone of the Polyfea microfrontend framework. It manages the lifecycle of microfrontends. It also includes a browser driver for interfacing with the Polyfea microfrontend controller.
Installation
npm install @polyfea/coreDocumentation
- The polyfea-context element loads microfrontends into the document, replacing itself (by
display: contents) with the microfrontend's content. - The Polyfea class is for advanced use cases, providing control over the loading of microfrontends and elements.
- The Navigation polyfill intercepts navigation events and enables programmatic navigation in browsers that don't yet support the Navigation API.
- The href function helps with navigation in the single page application.
Usage
The core library enables the Polyfea microfrontend controller to manage microfrontends. Use the <polyfea-context name="my-context"></polyfea-context> element to load resources and elements for a specific context.
Example: Using Boot Script from NPM Package
This example is useful for testing microfrontends with the standalone Polyfea driver during development. Set up your index.html file as follows:
<!DOCTYPE html>
<html dir="ltr" lang="en">
<head>
<base href="/ui/">
<title>Sample polyfea microfrontend</title>
<!-- Alows for repeated registration of the same custom elements.
Possible values are: verbose, silent, warn, error -->
<meta name="polyfea.duplicit-custom-elements" content="verbose">
<!-- Microfrontend configuration is taken from the backend.
You may specify the static configuration.
It will expect StaticConfig json resource to be available
at document.baseURI relative path ./polyfea/static-config
See https://github.com/polyfea/browser-api/blob/main/docs/interfaces/StaticConfig.md
-->
<meta name="polyfea.backend" content="static://">
<!-- Load polyfea driver-->
<script type="module" src="node_modules/@polyfea/core/dist/boot.mjs"></script>
<!-- you may replace above line with a a loading from release assets -->
<!-- <script type="module" src="https://cdn.jsdelivr.net/npm/@polyfea/core@1/dist/boot.mjs"></script> -->
</head>
<body></body>
</html>The code above loads the Polyfea driver and dynamically inserts the <polyfea-context name="shell" take="1"></polyfea-context> element into the document body. This element is populated with microfrontend content from the backend.
Your static configuration should be in the /ui/polyfea/static-config JSON file, served by your development server. For more information, see StaticConfig.
{
"microfrontends": {
"my-fea": {
"module": "./dist/myfea.esm.js",
"resources": [
{
"kind": "stylesheet",
"href": "./build/material-shell-webc.css"
}
]
},
"my-other-fea": {
"dependsOn": [
"my-fea"
],
"module": "./build/material-shell-webc.esm.js",
"resources": [
{
"kind": "stylesheet",
"href": "./build/material-shell-webc.css"
}
]
}
},
"contextAreas": [
{
"name": "shell",
"contextArea": {
"elements": [
{
"tagName": "my-shell-element",
"microfrontend": "my-fea"
}
]
}
},
{
"name": "my-context",
"contextArea": {
"elements": [
{
"tagName": "my-other-element",
"microfrontend": "my-other-fea"
}
]
}
}]
}Use the polyfea-context element in your document to dynamically load elements and microfrontends based on your configuration. This element will be replaced with the loaded microfrontend content. It's ideal for loading elements developed by other teams or subprojects with separate development and release cycles. Avoid using polyfea-context for custom elements in the same repository.
Configuration
You can influence the behavior of the package by setting the <meta> tags in the <head> of your document. Below is a list of supported meta tag names and their contents:
| Attribute Name | Default | Description |
|---|---|---|
| polyfea.backend | ./polyfea | Specifies the API URL for retrieving information about configured context areas. If preceded with static://, then the static-config API path is called at module load instead of calling context-area queries for each context area. |
| polyfea.cyclic-context-areas | error | Determines behavior when cyclic nested context areas are used to avoid infinite recursion. Possible values are error (displays an error in the document flow), silent (provides no output), and allow (allows areas recursion). |
| polyfea.cyclic-context-message | Error message to show if context area name recursion is detected. | |
| csp-none | Nonce to use for dynamically inserted scripts and styles. This nonce must match the nonce used in the Content-Security-Policy header. This method is safe, as scripts must be secured before being able to read the DOM. | |
| polyfea.duplicit-custom-elements | warn | Behavior when duplicate custom elements are registered at window.customElements. Possible values are silent, verbose, warn, and error. |
Developing
To begin development on this package, follow these steps:
- Clone the repository to your local machine.
- Run
npm installto install the necessary dependencies. - Execute
npm run startto start the development server. - Adapt the
src/index.htmlfile to meet the specific requirements of your development task.
With these steps, you can easily set up your development environment and make changes to the package as needed.
Run npm run build before commiting to ensure up-to-date documentation in the repository.