vite-plugin-single-spa weekly downloads statistics

vite-plugin-single-spa

Vite plug-in to convert Vite-based projects to single-spa root or micro-frontend applications.

This Vite plug-in is an opinionated way of making Vite-based front-end projects work with single-spa.

[!IMPORTANT] Due to false accusations raised against me by the author of single-spa Jolyn Denning, I will discontinue this plug-in. As of today, 2025-04-13, this plug-in will only accept bug reports and will only get bug fixes. No new features will be developed for this plug-in.

For reference, this is what Jolyn wrote at the single-spa Slack channel.

Whatever problems Jolyn may be going through right now do not invalidate single-spa, at least as of the current version. I will not, however, continue the journey as single-spa progresses (if it progresses at all).

I will instead be publishing a new library for micro-frontends since I still have the need at work. I will be pushing single-spa out of my work projects because I fear the long term stability of single-spa.

Quickstart

NOTE: This document assumes the use of TypeScript Vite projects. However, all of this applies to JavaScript projects as well. Just know that any file name with extension .ts probably exists as a .js file.

Install the NPM package as a development dependency.

npm i -D vite-plugin-single-spa

In reality, what is installed as development dependency is a matter of how you build your final product. For example, if you want to use npm with --omit=dev to build the project, then you'll need all packages used by Vite's build command to have been installed as regular dependencies. It is up to you how you end up installing the package (dev or regular).

Now, in vite.config.ts, import the vitePluginSingleSpa function from it. It is the default export but it is also a named export:

// Either works.
import vitePluginSingleSpa from 'vite-plugin-single-spa';
import { vitePluginSingleSpa } from 'vite-plugin-single-spa';

This is the plug-in factory function. Create the plug-in by invoking the function. Pass the plug-in options as argument to the function call. The following is the content of vite.config.ts of a Vite + Svelte project created with npm create vite@latest.

import { svelte } from '@sveltejs/vite-plugin-svelte';
import { defineConfig } from 'vite';
import vitePluginSingleSpa from 'vite-plugin-single-spa';

// https://vitejs.dev/config/
export default defineConfig({
    plugins: [svelte(), vitePluginSingleSpa({ /* options go here */})],
});

The options passed to the plug-in factory function determine the type of project (root or micro-frontend). For micro-frontend projects, the server port is required, while for root projects the type is required.

Additionally for micro-frontend projects, the file src/spa.ts|js|jsx|tsx must be created. This file becomes the main export of the project and should export the single-spa lifecycle functions.

single-spa Root Projects

The single-spa root project (referred to as root config within the single-spa documentation) is the project that loads all other micro-frontends and the one that has the single-spa package installed, and the one that typically calls registerApplication() and start(). The single-spa developers advertise as a best practice to make a root project that uses no framework. In other words, that your root project be devoided of all user interface elements. This is a view I don't share, and this plug-in is capable of making a suitable Vite + XXX root project. In the end, the choice is yours.

Root Project Options

The plug-in options available to root projects are dictated by the following TypeScript type:

export type SingleSpaRootPluginOptions = {
    type: 'root';
    importMaps?: {
        type?: 'importmap' | 'overridable-importmap' | 'systemjs-importmap' | 'importmap-shim';
        dev?: string | string[];
        build?: string | string[];
    };
    imo?: boolean | string | (() => string);
    imoUi?: boolean | 'full' | 'popup' | 'list' | {
        variant?: boolean | 'full' | 'popup' | 'list';
        buttonPos?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
        localStorageKey?: string;
    };
};

The type property is mandatory for root projects and must be the string 'root', as seen. The other options pertain to the use of import maps and the import-map-overrides package. Long story short: Vite, while in development mode, inserts the script @vite/client as first child in the HTML page's <head> element, and this makes the import maps non-functional, at least for the native importmap type. The solution: Make this plug-in add both the import map script and the import-map-overrides package as first children of the <head> HTML element. Why did I tell the story? Just so you know that it is impossible to use import-map-overrides with Vite "by hand" in serve mode.

The imo option is used to control the inclusion of import-map-overrides. Set it to false to exclude it; set to true to include its latest version from JSDelivr. However, production deployments should never let unknown versions of packages to be loaded without prior testing, so it really isn't good practice to just say "include the latest version". Instead, specify the desired package version as a string.

Check for releases of import-map-overrides.

vitePluginSingleSpa({
    type: 'root',
    imo: '4.2.0'
})

Just like the case of the latest version, this will also use the JSDelivr network.

IMPORTANT: Even if you request import-map-overrides to be included, it won't be included if no import maps are present.…