docs/guide/quick-start.md
This guide will help you set up a basic qiankun micro-frontend application in 5 minutes.
::: code-group
npm install qiankun
yarn add qiankun
pnpm add qiankun
:::
# Create main application using your favorite framework
npx create-react-app main-app
cd main-app
npm install qiankun
Register micro applications in the main application's entry file:
// src/index.js
import { registerMicroApps, start } from 'qiankun';
// register micro applications
registerMicroApps([
{
name: 'vue-app', // micro app name, unique
entry: '//localhost:8080', // micro app entry
container: '#subapp-viewport', // micro app mount node
activeRule: '/vue', // micro app activation rule
},
{
name: 'react-app',
entry: '//localhost:3001',
container: '#subapp-viewport',
activeRule: '/react',
},
]);
// start qiankun
start();
// render main application normally
ReactDOM.render(<App />, document.getElementById('root'));
Reserve mount nodes for micro applications in the main application:
// src/App.js
import React from 'react';
import { BrowserRouter as Router, Link } from 'react-router-dom';
function App() {
return (
<Router>
<div className="mainapp">
<header>
<h1>qiankun Main Application</h1>
<nav>
<Link to="/vue">Vue App</Link>
<Link to="/react">React App</Link>
</nav>
</header>
<main id="subapp-viewport"></main>
</div>
</Router>
);
}
export default App;
npm install -g @vue/cli
vue create vue-micro-app
cd vue-micro-app
Modify src/main.js:
import { createApp } from 'vue';
import { createRouter, createWebHistory } from 'vue-router';
import App from './App.vue';
import routes from './router';
let instance = null;
let router = null;
/**
* Render function
* Two scenarios: called by main app lifecycle / micro app runs independently
*/
function render(props = {}) {
const { container } = props;
router = createRouter({
history: createWebHistory(window.__POWERED_BY_QIANKUN__ ? '/vue' : '/'),
routes,
});
instance = createApp(App);
instance.use(router);
instance.mount(container ? container.querySelector('#app') : '#app');
}
// run independently
if (!window.__POWERED_BY_QIANKUN__) {
render();
}
export async function bootstrap() {
console.log('[vue] vue app bootstraped');
}
export async function mount(props) {
console.log('[vue] props from main framework', props);
render(props);
}
export async function unmount() {
instance.unmount();
instance._container.innerHTML = '';
instance = null;
router = null;
}
Modify vue.config.js:
const { defineConfig } = require('@vue/cli-service');
const packageName = require('./package.json').name;
module.exports = defineConfig({
transpileDependencies: true,
devServer: {
port: 8080,
headers: {
'Access-Control-Allow-Origin': '*',
},
},
configureWebpack: {
output: {
library: `${packageName}-[name]`,
libraryTarget: 'umd',
chunkLoadingGlobal: `webpackJsonp_${packageName}`,
},
},
});
npx create-react-app react-micro-app
cd react-micro-app
npm install react-app-rewired --save-dev
修改 src/index.js:
import React from 'react';
import ReactDOM from 'react-dom';
import './index.css';
import App from './App';
function render(props) {
const { container } = props;
ReactDOM.render(
<App />,
container ? container.querySelector('#root') : document.querySelector('#root')
);
}
if (!window.__POWERED_BY_QIANKUN__) {
render({});
}
export async function bootstrap() {
console.log('[react16] react app bootstraped');
}
export async function mount(props) {
console.log('[react16] props from main framework', props);
render(props);
}
export async function unmount(props) {
const { container } = props;
ReactDOM.unmountComponentAtNode(
container ? container.querySelector('#root') : document.querySelector('#root')
);
}
创建 config-overrides.js:
const { name } = require('./package');
module.exports = {
webpack: (config) => {
config.output.library = `${name}-[name]`;
config.output.libraryTarget = 'umd';
config.output.chunkLoadingGlobal = `webpackJsonp_${name}`;
return config;
},
devServer: function (configFunction) {
return function(proxy, allowedHost) {
const config = configFunction(proxy, allowedHost);
config.port = 3001;
config.headers = {
'Access-Control-Allow-Origin': '*',
};
return config;
};
},
};
Modify scripts in package.json:
{
"scripts": {
"start": "react-app-rewired start",
"build": "react-app-rewired build",
"test": "react-app-rewired test",
"eject": "react-scripts eject"
}
}
# Terminal 1: Start main application
cd main-app
npm start
# Terminal 2: Start Vue micro application
cd vue-micro-app
npm run serve
# Terminal 3: Start React micro application
cd react-micro-app
npm start
If everything is configured correctly, you should see:
::: warning CORS Issues Make sure your micro application's webpack devServer is configured with CORS headers:
headers: {
'Access-Control-Allow-Origin': '*',
}
:::
::: warning Routing Conflicts In integration mode, micro application routing needs to add corresponding prefixes:
// Vue Router
history: createWebHistory(window.__POWERED_BY_QIANKUN__ ? '/vue' : '/')
// React Router
<BrowserRouter basename={window.__POWERED_BY_QIANKUN__ ? '/react' : '/'}>
:::
Congratulations! You have successfully built your first qiankun micro-frontend application. Next you can: