vite-plugin-single-spa

1.1.1 verified Mon Apr 27 auth: no javascript maintenance

Vite plugin (v1.1.1) to convert Vite-based projects into single-spa root or micro-frontend applications. Supports Vite 5, 6, and 7. Maintained by WJSoftware, but now in maintenance-only mode after the author's decision to discontinue feature development due to disputes. Key differentiator: opinionated integration of Vite with single-spa, handling asset naming, FOUC prevention, and CSS lifecycle exports. Provides TypeScript types and ESM-first exports.

Common errors

error Cannot read properties of undefined (reading 'viteMetadata') ↓

cause This error occurred in v0.5.x when using certain Vite versions or configurations.

fix

Upgrade to v0.6.0 or later where this was fixed.

error Error: The plugin 'vite-plugin-single-spa' doesn't support Vite v4. Minimum required version is 5. ↓

cause Vite 4 support was dropped in v0.8.0.

fix

Upgrade Vite to ^5.0.0 or update plugin to v0.7.0.

Warnings

breaking Drop support for Vite v4 in v0.8.0. If using Vite 4, upgrade to Vite 5+ or stay on v0.7.0. ↓

fix Update Vite to ^5.0.0 || ^6.0.0 || ^7.0.0.

deprecated The resolveId hook order changed to 'pre' in v0.9.0. May cause issues with other plugins that assume default order. ↓

fix Ensure compatibility with other Vite plugins that also use resolveId with 'pre' order.

gotcha CSS collection moved to generateBundle hook in v1.1.1 for Vite 6 & 7 compatibility. Ensure your project uses generateBundle if relying on CSS lifecycle exports. ↓

fix Update plugin to v1.1.1 and verify CSS lifecycle works.

gotcha Project is in maintenance mode only (as of 2025-04-13). No new features, only bug fixes. Consider alternatives for long-term support. ↓

fix Evaluate other single-spa integrations or contribute to this project.

gotcha The plugin requires a file src/spa.ts|js|jsx|tsx for micro-frontend projects. Missing this file will cause build errors. ↓

fix Create src/spa.ts exporting lifecycle functions.

Install

npm install vite-plugin-single-spa

yarn add vite-plugin-single-spa

pnpm add vite-plugin-single-spa

Imports

vitePluginSingleSpa

wrong

const vitePluginSingleSpa = require('vite-plugin-single-spa')

correct

import vitePluginSingleSpa from 'vite-plugin-single-spa'

Default export is ESM-only; CommonJS require will fail.

vitePluginSingleSpa
```
import { vitePluginSingleSpa } from 'vite-plugin-single-spa'
```
Also available as a named export, same as default.

type SingleSpaRootPluginOptions

import type { SingleSpaRootPluginOptions } from 'vite-plugin-single-spa'

Type-only import for TypeScript users.

Quickstart

Configures a Vite project as a single-spa root config with import maps and plugin options.

// vite.config.ts
import { defineConfig } from 'vite';
import vitePluginSingleSpa from 'vite-plugin-single-spa';

export default defineConfig({
  plugins: [
    vitePluginSingleSpa({
      type: 'root',
      importMaps: {
        'single-spa': 'https://cdn.jsdelivr.net/npm/single-spa@6.0.1/lib/system/single-spa.min.js'
      }
    })
  ]
});