Vue CLI Plugin for single-spa

Common errors

• ERROR Cannot use import statement outside a module

  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.
  fix Add `pluginOptions['single-spa'].outputSystemJS: true` to your `vue.config.js` file to revert to UMD/SystemJS compatible output.

• Webpack build fails with module not found errors for 'single-spa' or other single-spa related packages.

  cause Webpack might not be correctly configured to treat `single-spa` and its related libraries as external dependencies, leading to bundling issues.
  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.

• TypeError: 'this' is undefined or 'app.use' is not a function when loading the Vue microfrontend.

  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.
  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.

Warnings

• breaking 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.
  Fix: To revert to UMD/SystemJS compatible output, add `pluginOptions['single-spa'].outputSystemJS: true` to your `vue.config.js` file.
• breaking 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.
  Fix: To upgrade, run `vue add single-spa@3`. If issues persist, consult the `standalone-single-spa-webpack-plugin` documentation for version 3.
• gotcha 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  Fix: Only install packages from trusted sources and consider using npm/yarn integrity checks or security scanning tools.

Install

• npm install vue-cli-plugin-single-spa npm
• yarn add vue-cli-plugin-single-spa yarn
• pnpm add vue-cli-plugin-single-spa pnpm

Imports

• N/A (CLI Command)

  vue add single-spa

  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.
• singleSpaVue
  wrong:

  import { singleSpaVue } from 'single-spa-vue'

  correct:

  import singleSpaVue from 'single-spa-vue'

  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.
• defineApplication
  wrong:

  import defineApplication from 'single-spa'

  correct:

  import { defineApplication } from 'single-spa'

  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.

Quickstart

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.

{
  // Step 1: Create a new Vue project (if you don't have one)
  // vue create my-single-spa-app
  // cd my-single-spa-app

  // Step 2: Add the single-spa plugin
  // Run this command in your project's root directory:
  // vue add single-spa@latest

  // The plugin will modify your main.ts (or main.js) to look similar to this:
  // main.ts (or main.js)
  import { h, createApp } from 'vue';
  import singleSpaVue from 'single-spa-vue';
  import App from './App.vue';
  // import router from './router'; // Uncomment if you have vue-router installed
  // import store from './store'; // Uncomment if you have Vuex installed

  const vueLifecycles = singleSpaVue({
    createApp,
    appOptions: {
      render() {
        return h(App, {
          props: {
            // single-spa props are passed as "custom props" to the root component
            name: this.name,
            mountParcel: this.mountParcel,
            singleSpa: this.singleSpa
          }
        });
      },
      // Uncomment the following if you use Vuex or Vue Router
      // el: '#app', // Not typically needed for single-spa apps unless rendering standalone
    },
    handleInstance(app) {
      // app.use(router); // Apply vue-router
      // app.use(store);  // Apply Vuex store
    },
  });

  export const bootstrap = vueLifecycles.bootstrap;
  export const mount = vueLifecycles.mount;
  export const unmount = vueLifecycles.unmount;
}