single-spa-vue
single-spa-vue is a helper library that helps implement single-spa registered application lifecycle functions (bootstrap, mount and unmount) for use with Vue.js. Check out the single-spa-vue github.
#
ExampleFor a full example, see vue-microfrontends.
#
Live demohttps://coexisting-vue-microfrontends.surge.sh
#
Installation#
Vue CLIThe vue-cli-plugin-single-spa will get everything set up.
The CLI Plugin does the following for you:
- Modify your webpack config so that your project works as a single-spa application or parcel.
- Install single-spa-vue.
- Modify your
main.js
ormain.ts
file so that your project works as a single-spa application or parcel. - Add a
set-public-path.js
that will usesystemjs-webpack-interop
in order to set the public path of your application.
#
Without Vue CLIAlternatively, you can use single-spa-vue by adding <script src="https://unpkg.com/single-spa-vue"></script>
to your HTML file and
accessing the singleSpaVue
global variable.
#
UsageInstall systemjs-webpack-interop
if you have not already done so.
npm install systemjs-webpack-interop -S
Create a file at the same level as your main.js/ts
called set-public-path.js
Note that if you are using the Vue CLI Plugin, your main.ts
or main.js
file will be updated with this code automatically and the set-public-path.js
file
will automatically be created with the app name being your package.json's name property.
If you want to deal with your Vue instance, you can modify the mount method by following this. mount method will return Promise with Vue instance after v1.6.0.
#
Vue 2For Vue 2, change your application's entry file to be the following:
#
Vue 3For Vue 3, change your application's entry file to be the following:
#
Custom propsSingle-spa custom props can be passed to your root component like so:
#
Shared dependenciesFor performance, it is best to share a single version and instance of Vue, Vue Router, and other large libraries.
To do this, add your shared dependencies as webpack externals. Then you use
an in-browser module loader such as systemjs to provide those shared dependencies
to each of the single-spa applications. Adding vue
and other libraries to your
import map. For an example import map that is doing this,
checkout coexisting-vue-microfrontends' index.html file.
Sharing a single instance of Vue and other common libraries is highly recommended. See the recommended setup for single-spa for more details on why.
#
Shared deps with Vue CLI#
Shared deps without Vue CLI#
OptionsAll options are passed to single-spa-vue via the opts
parameter when calling singleSpaVue(opts)
. The following options are available:
Vue
: (required) The main Vue object, which is generally either exposed onto the window or is available viarequire('vue')
import Vue from 'vue'
.appOptions
: (required) An object or async function which will be used to instantiate your Vue.js application.appOptions
will pass directly through tonew Vue(appOptions)
. Note that if you do not provide anel
to appOptions, that a div will be created and appended to the DOM as a default container for your Vue application.loadRootComponent
: (optional and replacesappOptions.render
) A promise that resolves with your root component. This is useful for lazy loading.handleInstance
: (optional) A method can be used to handle Vue instance. Vue 3 brings new instance API, and you can access the app instance from this, likehandleInstance: (app) => app.use(router)
. For Vue 2 users, a Vue instance can be accessed.replaceMode
: (optional, defaults tofalse
) A boolean that determines whether your root Vue component will entirely replace the container element it's mounted to. The Vue library always replaces, so to implementreplaceMode: false
a temporary<div class="single-spa-container">
element is created inside of the container, so that Vue replaces that element rather than the container. Introduced in single-spa-vue@2.3.0.
To configure which dom element the single-spa application is mounted to, use appOptions.el:
To configure options asynchronously return a promise from appOptions function:
#
Custom Propssingle-spa custom props are available in the render()
function in your main file. They can be passed as custom props to your App component.
#
Parcels#
Creating a parcelA parcel config is an object that represents a component implemented in Vue, React, Angular, or any other framework.
To create a VueJS single-spa parcel config object, simply omit the el
option from your appOptions, since the dom element will be specified by the user of the Parcel. Every other
option should be provided exactly the same as in the example above.
#
Rendering a parcelTo render a parcel config object in Vue, you can use single-spa-vue's Parcel
component:
#
Webpack Public Pathvue-cli-plugin-single-spa sets the webpack public path via SystemJSPublicPathWebpackPlugin. By default, the public path is set to match the following output directory structure:
With this directory structure (which is the Vue CLI default), the public path should not include the js
folder. This is accomplished by setting rootDirectoryLevel
to be 2
. If this doesn't match your directory structure or setup, you can change the rootDirectoryLevel
with the following code in your vue.config.js or webpack.config.js: