DOCSEARCHbyAlgolia
Submit Docs

micro-app Documentation

repository·master·Indexed 27 days ago

https://github.com/jd-opensource/micro-app

A lightweight, efficient, and framework-agnostic micro front-end framework by JD Retail. It uses a webcomponent-like approach to embed sub-applications, providing JS sandboxing, style isolation, element isolation, and route isolation with minimal configuration. The framework allows developers to encapsulate micro-frontends as class-based WebComponent components for componentized rendering.

Tokens
17.7K
Snippets
55
Records
122
Agent score
91%

What's inside micro-app

  1. Overview of micro-app

    master

    micro-app is a micro-frontend framework released by the JD frontend team. It leverages WebComponent concepts to provide isolation features similar to ShadowDom, including JS sandboxing, style isolation, element isolation, and route isolation. It encapsulates micro-frontends as class-based WebComponent components to enable componentized rendering.

    Key characteristics:

    • Framework Agnostic: It is not tied to any specific technology stack or business logic and can be used with any frontend framework.
    • Low Learning Curve: Designed to be easy to use by encapsulating functionality into a single component.
    • Comprehensive Features: Provides JS sandboxing, style isolation, element isolation, route isolation, preloading, and data communication.

  2. Get data from a child application in the main application

    master

    The main application can retrieve data sent by a child application using three methods:

    1. Direct Access: Use microApp.getData(appName) to immediately return the current data of a specific child application.
    2. Custom Event (datachange): Listen for the datachange event on the <micro-app> element. The data is located in event.detail.data.
      • React Users: You must import a polyfill at the top of the file where the <micro-app> element is located: import jsxCustomEvent from '@micro-zoe/micro-app/polyfill/jsx-custom-event'.
      • Vue Users: Use the @datachange event listener.
    3. Listener Functions: Use microApp.addDataListener to bind a callback function that triggers whenever the child application sends data.
    // Method 1: Direct
import microApp from '@micro-zoe/micro-app'
const childData = microApp.getData('my-app')

// Method 2: React (with polyfill)
/** @jsxRuntime classic */
/** @jsx jsxCustomEvent */
import jsxCustomEvent from '@micro-zoe/micro-app/polyfill/jsx-custom-event'

<micro-app
  name='my-app'
  url='xx'
  onDataChange={(e) => console.log('Data:', e.detail.data)}
/>

// Method 3: Listener
function dataListener (data) {
  console.log('Data from my-app', data)
}
microApp.addDataListener('my-app', dataListener)

  4. Download and run the micro-app repository

    master

    To set up the entire development environment, clone the repository, install dependencies for both the project and the demos using yarn bootstrap, and then start the default application setup.

    By default, the base application is main-react16, and it will start the following sub-applications: react16, react17, vue2, vue3, angular11, and vite.

    git clone https://github.com/jd-opensource/micro-app.git

cd micro-app

// Install dependencies for the project and demos
yarn bootstrap 

// Run the default setup
yarn start

  6. Set up a Vue 3 project with Vite

    master

    This template provides a starting point for developing Vue 3 applications using Vite.

    Project Setup

    Install dependencies using pnpm:

    pnpm install

    Development

    Run the development server with hot-reload enabled:

    pnpm dev

    Production

    Perform type-checking, compilation, and minification for production builds:

    pnpm build
    pnpm install
pnpm dev
pnpm build

  7. Exclude specific JS, CSS, or Style elements

    master

    To prevent a child application from loading specific JS or CSS resources, add the exclude attribute to the corresponding link, script, or style elements. Micro-app will detect this attribute and delete the element instead of processing it.

    <link rel="stylesheet" href="xx.css" exclude>
<script src="xx.js" exclude></script>
<style exclude></style>

  8. Configure MicroApp routing modes

    master

    MicroApp uses a virtual routing system to isolate child application routing from the main application. You can configure the router-mode for individual child applications via HTML attributes or globally via microApp.start().

    Available modes:

    • search (Default): Synchronizes child routing information to the browser address as a query parameter.
    • native: Releases routing isolation; child and main applications share the browser routing.
    • native-scope: Similar to native, but the child application's domain name points to itself rather than the main application.
    • pure (Experimental): Renders the child application independently of browser routing without modifying the address or stack. Not recommended for complex apps.
    • state (Experimental): Simulates routing behavior using history.state without modifying the browser address. Similar performance to iframe routing without iframe issues.
    <!-- Set single child application mode -->
<micro-app name='xx' url='xx' router-mode='search'></micro-app>

// Set global routing mode
import microApp from '@micro-zoe/micro-app'

microApp.start({
  'router-mode': 'search',
})

  10. Navigate from a Child Application to the Main Application

    master
    By default, child applications are isolated from the main application's routing. To allow a child application to control the main application's navigation, the Main Application must explicitly register its router object, and the Child Application can then access it via window.microApp.

  12. Eject from Create React App configuration

    master

    If you need full control over the build tool and configuration (webpack, Babel, ESLint, etc.), you can run yarn eject.

    Warning: This is a one-way operation. Once you eject, you cannot go back.

    This command removes the single build dependency and copies all configuration files and transitive dependencies directly into your project.

    yarn eject