qiankun-plugin-vite

0.2.9 verified Mon Apr 27 auth: no javascript

A Vite plugin (v0.2.9) for integrating micro-apps with Qiankun, supporting ES modules and HMR in development. Maintains Vite's fast build while adding Qiankun lifecycle hooks and sandbox window. Releases are infrequent with minor patches. Unlike qiankun's own plugin, this one uses a separate helper import for lifecycle utilities and explicitly avoids JavaScript sandbox in favor of manual qiankunWindow usage. Requires Vite >=2 and TypeScript >=4. Current version is stable and feature-complete.

Common errors

error Cannot find module 'asma-qiankun-plugin-vite/helper' ↓

cause Import path does not include '/helper' or module resolution is misconfigured.

fix

Use import { generateQiankunHelpers } from 'asma-qiankun-plugin-vite/helper' (note the subpath).

error TypeError: qiankun is not a function ↓

cause Default import used instead of named import.

fix

Use import { qiankun } from 'asma-qiankun-plugin-vite' (curly braces).

error Uncaught TypeError: Cannot set properties of undefined (setting 'customxxx') ↓

cause qiankunWindow is undefined because generateQiankunHelpers was not called or incorrect import path.

fix

Ensure correct import and invocation: const { qiankunWindow } = generateQiankunHelpers('myMicroAppName'); then use qiankunWindow.customxxx = 'ssss'.

Warnings

gotcha ES module loading conflicts with Qiankun's JavaScript sandbox. Micro-apps do NOT run inside sandbox; window assignments may leak. ↓

fix Always use qiankunWindow from generateQiankunHelpers instead of window for shared state.

gotcha useDevMode conflicts with hot-reload plugins like @vitejs/plugin-react-refresh. Disable hot-reload when useDevMode=true. ↓

fix Conditionally exclude hot-reload plugin when useDevMode is enabled: e.g., ...(useDevMode ? [] : [reactRefresh()])

breaking qiankunWindow and renderWithQiankun are only accessible via generateQiankunHelpers('appName'), not direct imports from the package. ↓

fix Replace direct imports with destructured calls to generateQiankunHelpers.

gotcha The 'appName' argument to qiankun() and generateQiankunHelpers() must match the host's registered app name exactly. ↓

fix Ensure both calls use the same string, typically defined in the host's registerMicroApps.

Install

npm install asma-qiankun-plugin-vite

yarn add asma-qiankun-plugin-vite

pnpm add asma-qiankun-plugin-vite

Imports

qiankun

wrong

import qiankun from 'asma-qiankun-plugin-vite';

correct

import { qiankun } from 'asma-qiankun-plugin-vite';

qiankun is a named export, not default.

generateQiankunHelpers

wrong

import { generateQiankunHelpers } from 'asma-qiankun-plugin-vite';

correct

import { generateQiankunHelpers } from 'asma-qiankun-plugin-vite/helper';

Helpers are exported from the submodule 'helper', not main entry.

qiankunWindow

wrong

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

correct

import { generateQiankunHelpers } from 'asma-qiankun-plugin-vite/helper'; const { qiankunWindow } = generateQiankunHelpers('appName');

qiankunWindow is not a direct export; you must call generateQiankunHelpers to obtain it.

Quickstart

Configures Vite with the qiankun plugin, then sets up Qiankun lifecycle hooks and conditional rendering based on sandbox flag.

// vite.config.ts
import { qiankun } from 'asma-qiankun-plugin-vite';

export default {
  plugins: [qiankun('myMicroAppName')],
  base: 'http://xxx.com/'
}

// main.ts
import { generateQiankunHelpers } from 'asma-qiankun-plugin-vite/helper';
const { renderWithQiankun, qiankunWindow } = generateQiankunHelpers('myMicroAppName');

renderWithQiankun({
  mount(props) {
    console.log('mount');
    const { container } = props;
    const root = container?.querySelector('#root') || document.querySelector('#root');
    ReactDOM.render(<App />, root);
  },
  bootstrap() { console.log('bootstrap'); },
  unmount(props: any) {
    const { container } = props;
    const root = container?.querySelector('#root') || document.querySelector('#root');
    ReactDOM.unmountComponentAtNode(root);
  },
});

if (!qiankunWindow.__POWERED_BY_QIANKUN__) {
  ReactDOM.render(<App />, document.querySelector('#root'));
}