{"id":12426,"library":"vue-cli-plugin-single-spa","title":"Vue CLI Plugin for single-spa","description":"vue-cli-plugin-single-spa is an official plugin for Vue CLI that streamlines the process of integrating Vue applications into a single-spa microfrontend architecture. It automatically handles the necessary Webpack configuration and scaffolding to transform a standard Vue project into a single-spa microfrontend or parcel. The current stable version is 4.0.0, which notably shifted the default Webpack output module format to native ES modules. The project maintains a moderate release cadence, with consistent updates addressing Webpack compatibility, security, and feature enhancements. Its primary differentiator is its deep integration with the Vue CLI ecosystem, offering a simplified developer experience for creating single-spa compatible Vue applications without extensive manual Webpack configuration.","status":"active","version":"4.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/single-spa/vue-cli-plugin-single-spa","tags":["javascript"],"install":[{"cmd":"npm install vue-cli-plugin-single-spa","lang":"bash","label":"npm"},{"cmd":"yarn add vue-cli-plugin-single-spa","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue-cli-plugin-single-spa","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required for the plugin's build processes.","package":"webpack","optional":false}],"imports":[{"note":"This is the primary method for 'importing' and integrating the vue-cli-plugin-single-spa plugin into an existing Vue CLI project, which configures the project for single-spa.","symbol":"N/A (CLI Command)","correct":"vue add single-spa"},{"note":"This is the core utility from the `single-spa-vue` library, which `vue-cli-plugin-single-spa` configures your Vue application to use. It's a default export and wraps your Vue app lifecycle for single-spa.","wrong":"import { singleSpaVue } from 'single-spa-vue'","symbol":"singleSpaVue","correct":"import singleSpaVue from 'single-spa-vue'"},{"note":"While not directly from `vue-cli-plugin-single-spa`, this is a crucial symbol from the `single-spa` library that applications configured by the plugin will typically use in their root configuration to register the Vue microfrontend. It is a named export.","wrong":"import defineApplication from 'single-spa'","symbol":"defineApplication","correct":"import { defineApplication } from 'single-spa'"}],"quickstart":{"code":"{\n  // Step 1: Create a new Vue project (if you don't have one)\n  // vue create my-single-spa-app\n  // cd my-single-spa-app\n\n  // Step 2: Add the single-spa plugin\n  // Run this command in your project's root directory:\n  // vue add single-spa@latest\n\n  // The plugin will modify your main.ts (or main.js) to look similar to this:\n  // main.ts (or main.js)\n  import { h, createApp } from 'vue';\n  import singleSpaVue from 'single-spa-vue';\n  import App from './App.vue';\n  // import router from './router'; // Uncomment if you have vue-router installed\n  // import store from './store'; // Uncomment if you have Vuex installed\n\n  const vueLifecycles = singleSpaVue({\n    createApp,\n    appOptions: {\n      render() {\n        return h(App, {\n          props: {\n            // single-spa props are passed as \"custom props\" to the root component\n            name: this.name,\n            mountParcel: this.mountParcel,\n            singleSpa: this.singleSpa\n          }\n        });\n      },\n      // Uncomment the following if you use Vuex or Vue Router\n      // el: '#app', // Not typically needed for single-spa apps unless rendering standalone\n    },\n    handleInstance(app) {\n      // app.use(router); // Apply vue-router\n      // app.use(store);  // Apply Vuex store\n    },\n  });\n\n  export const bootstrap = vueLifecycles.bootstrap;\n  export const mount = vueLifecycles.mount;\n  export const unmount = vueLifecycles.unmount;\n}","lang":"typescript","description":"This quickstart demonstrates how to add the `single-spa` plugin to a Vue CLI project and shows the typical structure of the generated `main.ts` file, setting up the Vue application as a single-spa microfrontend."},"warnings":[{"fix":"To revert to UMD/SystemJS compatible output, add `pluginOptions['single-spa'].outputSystemJS: true` to your `vue.config.js` file.","message":"With v4.0.0, the default output module format now defaults to native ES modules (`\"libraryTarget\": \"module\"` in webpack). This may cause compatibility issues with older single-spa root configurations that expect UMD or SystemJS module formats.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"To upgrade, run `vue add single-spa@3`. If issues persist, consult the `standalone-single-spa-webpack-plugin` documentation for version 3.","message":"Version 3.0.0 upgraded the underlying `standalone-single-spa-webpack-plugin` from v1 to v3. While most projects can safely upgrade, it's recommended to review the breaking changes for `standalone-single-spa-webpack-plugin` if you encounter unexpected build or runtime issues.","severity":"breaking","affected_versions":">=3.0.0 <4.0.0"},{"fix":"Ensure you are using `vue-cli-plugin-single-spa` v3.3.0 or higher when working with Webpack 5 to ensure proper compatibility and stability.","message":"Version 3.3.0 introduced critical fixes for Webpack 5 compatibility. Using versions prior to 3.3.0 with Webpack 5 may lead to build failures or unexpected behavior.","severity":"gotcha","affected_versions":"<3.3.0"},{"fix":"Refer to the plugin's GitHub releases or `package.json` for recommended Webpack versions. Upgrade or downgrade your `webpack` dependency accordingly, typically managed by Vue CLI.","message":"This plugin relies on `webpack` as a peer dependency. Incompatibility between the plugin's expected Webpack version and your project's installed Webpack version can lead to build errors. Ensure your `webpack` version is compatible.","severity":"gotcha","affected_versions":"*"},{"fix":"Only install packages from trusted sources and consider using npm/yarn integrity checks or security scanning tools.","message":"As a CLI plugin that generates and modifies project configurations, it's crucial to ensure supply chain security. Always verify the source and integrity of downloaded packages to mitigate risks.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Add `pluginOptions['single-spa'].outputSystemJS: true` to your `vue.config.js` file to revert to UMD/SystemJS compatible output.","cause":"With vue-cli-plugin-single-spa v4.0.0+, the default Webpack output format is native ES modules, which may conflict with environments expecting UMD or SystemJS.","error":"ERROR Cannot use import statement outside a module"},{"fix":"Ensure `single-spa` is correctly marked as a Webpack external. While the plugin handles this, custom Webpack configurations in `vue.config.js` might override it. Verify `webpack-chain` or `configureWebpack` modifications are not interfering.","cause":"Webpack might not be correctly configured to treat `single-spa` and its related libraries as external dependencies, leading to bundling issues.","error":"Webpack build fails with module not found errors for 'single-spa' or other single-spa related packages."},{"fix":"Verify that your `main.js` (or entry file) exports the `bootstrap`, `mount`, and `unmount` functions returned by `singleSpaVue({})` and that `createApp` is correctly passed. Ensure `app.use()` calls for plugins like Vue Router or Vuex are inside the `handleInstance` callback.","cause":"Vue's instance creation or lifecycle hooks are not correctly integrated with `single-spa-vue`'s `bootstrap`, `mount`, and `unmount` functions, or the Vue instance isn't properly created.","error":"TypeError: 'this' is undefined or 'app.use' is not a function when loading the Vue microfrontend."}],"ecosystem":"npm"}