@mcplex-js/web-components

MCPlex Web Components built with Lit Element for dynamically loading and mounting micro-frontend modules using the single-spa architecture.

Installation

npm install @mcplex-js/web-components

Usage

The primary component is <mcplex-module>, which allows you to dynamically load and mount modules from an import map.

Basic Usage

<!-- Include the web components bundle -->
<script src="./dist/mcplex-web-components.iife.js"></script>

<!-- Use the mcplex-module component -->
<mcplex-module 
  module-name="@my-org/my-module"
  data-config='{"lifecycles": "myWidgetLifecycles"}'
  data-args='{"title": "Hello World"}'>
</mcplex-module>

ES Module Import

import '@mcplex-js/web-components';

// The component is now available as <mcplex-module>

Component Properties

The <mcplex-module> component accepts the following attributes:

| Attribute | Type | Default | Description | |-----------|------|---------|-------------| | module-name | String | "" | The name/path of the module to load from the import map | | data-config | JSON String | {"lifecycles": "default"} | Configuration object containing lifecycle information | | data-args | JSON String | {} | Arguments to pass to the mounted module |

Configuration

Module Configuration

The data-config attribute should contain a JSON object with at least the lifecycles property:

{
  "lifecycles": "myWidgetLifecycles",
  "type": "single-spa"
}

Module Arguments

Pass data to your module using the data-args attribute:

{
  "title": "My Widget",
  "data": {
    "items": ["item1", "item2"]
  }
}

Example: Pokemon Card Widget

<mcplex-module 
  module-name="@mcplex-js/sample-single-spa-widgets"
  data-config='{"lifecycles": "pokemonCardWidgetlifecycles"}'
  data-args='{
    "pokemon": {
      "name": "raichu",
      "pokemontypes": [{"type": {"name": "electric"}}],
      "pokemonsprites": [{
        "sprites": "https://raw.githubusercontent.com/PokeAPI/sprites/master/sprites/pokemon/other/official-artwork/26.png"
      }]
    }
  }'>
</mcplex-module>

Creating Compatible Modules

To create modules that work with <mcplex-module>, your module should export single-spa lifecycles:

// my-widget.js
import singleSpaReact from 'single-spa-react';
import React from 'react';
import ReactDOMClient from 'react-dom/client';
import MyComponent from './MyComponent';

export const myWidgetLifecycles = singleSpaReact({
  React,
  ReactDOMClient,
  renderType: 'createRoot',
  rootComponent: MyComponent,
});

Requirements

• Import Map: Your application must have an import map configured to resolve module names
• Single-SPA: The single-spa library should be available in your import map
• Import Map Injector: The window.importMapInjector should be available for dynamic loading

Loading States

The component automatically handles loading states:

• Loading: Shows "Loading module..." while the module is being fetched
• Error: Displays error message if module loading fails
• Success: Renders the loaded module content

Browser Compatibility

Built with Lit Element for modern browser compatibility. Supports all browsers that support:

• ES2018+
• Web Components (Custom Elements, Shadow DOM)
• ES Modules

Development

# Build the components
npm run build

# Watch for changes
npm run build:watch

# Serve for development
npm run serve

License

ISC