{"id":22798,"library":"vite-plugin-qiankun","title":"vite-plugin-qiankun","description":"A Vite plugin that enables seamless integration of Vite-based micro-frontends into the qiankun framework. Version 1.0.15, stable, with moderate release cadence. It preserves Vite's ESM advantages and supports development mode, but note that ESM modules conflict with qiankun's JS sandbox, so the plugin works without sandboxing. You must manually handle global state via `qiankunWindow`. Alternative to using webpack with qiankun.","status":"active","version":"1.0.15","language":"javascript","source_language":"en","source_url":"https://github.com/tengmaoqing/vite-plugin-qiankun","tags":["javascript","qiankun","vite","esm","esModule","typescript"],"install":[{"cmd":"npm install vite-plugin-qiankun","lang":"bash","label":"npm"},{"cmd":"yarn add vite-plugin-qiankun","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-plugin-qiankun","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"core peer dependency for plugin","package":"vite","optional":false},{"reason":"peer dependency for TypeScript support","package":"typescript","optional":true}],"imports":[{"note":"Plugin is ESM-only, no CJS support.","wrong":"const qiankun = require('vite-plugin-qiankun')","symbol":"default","correct":"import qiankun from 'vite-plugin-qiankun'"},{"note":"Must import helper functions from the 'dist/helper' subpath.","wrong":"import { renderWithQiankun } from 'vite-plugin-qiankun'","symbol":"renderWithQiankun","correct":"import { renderWithQiankun } from 'vite-plugin-qiankun/dist/helper'"},{"note":"qiankunWindow is a named export, not default.","wrong":"import qiankunWindow from 'vite-plugin-qiankun/dist/helper'","symbol":"qiankunWindow","correct":"import { qiankunWindow } from 'vite-plugin-qiankun/dist/helper'"},{"note":"Must use the exported qiankunWindow object instead of window.","wrong":"if (window.__POWERED_BY_QIANKUN__) {}","symbol":"qiankunWindow.__POWERED_BY_QIANKUN__","correct":"import { qiankunWindow } from 'vite-plugin-qiankun/dist/helper'; if (qiankunWindow.__POWERED_BY_QIANKUN__) {}"}],"quickstart":{"code":"// vite.config.ts\nimport qiankun from 'vite-plugin-qiankun';\n\nexport default {\n  plugins: [qiankun('myMicroAppName')],\n  base: 'http://localhost:5173/'\n}\n\n// main.ts (React example)\nimport { renderWithQiankun, qiankunWindow } from 'vite-plugin-qiankun/dist/helper';\n\nfunction render(props = {}) {\n  const { container } = props;\n  ReactDOM.render(<App />, container?.querySelector('#root') || document.getElementById('root'));\n}\n\nrenderWithQiankun({\n  mount(props) { render(props); },\n  bootstrap() { console.log('bootstrap'); },\n  unmount(props) {\n    const { container } = props;\n    ReactDOM.unmountComponentAtNode(container?.querySelector('#root') || document.getElementById('root'));\n  }\n});\n\nif (!qiankunWindow.__POWERED_BY_QIANKUN__) {\n  render({});\n}","lang":"typescript","description":"Shows how to install the plugin, configure lifecycle hooks, and handle standalone vs qiankun mode."},"warnings":[{"fix":"Use `qiankunWindow` object instead of `window` to set properties, which provides a lightweight proxy.","message":"No JS sandbox: Because Vite loads ESM modules, qiankun's sandbox is not enabled. Global variables set via `window` may leak to other micro-apps.","severity":"gotcha","affected_versions":"*"},{"fix":"Toggle between `useDevMode: true` (no HMR) and `useDevMode: false` (HMR but not in qiankun).","message":"In development mode, the plugin conflicts with Vite's HMR (e.g., @vitejs/plugin-react-refresh). You cannot use both simultaneously.","severity":"gotcha","affected_versions":"*"},{"fix":"Set `base: 'http://your-deploy-url.com/'` in vite.config.ts.","message":"Must set `base` option in Vite config to the production URL, otherwise assets may not load in qiankun.","severity":"gotcha","affected_versions":"*"},{"fix":"Keep plugin version in sync with Vite version and monitor for breaking changes.","message":"Plugin API may change as it relies on undocumented Vite internals.","severity":"deprecated","affected_versions":">=1.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Add `\"exports\": { \"./dist/helper\": \"./dist/helper.js\" }` to your tsconfig.json or use `// @ts-ignore`.","cause":"TypeScript cannot resolve the helper subpath because it's not exported in package.json 'exports' field.","error":"Cannot find module 'vite-plugin-qiankun/dist/helper' or its corresponding type declarations."},{"fix":"Use `import qiankun from 'vite-plugin-qiankun'` and ensure your project is ESM.","cause":"Using CommonJS `require()` instead of ESM import.","error":"Uncaught SyntaxError: The requested module 'vite-plugin-qiankun' does not provide an export named 'default'"},{"fix":"Set `base: 'http://localhost:5173/'` in vite.config.ts and ensure CORS headers are properly configured.","cause":"In development, the micro-app's origin differs from the main app's origin. Vite dev server's base URL is not correct.","error":"Failed to fetch dynamically imported module: http://localhost:5173/..."},{"fix":"Import `renderWithQiankun` from `'vite-plugin-qiankun/dist/helper'` and call it with the correct lifecycle object.","cause":"The `renderWithQiankun` function was not called correctly or not imported from the correct path.","error":"Lifecycle function 'mount' not triggered when loading micro-app in qiankun."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}