vite-plugin-qiankun-lite

1.3.0 verified Mon Apr 27 auth: no javascript

vite-plugin-qiankun-lite is a Vite plugin that simplifies integrating qiankun micro-frontend framework into Vite-based applications. Version 1.3.0 supports Vite 4 through 7, maintaining active development with regular releases. Unlike alternatives, it requires no lifecycle function exports or special proxy window imports; just add the plugin. It preserves ES module benefits, provides an experimental JS sandbox, and supports React HMR. The plugin is TypeScript-friendly with bundled type definitions.

Common errors

error TypeError: qiankun is not a function ↓

cause Importing the plugin using named import instead of default import.

fix

Use default import: import qiankun from 'vite-plugin-qiankun-lite'

error Error: [vite] RollupError: "VitePluginQiankunLiteOptions" is not exported by "node_modules/vite-plugin-qiankun-lite/dist/index.mjs" ↓

cause Trying to import the TypeScript type as a runtime value in a JavaScript file.

fix

Remove the import of VitePluginQiankunLiteOptions or use import type.

error ReferenceError: qiankunWindow is not defined ↓

cause Attempting to use qiankunWindow from vite-plugin-qiankun-lite; the plugin does not export it.

fix

Use window directly or refer to qiankun documentation for the proxy window.

error Error: The plugin requires Vite >=4.0.0. Current version: 3.x.x ↓

cause Using an unsupported version of Vite.

fix

Upgrade Vite to version 4, 5, 6, or 7.

Warnings

gotcha The sandbox option is experimental. In sandbox mode, plugins that rely on global variables (e.g., window, document) may not work as expected. ↓

fix Set sandbox: false or test thoroughly with sandbox enabled.

gotcha The plugin automatically prefixes global browser variables (e.g., window, document) when sandbox is enabled. This may break libraries that use dynamic property access on window. ↓

fix Disable sandbox if such issues occur, or update the library to use the proxy window (qiankunWindow) manually.

breaking Plugin does not export lifecycle hooks like exportLifeCycleHooks. Do not expect named exports such as qiankunWindow or hooks. ↓

fix Refer to qiankun documentation for manual lifecycle hook registration; this plugin handles them automatically.

deprecated Usage with Vite 3 is not supported; peer dependency requires Vite >=4. ↓

fix Upgrade Vite to version 4, 5, 6, or 7.

gotcha HMR may not work correctly when sandbox is enabled due to proxy re-initialization. ↓

fix Disable sandbox during development if HMR issues arise.

Install

npm install vite-plugin-qiankun-lite

yarn add vite-plugin-qiankun-lite

pnpm add vite-plugin-qiankun-lite

Imports

default

wrong

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

correct

import qiankun from 'vite-plugin-qiankun-lite'

Default export only; named import will result in undefined.

VitePluginQiankunLiteOptions

wrong

import { VitePluginQiankunLiteOptions } from 'vite-plugin-qiankun-lite'

correct

import type { VitePluginQiankunLiteOptions } from 'vite-plugin-qiankun-lite'

TypeScript type export; does not exist at runtime.

require
```
const qiankun = require('vite-plugin-qiankun-lite')
```
CommonJS usage is supported; but ESM is recommended for Vite projects.

Quickstart

Configures a Vite sub-application with the qiankun plugin, enabling micro-frontend integration with sandbox and HMR.

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import qiankun from 'vite-plugin-qiankun-lite';

export default defineConfig({
  plugins: [
    react(),
    qiankun({
      name: 'my-sub-app',
      sandbox: true, // experimental: enable JS sandbox
    }),
  ],
  server: {
    port: 3001,
    origin: 'http://localhost:3001', // must match the registered app URL
  },
});