single-spa / single-spa

The router for easy microfrontends

single-spa

Join the chat on Slack

Donate to this project

Official single-spa hosting

A javascript framework for front-end microservices

Build micro frontends that coexist and can (but don't need to) be written with their own framework. This allows you to:

• Use multiple frameworks on the same page without refreshing the page (React, AngularJS, Angular, Ember, or whatever you're using)
• Write new code, possibly with a new framework, without rewriting your existing app
• Lazy load code for improved initial load time.

Sponsors

To add your company's logo to this section:

• Become a recurring Open Collective sponsor of at least $100 a month.
• Become a recurring Github sponsor of at least $100 a month.
• Sponsor a core team member to implement a specific feature for single-spa. Pay our regular consulting rate. Inquire in our Slack workspace.

Documentation

You can find the single-spa documentation on the website.

Check out the Getting Started page for a quick overview.

Demo and examples

Please see the examples page on the website.

Want to help?

Want to file a bug, contribute some code, or improve documentation? Excellent! Read up on our guidelines for contributing on the single-spa website.

Contributing

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.

Code of Conduct

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.

Contributing Guide

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.

single-spa's Issues

The eventArguments given to enqueued calls to reroute are not ever given to the captured event listeners.

When we call callCapturedEventListeners, it only calls the captured event listeners with the current eventArguments, but not any previously queued eventArguments. See https://github.com/CanopyTax/single-spa/blob/e365390ff4fd0ac879edc9b6fc0ae2665b7cc7fa/src/navigation/reroute.js#L99. This matters because the first eventArguments sometimes is a PopStateEvent, and subsequently queued calls have a HashChangeEvent eventArguments. Because there are different event listeners for popstate and hashchange, this is a problem because the hashchange listeners will never be called.

Non-hash navigation (with pushState) isn't working in ms edge

Don't log errors twice

Add a `single-spa:first-mount` event

I could see this being useful for a variety of reasons, but here are a couple I can think of right now:

• Show a visual loading bar before single-spa apps are mounted, but then get rid of the loader once the first app is mounted. Although this could maybe better be served with a bootstrap hook in the apps, or maybe a single-spa:before-first-mount event so that the loading bar doesn't show up temporarily while apps are mounting.
• Perform initialization logic that, for performance reasons, you want to defer until after the single-spa apps are up and running.
• Time how long it takes to initialize the first app in your application.

From an implementation standpoint, I think this could be as simple as dispatching a CustomEvent inside of the mount lifecycle, and just keep track of if it has ever been fired before or not.

Build a dist file and make it the one that's referenced in the package.json

We'll just have to make sure that the single-spa-examples work once using the dist file.

Create `unload` lifecycle and `unloadChildApplication` API

This is something the Dealer Socket guys have implemented and found useful for their iframe loading solution. It should work something like this:

// We've decided that this should be unloaded
import {unloadChildApplication} from 'single-spa';
unloadChildApplication('app-name', {waitForUnmount: true});

// Inside of the 'app-name' app
export async function unload() {
  // Do something special here, on a per-app basis
  SystemJS.delete('app-name');
}

This lifecycle would be the first optional lifecycle. What the unloadChildApplication API will do is set the app.status to NOT_LOADED, after calling the unload lifecyle.

An open question is what the default behavior for waitForUnmount should be, and whether this is something that should be configurable or not.

document.importNode causes race conditions?

joeldenning/single-spa@3bac030#diff-b91812c2eab4fbf92962784c8ce887c0R339 caused the bower-angular-phonecat example in single-spa-examples to break (probably because of a race condition). Need to investigate what's going on with importNode and if it is single-spa-angular1's fault or single-spa's fault.

jquery support hasInitialized should be removed in favor of per-jquery flag for initialization

See https://github.com/CanopyTax/single-spa/blob/master/src/jquery-support.js#L3. The problem is that if you have multiple jquerys, only one of them would be compatible with single-spa

Pass `childAppName` to lifecycle functions

Right now lifecycle functions are not given any arguments. This proposal is to give it arguments, maybe an object with a childAppName string

Transition between apps

single-spa doesn't preserve script/html load order

New API. CheckActivityFunction

To enable Server rendering we're going to at least need an API that allows the parent Application to ask Single-spa which children should be active given an arbitrary URL

support for nested apps

Performance improvement -- don't wait for all apps to finish bootstrapping / unmounting before starting mounting

Add documentation for events single spa fires

https://github.com/CanopyTax/single-spa/blob/master/src/navigation/reroute.js#L132-L135

Add `getAppNames` api

Similar to getMountedApps, except it gives you all of the apps that have ever been declared.

CustomEvent constructor not supported in IE

Need to polyfill it, as described in http://stackoverflow.com/questions/19345392/why-arent-my-parameters-getting-passed-through-to-a-dispatched-event/19345563#19345563

Does single-spa support retrieving apps from a different domain?

I have multiple react applications served on different servers (domains). Can I use single-spa to create a root application that includes these apps as child apps?

Something like this:
singleSpa.declareChildApplication('app1', () => import('http://localhost/MyReactApp/src/child-app.js'), hashPrefix('/app1'));

Support exporting lifecycle function that's just an empty array

It should be the equivalent to exporting Promise.resolve().

To help applications that are tested and import single-spa, don't use window during initial import of single-spa

This will help for people who import 'single-spa' in their tests that are run in a non-browser environment.

app2 not deactivated

Hi,
first of all great work!
I'm trying to use your example to see if this tool fit with my requirement and in the angular2 application I tried to add a simple router example. the angular 2 works great but when I try to switch to react (after angular2 has been loaded) it fail because angular2 is not unmounted and it try to find the path app1.

this is the repository that I created: https://github.com/daniele-zurico/microservice-test

Adding event listeners to all anchors is not done efficiently

RFC: Server Rendering

Some single-spa applications may want to server render some or all of the child applications that are active for a url. How to pull that off is not decided, but here's what I'm thinking for it so far:

const location = {href: '/url#/hash', hash: '#/hash'};
// New API for single-spa returns an array of string names.
const activeAppNames = singleSpa.findActiveApplications(location);

// The serverRender API will load the app but will probably not bootstrap it and will definitely not mount it. Instead it will check
// for a new lifecycle method (serverRender?) on the application. If the lifecycleMethod exists, it calls it. If not, it returns an empty string
Promise
  .all(activeAppNames.map(singleSpa.serverRender))
  .then(serverRenderedHtmls => {
    const finalHtml = serverRenderedHtmls.join("");
    res.write(finalHtml);
  })

Advantages of doing it that way:

• The user of single-spa can control which applications to server render
• findActiveApplications might have other use cases besides server rendering

Disadvantages:

• You have to load the child application before you even know whether it supports server rendering or not. I'm not sure how this would be solved in any other way, though, besides perhaps including some configuration during declareChildApplication.

Reduce bundle size

Right now single-spa is an embarrassing 55kb with minification and mangling (webpack -p). But a lot of that is because single-spa uses async/await, which requires the babel regenerator runtime which is pretty large. So to fix this, we could remove all the async/await code in single-spa itself.

Transitions/animations between apps

My ideas about this are vague and we've had a couple of small discussions about it, but I think that single-spa support might be needed for animations/transitions between apps because it is really the only thing that knows when apps are mounting and unmounting.

Not sure about implementation options or details, but would love to discuss it if anyone has ideas.

triggerAppChange js error when no app claims to be active for a url.

Steps to repro:

1. Go to an app
2. Navigate to a url that doesn't have an app claiming it (using window.history.pushState(..))

Expose root module loader so that all apps can share some modules.

This would include

• ensuring that single-spa knows which apps depend on which 'global' modules (for hot reloading)
• exposing the single-spa loader to user apps (probably through a global SPA.loader)

Find a better way for apps to write links with the <a> tag

Right now we have <a href="/path" onclick="return window.singlespa(this)">Link</a>, which is not terrible but is also not ideal.

Open to ideas/suggestions

Better error messaging if an app fails to load

Currently the error messaging for a systemjs app that fails to load correctly is something like this:

Uncaught Error: "does not export an unmount function or array of functions". It should say something like this: App 'my-app' could not be loaded - could not resolve dependency "lodash"

Create event for when an app is put into broken status

As suggested by the Dealer Socket team

What to do when a lifecycle function never resolves it's promise

Support webpack apps (without converting them to systemjs apps)

Create event for when a routing event occurs where no apps changed

As suggested by Dealer Socket

Figure out the best way to test.

Combining multiple version of the same framework

I was wondering if single-spa allows combining multiple child applications using different versions of the same framework. Say i have two team that want to combine an angular2 and angular4 child app into the same page. Can the framework handle this? I would think not since this would trigger conflicts in the browser.

Question regarding multiple child apps

Hi,

We are in the process of figuring out how to extend our angular 1.5 app with 2.0 child apps. single-spa seems like a great candidate. I was curious to know if there is any documentation regarding having child apps use their own package.json file instead of there being a globally defined package.json file for all child apps. Is this presently possible with single-spa?

single-spa cannot be bundled into webpack bundle.

This was reported by the guys at Dealer Socket. Apparently the UMD bundle doesn't play nice when required in a webpack bundle, like it should be.

when loading index.html files, there are two leading slashes in the url path

Create an npm start script

I would expect to be able to type npm start in the root directory to start serving the app.

single-spa post install requires JSPM

You cannot run an npm install single-spa --save on a system that doesn't have JSPM installed.

Reproduction steps

1. Ensure that you have a version of node/npm that doesn't have JSPM (I just used nvm to switch to a new version)
2. Create a new directory then run npm init in the new directory
3. run npm install single-spa --save

Replace SystemJS with Webpack?

Hi, I was wondering what the feeling is about replacing SystemJS with Webpack? SystemJS is fine, but Webpack is the standard. Use of SystemJS will likely hurt adoption.

split src/single-spa.js into multiple files

Need to find a way to organize the functionality in a way that makes sense.

Get things working with es6-module-loader branch 1.0, (no systemjs and no jspm)

Give warning if `singleSpa.start()` is not called a second or two after singleSpa is instantiated.

There is a good reason for start(), but it is a gotcha unless we provide feedback to the user of single-spa. Also we should add docs about start to the root-application.md

Update docs for new declareChildApplication api

Sharing data and state between micro-apps via Redux?

Hi there @joeldenning,

I came across this project and think it's pretty awesome. It seems to function very closely to how we want to do things at my company. My UI team has been talking more about how we can create a system that can work very much like how this does.

We would, however, require the ability to share data between the loaded micro apps somehow, and would also like to be able to manage the state as well. I may have missed it in the docs, but is this something that is possible currently, or do you know if there is anyone doing anything similar?

We want to be able to develop the different parts of our currently very monolithic application as smaller independent apps that can co-exist and communicate together through some kind of state management (redux) or other kind of interface.

Would love to hear your thoughts on this.

Thanks!
Jared

Add the app that caused the problem to the Error message, where possible

Coding splitting child apps

Hi there, great framework. Thanks for sharing!

Do child apps need to be a single bundle or can they be code splitted?

As an exercise I converted https://github.com/AngularClass/angular-starter into a single-spa child and it successfully mounted onto my root single-spa app. However, it fails on certain routes within the child app, as it tries loading its chunk from the root app

GET http://127.0.0.1:8080/1.chunk.js

rather than the location of the child app on the filesystem.

What's the best strategy to enable on-demand loading of chunks for child apps? Or do I import every chunk in declareChildApplication?

Explore universal rendering.

Add examples and/or documentation for inter-app communication

It's one of the most common questions that comes up, so we should address it more directly in documentation and possibly even single-spa-examples.

See #107 (comment)