wenzirang / qiankun

📦🚀Blazing fast, simple and completed solution for micro frontends.

qiankun（乾坤）

In Chinese traditional culture qian means heaven and kun stands for earth, so qiankun is the universe.

An implementation of Micro Frontends, based on single-spa, but made it production-ready.

🤔 Motivation

As we know what micro-frontends aims for:

Techniques, strategies and recipes for building a modern web app with multiple teams using different JavaScript frameworks. — Micro Frontends

An independent development experience is very important for a large system, especially with an enterprise application. But if you've tried to implement a micro-frontends architecture in such a system, you'll usually hurt your brain with such problems:

• How to compose your independent sub apps into your main system?
• How to guarantee your sub apps to be isolated by each other?
• and so on...

We built an library to help you solve these glitch problems automatically without any mental burden of yours, then named it qiankun.

Probably the most complete micro-frontends solution you ever met🧐.

📦 Installation

npm i qiankun -S

🔨 Getting Started

1. Create master framework with qiankun

   import { registerMicroApps, start } from 'qiankun';
   
   function render({ appContent, loading }) {
     const container = document.getElementById('container');
     ReactDOM.render(<Framework loading={loading} content={appContent}/>, container);
   }
   
   function genActiveRule(routerPrefix) {
     return (location) => location.pathname.startsWith(routerPrefix);
   }
   
   registerMicroApps(
     [
       { 
         name: 'react app', // app name registered
         entry: '//localhost:7100',
         render, 
         activeRule: genActiveRule('/react') },
       { 
         name: 'vue app',
         entry: { scripts: [ '//localhost:7100/main.js' ] }, 
         render, 
         activeRule: genActiveRule('/vue') 
       },
     ],
   );
   
   start({ prefetch: true, jsSandbox: true });

2. Export the lifecycles from your sub app entry

   export async function bootstrap() {
     console.log('react app bootstraped');
   }
   
   export async function mount(props) {
     console.log(props);
     ReactDOM.render(<App/>, document.getElementById('react15Root'));
   }
   
   export async function unmount() {
     ReactDOM.unmountComponentAtNode(document.getElementById('react15Root'));
   }

   For more lifecycle information, see single-spa lifecycles

3. Config your sub app bundler

While you wanna build a sub app to integrate to qiankun, pls make sure your bundler have the required configuration below:

webpack:

output: {
  library: packageName,
  libraryTarget: 'umd',
  jsonpFunction: `webpackJsonp_${packageName}`,
}

see https://webpack.js.org/configuration/output/#outputlibrary

parcel:

parcel serve entry.js --global myvariable

see https://en.parceljs.org/cli.html#expose-modules-as-umd

💿 Examples

npm i
npm run install:examples
npm start

Visit http://localhost:7099

✨ Features

• Based on single-spa
• HTML Entry
• Config Entry
• Isolated styles
• JS Sandbox
• Assets Prefetch
• @umijs/plugin-qiankun integration

📖 API

registerMicroApps

type RegistrableApp = {
	// name to identify your app
  name: string;
  // where your sub app served from, supported html entry and config entry
  entry: string | { scripts?: string[]; styles?: string[]; html?: string };
  // render function called around sub app lifecycle
  render: (props?: { appContent: string, loading: boolean }) => any;
  // when sub app active
  activeRule: (location: Location) => boolean;
  // props pass through to sub app
  props?: object;
};

type Lifecycle<T extends object> = (app: RegistrableApp<T>) => Promise<any>;
type LifeCycles<T extends object> = {
    beforeLoad?: Lifecycle<T> | Array<Lifecycle<T>>;
    beforeMount?: Lifecycle<T> | Array<Lifecycle<T>>;
    afterMount?: Lifecycle<T> | Array<Lifecycle<T>>;
    afterUnmount?: Lifecycle<T> | Array<Lifecycle<T>>;
};

function registerMicroApps<T extends object = {}>(apps: Array<RegistrableApp<T>>, lifeCycles?: LifeCycles<T>): void;

start

function start({ prefetch: boolean, jsSandbox: boolean }): void;

🎯 Roadmap

• Parcel apps integration (multiple sub apps displayed at the same time, but only one uses router at most)
• Communication development kits between master and sub apps
• Custom side effects hijacker
• Nested Microfrontends

❓ FAQ

https://github.com/umijs/qiankun/wiki/FAQ

👬 Community

https://github.com/umijs/umi#community

🎁 Acknowledgements

• single-spa What an awesome meta-framework for micro-fronteds!