Getting Started with single-spa
Overview of single-spa
- Use multiple frameworks on the same page without page refreshing (React, AngularJS, Angular, Ember, or whatever you're using)
- Deploy your microfrontends independently
- Write code using a new framework, without rewriting your existing app
- Lazy load code for improved initial load time
Demos and Examples
See our examples page.
single-spa takes inspiration from modern framework component lifecycles by abstracting lifecycles for entire applications. Born out of Canopy's desire to use React + react-router instead of being forever stuck with our AngularJS + ui-router application, single-spa is now a mature library that enables frontend microservices architecture aka "microfrontends". Microfrontends enable many benefits such as independent deployments, migration and experimentation, and resilient applications.
single-spa apps consist of the following:
- A name
- A function to load the application's code
- A function that determines when the application is active/inactive
Applications which can be thought of as single-page applications packaged up into modules. Each application must know how to bootstrap, mount, and unmount itself from the DOM. The main difference between a traditional SPA and single-spa applications is that they must be able to coexist with other applications as they do not each have their own HTML page.
For example, your React or Angular SPAs are applications. When active, they can listen to url routing events and put content on the DOM. When inactive, they do not listen to url routing events and are totally removed from the DOM.
The Recommended Setup
The single-spa core team has put together documentation, tools, and videos showing the currently encouraged best practices with single-spa. Check out these docs for more information.
How hard will it be to use single-spa?
single-spa works with ES5, ES6+, TypeScript, Webpack, SystemJS, Gulp, Grunt, Bower, ember-cli, or really any build system available. You can npm install it or even just use a
<script> tag if you prefer.
While our objective is to make using single-spa as easy as possible, we should also note that this is an advanced architecture that is different from how front-end applications are typically done. This will require changes to existing paradigms as well as understanding of underlying tools.
If you're not starting your application from scratch, you'll have to migrate your SPA to become a single-spa application.
single-spa works in Chrome, Firefox, Safari, Edge, and IE11 (with polyfills).
Isn't single-spa sort of a redundant name?
The documentation is divided into several sections:
- Getting Started
- single-spa Applications
- single-spa Parcels
- Contributing Guide
- Where to Get Support
You can help improve the single-spa website by sending pull requests to the
To help beginners to single-spa get started quickly we have developed
create-single-spa, a utility for generating starter code. This guide will cover creating the root-config and your first single-spa application. Let's get started.
:::note Once you've gotten some of the basics down, refer to these other single-spa examples to see more advanced usage. :::
Create a root config
create-single-spato generate a root-config by running:
npx create-single-spa --moduleType root-config
Follow the remaining prompts with a few things in mind:
Once created, navigate into the newly created root-config folder
startscript using your preferred package manager
Navigate to http://localhost:9000/ in your browser
You now have a working root-config!
Be sure to review the comments inside the generated code as well as the information in the Welcome application even if some of the content is duplicated in this guide.
:::tip single-spa-playground.org is an alternative guide to run an application without needing to create your own root-config. :::
Create a single-spa application
create-single-spato generate a single-spa application by running:
npx create-single-spa --moduleType app-parcel
Follow the remaining prompts to generate a single-spa application using your framework of choice
Once created, navigate into the newly created application folder
startscript using your preferred package manager
Add shared dependencies
Shared dependencies are used to improve performance by sharing a module in the browser through import maps declared in the root-config. Adding these at this point is conditionally optional, depending on if the generated application expects any shared dependencies.
For example, if using React the generated Webpack config already expects
ReactDOM to be shared dependencies, so you must add these to the import map. Vue, Angular, and Svelte don't require shared dependencies at this time.
"react": "https://firstname.lastname@example.org/umd/react.production.min.js", "react-dom": "https://email@example.com/umd/react-dom.production.min.js"
As your architecture matures, you may add more shared dependencies in the future so don't stress about leveraging these perfectly at first.
Register the application
Return to the root-config and add your application to the import map in
The application's package.json name field is recommended
Register as a single-spa application
if not using single-spa Layout Engine
- Remove the code for registering
@single-spa/welcomeas an application
- Uncomment the sample
registerApplicationcode and update it with the module name of your application
if using single-spa Layout Engine
- Remove the existing
- Add your own
<application name=""></application>element using the
namethe module name used in the import map from the previous step
Thats it! Your first single-spa application should now be running in your root-config.
The main purpose of this repository is to continue to evolve single-spa, making it better and easier to use. Development of single-spa, and the single-spa ecosystem happens in the open on GitHub, and we are grateful to the community for contributing bugfixes and improvements. Read below to learn how you can take part in improving single-spa.
single-spa has adopted a Code of Conduct that we expect project participants to adhere to. Please read the full text so that you can understand what actions will and will not be tolerated.
Read our contributing guide to learn about our development process, how to propose bugfixes and improvements, and how to build and test your changes to single-spa.
Who's Using This?
See user showcase.
Is your company or project using single-spa? Let us know by submitting a PR to this section!