Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–223 runs
build_error
glibcnode 18–223 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
default
✓ import qiankun from 'vite-plugin-qiankun'
✗ const qiankun = require('vite-plugin-qiankun')
Plugin is ESM-only, no CJS support.
renderWithQiankun
✓ import { renderWithQiankun } from 'vite-plugin-qiankun/dist/helper'
✗ import { renderWithQiankun } from 'vite-plugin-qiankun'
Must import helper functions from the 'dist/helper' subpath.
qiankunWindow
✓ import { qiankunWindow } from 'vite-plugin-qiankun/dist/helper'
✗ import qiankunWindow from 'vite-plugin-qiankun/dist/helper'
qiankunWindow is a named export, not default.
qiankunWindow.__POWERED_BY_QIANKUN__
✓ import { qiankunWindow } from 'vite-plugin-qiankun/dist/helper'; if (qiankunWindow.__POWERED_BY_QIANKUN__) {}
✗ if (window.__POWERED_BY_QIANKUN__) {}
Must use the exported qiankunWindow object instead of window.
Shows how to install the plugin, configure lifecycle hooks, and handle standalone vs qiankun mode.
// vite.config.ts
import qiankun from 'vite-plugin-qiankun';
export default {
plugins: [qiankun('myMicroAppName')],
base: 'http://localhost:5173/'
}
// main.ts (React example)
import { renderWithQiankun, qiankunWindow } from 'vite-plugin-qiankun/dist/helper';
function render(props = {}) {
const { container } = props;
ReactDOM.render(<App />, container?.querySelector('#root') || document.getElementById('root'));
}
renderWithQiankun({
mount(props) { render(props); },
bootstrap() { console.log('bootstrap'); },
unmount(props) {
const { container } = props;
ReactDOM.unmountComponentAtNode(container?.querySelector('#root') || document.getElementById('root'));
}
});
if (!qiankunWindow.__POWERED_BY_QIANKUN__) {
render({});
}
Errors
Common errors & fixes
Cannot find module 'vite-plugin-qiankun/dist/helper' or its corresponding type declarations.
TypeScript cannot resolve the helper subpath because it's not exported in package.json 'exports' field.
fixAdd `"exports": { "./dist/helper": "./dist/helper.js" }` to your tsconfig.json or use `// @ts-ignore`. Uncaught SyntaxError: The requested module 'vite-plugin-qiankun' does not provide an export named 'default'
Using CommonJS `require()` instead of ESM import.
fixUse `import qiankun from 'vite-plugin-qiankun'` and ensure your project is ESM.
Failed to fetch dynamically imported module: http://localhost:5173/...
In development, the micro-app's origin differs from the main app's origin. Vite dev server's base URL is not correct.
fixSet `base: 'http://localhost:5173/'` in vite.config.ts and ensure CORS headers are properly configured.
Lifecycle function 'mount' not triggered when loading micro-app in qiankun.
The `renderWithQiankun` function was not called correctly or not imported from the correct path.
fixImport `renderWithQiankun` from `'vite-plugin-qiankun/dist/helper'` and call it with the correct lifecycle object.
Audit
Dependencies
viterequiredcore peer dependency for plugin
typescriptoptionalpeer dependency for TypeScript support