vite-plugin-qiankun

1.0.15 verified Mon Apr 27 auth: no javascript

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.

Common errors

error Cannot find module 'vite-plugin-qiankun/dist/helper' or its corresponding type declarations. ↓

cause TypeScript cannot resolve the helper subpath because it's not exported in package.json 'exports' field.

fix

Add "exports": { "./dist/helper": "./dist/helper.js" } to your tsconfig.json or use // @ts-ignore.

error Uncaught SyntaxError: The requested module 'vite-plugin-qiankun' does not provide an export named 'default' ↓

cause Using CommonJS `require()` instead of ESM import.

fix

Use import qiankun from 'vite-plugin-qiankun' and ensure your project is ESM.

error Failed to fetch dynamically imported module: http://localhost:5173/... ↓

cause In development, the micro-app's origin differs from the main app's origin. Vite dev server's base URL is not correct.

fix

Set base: 'http://localhost:5173/' in vite.config.ts and ensure CORS headers are properly configured.

error Lifecycle function 'mount' not triggered when loading micro-app in qiankun. ↓

cause The `renderWithQiankun` function was not called correctly or not imported from the correct path.

fix

Import renderWithQiankun from 'vite-plugin-qiankun/dist/helper' and call it with the correct lifecycle object.

Warnings

gotcha 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. ↓

fix Use `qiankunWindow` object instead of `window` to set properties, which provides a lightweight proxy.

gotcha In development mode, the plugin conflicts with Vite's HMR (e.g., @vitejs/plugin-react-refresh). You cannot use both simultaneously. ↓

fix Toggle between `useDevMode: true` (no HMR) and `useDevMode: false` (HMR but not in qiankun).

gotcha Must set `base` option in Vite config to the production URL, otherwise assets may not load in qiankun. ↓

fix Set `base: 'http://your-deploy-url.com/'` in vite.config.ts.

deprecated Plugin API may change as it relies on undocumented Vite internals. ↓

fix Keep plugin version in sync with Vite version and monitor for breaking changes.

Install

npm install vite-plugin-qiankun

yarn add vite-plugin-qiankun

pnpm add vite-plugin-qiankun

Imports

default

wrong

const qiankun = require('vite-plugin-qiankun')

correct

import qiankun from 'vite-plugin-qiankun'

Plugin is ESM-only, no CJS support.

renderWithQiankun

wrong

import { renderWithQiankun } from 'vite-plugin-qiankun'

correct

import { renderWithQiankun } from 'vite-plugin-qiankun/dist/helper'

Must import helper functions from the 'dist/helper' subpath.

qiankunWindow

wrong

import qiankunWindow from 'vite-plugin-qiankun/dist/helper'

correct

import { qiankunWindow } from 'vite-plugin-qiankun/dist/helper'

qiankunWindow is a named export, not default.

qiankunWindow.__POWERED_BY_QIANKUN__

wrong

if (window.__POWERED_BY_QIANKUN__) {}

correct

import { qiankunWindow } from 'vite-plugin-qiankun/dist/helper'; if (qiankunWindow.__POWERED_BY_QIANKUN__) {}

Must use the exported qiankunWindow object instead of window.

Quickstart

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({});
}