New Case Study:See how Anthropic automated 95% of dependency reviews with Socket.Learn More →
Socket
Sign inDemoInstall
Socket
Sign inDemoInstall

single-spa

Package Overview
Dependencies
Maintainers
1
Versions
141
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

single-spa - npm Package Compare versions

Comparing version

2.0.7
to
2.0.8

docs/application-blast-radius.md
docs/child-applications.md
docs/migrating-existing-spas.md
docs/root-application.md
docs/single-spa-api.md
docs/single-spa-ecosystem.md

6

examples/README.md
# Examples
There is [a whole repository](https://github.com/joeldenning/single-spa-examples) dedicated to examples. What you'll find there is one SPA with the following:
- [The index.html file](https://github.com/joeldenning/single-spa-examples/blob/master/index.html)
- [The root app](https://github.com/joeldenning/single-spa-examples/blob/master/bootstrap.js)
- [Many children apps](https://github.com/joeldenning/single-spa-examples/tree/master/apps)
There is [a whole repository](https://github.com/joeldenning/single-spa-examples) dedicated to examples. However, those examples
are not yet up-to-date with single-spa@2.x's api. Contributions are welcome to that project in the meantime.

65

lib/single-spa.js

@@ -46,5 +46,3 @@ 'use strict';

childApps = void 0,
bootstrapMaxTime = void 0,
mountMaxTime = void 0,
unmountMaxTime = void 0,
globalTimeoutConfig = void 0,
peopleWaitingOnAppChange = void 0,

@@ -60,7 +58,24 @@ appChangeUnderway = void 0,

Loader = typeof SystemJS !== 'undefined' ? SystemJS : null;
if (typeof SystemJS !== 'undefined') {
Loader = SystemJS;
} else if (typeof System !== 'undefined' && typeof System.import === 'function') {
Loader = System;
} else {
Loader = null;
}
bootstrapMaxTime = 4000;
mountMaxTime = 3000;
unmountMaxTime = 3000;
globalTimeoutConfig = {
bootstrap: {
millis: 4000,
dieOnTimeout: false
},
mount: {
millis: 3000,
dieOnTimeout: false
},
unmount: {
millis: 3000,
dieOnTimeout: false
}
};

@@ -138,2 +153,4 @@ window.addEventListener('hashchange', urlReroute);

function setBootstrapMaxTime(time) {
var dieOnTimeout = arguments.length <= 1 || arguments[1] === undefined ? false : arguments[1];
if (typeof time !== 'number' || time <= 0) {

@@ -143,6 +160,11 @@ throw new Error('bootstrap max time must be a positive integer number of milliseconds');

bootstrapMaxTime = time;
globalTimeoutConfig.bootstrap = {
millis: time,
dieOnTimeout: dieOnTimeout
};
}
function setMountMaxTime(time) {
var dieOnTimeout = arguments.length <= 1 || arguments[1] === undefined ? false : arguments[1];
if (typeof time !== 'number' || time <= 0) {

@@ -152,6 +174,11 @@ throw new Error('mount max time must be a positive integer number of milliseconds');

mountMaxTime = time;
globalTimeoutConfig.mount = {
millis: time,
dieOnTimeout: dieOnTimeout
};
}
function setUnmountMaxTime(time) {
var dieOnTimeout = arguments.length <= 1 || arguments[1] === undefined ? false : arguments[1];
if (typeof time !== 'number' || time <= 0) {

@@ -161,3 +188,6 @@ throw new Error('unmount max time must be a positive integer number of milliseconds');

unmountMaxTime = time;
globalTimeoutConfig.unmount = {
millis: time,
dieOnTimeout: dieOnTimeout
};
}

@@ -399,16 +429,3 @@

return _extends({
bootstrap: {
millis: bootstrapMaxTime,
dieOnTimeout: false
},
mount: {
millis: mountMaxTime,
dieOnTimeout: false
},
unmount: {
millis: unmountMaxTime,
dieOnTimeout: false
}
}, timeouts);
return _extends({}, globalTimeoutConfig, timeouts);
}

@@ -415,0 +432,0 @@ }).catch(function (ex) {

4

package.json
{
"name": "single-spa",
"version": "2.0.7",
"version": "2.0.8",
"description": "Multiple applications, one page",

@@ -11,3 +11,3 @@ "main": "lib/single-spa.js",

"test": "jasmine",
"build:canopy": "npm run build && rm -rf ../spalpatine/jspm_packages/npm/single-spa@2.0.7 && rsync -av . ../spalpatine/jspm_packages/npm/single-spa@2.0.7 --exclude node_modules --exclude .git --exclude --spec --exclude examples && cd ../spalpatine && npm run build-common-deps && cd ../single-spa"
"build:canopy": "npm run build && rm -rf ../spalpatine/jspm_packages/npm/single-spa@2.0.8 && rsync -av . ../spalpatine/jspm_packages/npm/single-spa@2.0.8 --exclude node_modules --exclude .git --exclude --spec --exclude examples && cd ../spalpatine && npm run build-common-deps && cd ../single-spa"
},

@@ -14,0 +14,0 @@ "repository": "https://github.com/CanopyTax/single-spa",

169

README.md

@@ -5,127 +5,90 @@ # single-spa

Multiple applications all lazily loaded and mounted/unmounted in the same single page application (SPA). The apps can be deployed independently to your web server of choice, lazy-loaded onto the page independently, and nested. Single-spa also allows for **service oriented javascript**, where a "service" (a shared es6 module) is a singleton that each app can call, without resorting to shared libraries that can be out of sync across apps.
Combine multiple SPAs into one SPA by implementing lifecycle functions. Allows you to:
- [Trade off between frameworks](/docs/single-spa-ecosystem.md#help-for-frameworks) [without refreshing the page](/docs/child-applications.md)
(React, ng1, ng2, ember, or whatever you're using)
- [Lazy load code for improved initial load time](/docs/child-applications.md#load). This is baked in and requires no configuration.
- [Ensure that no single part of the app can break everything](/docs/application-blast-radius.md).
In this context, an application is an html document that pulls in JS, CSS, and more HTML. This means that many pre-existing applications do not need to change at all in order to work with single-spa. You just need to add a configuration file on top of your existing SPA.
single-spa works in Chrome, Firefox, Safari, IE11, and Edge.
Single-spa works in Chrome, Firefox, Safari, IE11, and Edge.
## Architectural Overview
Apps built with single-spa are made up of the following pieces:
## View the demo!
A [demo is live](http://single-spa.surge.sh) on surge.sh. Don't be turned off by the lack of styling -- I'll be fixing that soon. It's based on the code in the [examples](https://github.com/joeldenning/single-spa-examples) repository.
1. An index.html file
1. A root application, in which child applications are registered. In order to register a child application, two things must be provided:
1. The path to the application
1. A function that determines if the application is active
1. Many child applications, each of which is like an SPA itself. Child applications respond to url routing events and must know how to bootstrap, mount, and unmount themselves from the DOM.
## Ideology
## Prerequistes
In order to use single-spa, you must be using a javascript [loader](https://github.com/whatwg/loader). Since loaders are not yet supported natively by browsers, you'll have to use a polyfill, such as [SystemJS](https://github.com/systemjs/systemjs).
If you're using a bundler (such as webpack or browserify) instead of a loader, or if you're using a non-standard loader (such as requirejs), check out [the migration guide](/docs/migrating-existing-spas.md)
to see your options.
The hope here is that "one SPA to rule them all" will help scale teams and organizations that have complex apps -- this is done by making it easier to split code and then deploy it independently. To explain why single SPA is advantageous, consider the following **disadvantages of a multiple SPA approach**:
## Documentation
See the [docs](/docs) directory.
1. Implementation details are usually reflected in the URL (different subdomains for different SPAs, or different apps own different prefixes in the window.location.pathname)
2. Each SPA tends to become a monolith, since it's easier to add to an existing SPA than it is to figure out how to deploy a new SPA.
3. Transitioning between the apps is a full page unload-then-load, which generally provides a worse user experience. It *is* possible to mitigate this one with server-side routing + rendering (popularly done with React), but single-spa offers an alternative approach.
4. Shared functionality can *only* be accomplished via shared libraries, instead of a service oriented architecture ("Update it and hope library consumers upgrade" vs "Deploy it once and now everyone has it")
## Simple Usage
*Note*: this example uses [jspm](https://github.com/jspm/jspm-cli), since it's the easiest way to set up a loader. However, jspm and systemjs are not required.
```bash
npm install -g jspm@beta
jspm init
jspm install npm:single-spa
```
## How to use it
In general, the process is to create a root app which imports single-spa and declares child applications by calling `singleSpa.declareChildApplication(...)`. Each child application starts out as just a single-spa.config.js file, with the rest of the app (the html document, the js, the css, etc) being lazy loaded later on. As the app is being loaded, mounted, unmounted, etc., lifecycle functions are called to allow customized behavior. SSPA plugins are written to standardize the lifecycle functions for popular technologies like angular, jspm, react, webpack, etc.
Example:
```javascript
// root-app.html
Create an index.html file (see [docs](/docs/root-application.md#indexhtml-file) for more detail).
```html
<html>
<head>
<script src="/jspm_packages/system.src.js"></script>
<script src="/config.js"></script>
<script src="jspm_packages/system.src.js"></script>
<script src="jspm.browser.js"></script>
<script src="jspm.config.js"></script>
<script>
System.import('/root-app.js');
System.import('src/main.js');
</script>
</head>
<body>
<div id="main-content"></div>
</body>
</html>
```
// root-app.js
Create the root application (see [docs](/docs/root-application.md) for more detail).
```js
// src/main.js
import { declareChildApplication } from "single-spa";
declareChildApplication('/apps/myApp/single-spa.config.js', () => window.location.pathname.startsWith('/myApp'));
// apps/myApp/single-spa.config.js
export const publicRoot = '/apps/the-directory-my-app-is-in'; //the path on the web server to the directory the app is in.
export const pathToIndex = 'index.html'; //This is a relative url (based on publicRoot) to the html document that bootstraps your app
export const lifecycles = []; //put any plugins (i.e., for jspm or angular) here
declareChildApplication('/apps/app1/app1.js', () => window.location.hash === '');
```
### Configuring JSPM apps
[single-spa-jspm](https://github.com/joeldenning/single-spa-jspm) is an actively maintained project that eases the burden of configuring jspm apps. To use it, run the following in your root app's directory
`jspm install npm:single-spa-jspm`
and then add the following to the jspm app's single-spa.config.js:
```javascript
import { defaultJspmApp } from "single-spa-jspm";
export const lifecycles = [...(any other plugins)..., defaultJspmApp()]
```
Thus far it seems that it's best to put your JSPM lifecycles at the end of the array.
### Configuring Webpack apps
So far, webpack has not required any special configuration to work in an SSPA environment. It works out of the box! So no need to add a "lifecycle" for webpack in your single-spa.config.js file.
Create the child application (see [docs](/docs/child-applications.md) for more detail).
```js
document.getElementById('main-content').textContent += "App1 is loaded.";
One thing to watch out for, though, is to make sure that any urls in your webpack config are relative urls. For example, use `publicPath: 'build/'` instead of `publicPath: '/build/'`
### Configuring React apps
[single-spa-react](https://github.com/joeldenning/single-spa-react) is an actively maintained project that eases the burden of configuring react apps. To use it, run the following in your root app's directory
`jspm install npm:single-spa-react`
and then add the following to your single-spa.config.js:
```javascript
import { defaultReactApp } from "single-spa-react";
// apps/app1/app1.js
export function bootstrap() {
return new Promise((resolve, reject) => {
document.getElementById('main-content').textContent += "App1 is bootstrapped.";
resolve();
});
}
export const publicRoot = '...';
export const pathToIndex = 'index.html';
export function mount() {
return new Promise((resolve, reject) => {
document.getElementById('main-content').textContent += "App1 is mounted!";
resolve();
});
}
const reactApp = defaultReactApp({
rootElementGetter: function() {
return document.querySelector('#root-react-element');
},
mountApp: function() {
return ReactDOM.render(<MyApp/>, document.getElementById('root-react-element');
},
ReactDOMGetter: function() { //only needed if the ReactDOM object is not leaked as a global
return window.app.ReactDOM; //or however you want to reference ReactDOM
}
});
export const lifecycles = [reactApp, ...(any other plugins)...];
export function unmount() {
return new Promise((resolve, reject) => {
document.getElementById('main-content').textContent = "";
resolve();
});
}
```
### Configuring Angular apps
[single-spa-angular1](https://github.com/joeldenning/single-spa-angular1) is an actively maintained project that eases the burden of configuring Angular apps. To use it, run the following in your root app's directory
`jspm install npm:single-spa-angular1`
and then add the following to your single-spa.config.js
```javascript
import { defaultAngular1App } from "single-spa-angular1";
export const publicRoot = '....'; //the path on the web server to the directory the app is in
## API
See [single-spa api](/docs/single-spa-api.md) and [child application api](/docs/child-applications.md#child-application-lifecycle).
const angular1App = defaultAngular1App({
publicRoot: publicRoot,
rootAngularModule: '[name of your root angular module]',
rootElementGetter: () => document.querySelector('#app-root') //or some other way of getting the root element
});
export const lifecycles = [...(any other plugins)..., angular1App]
```
### Configuring apps that leak globals
[single-spa-globals](https://github.com/joeldenning/single-spa-globals) is an actively maintained project that eases the burden of configuring apps that leak globals. To use it, run the following in your root app's directory
`jspm install npm:single-spa-globals`
and then add the following to your single-spa.config.js
```javascript
import { appWithGlobals } from "single-spa-globals";
export const publicRoot = '....';
export const pathToIndex = 'index.html';
export const lifecycles = [...(any other plugins)..., appWithGlobals(['app1', 'globalVar1', 'anotherGlobal'])]
```
### Configuring React-Router apps
react-router apps usually require no more configuration than plain old react apps (see above for how to do that). The only thing that may need to change in your app is the `basename` that is used when creating your history object. But that only needs to happen if you're using URLs to determine which app is active at any given time.
For example, you may have to do something like this:
```javascript
import history from "history";
const history = history.useBasename(history.createHistory)({
basename: '/path-that-is-active-when-this-app-is-active'
})
```
### Read the examples
There is also an [examples repository](https://github.com/joeldenning/single-spa-examples) that shows several apps working great in a single-spa environment. The following files are a good place to start:
- [The index.html file](https://github.com/joeldenning/single-spa-examples/blob/master/index.html)
- [The root app](https://github.com/joeldenning/single-spa-examples/blob/master/bootstrap.js)
- [The children apps](https://github.com/joeldenning/single-spa-examples/tree/master/apps)
Also note that it requires that as of 11/1/15, the root app that loads all other apps must be written with JSPM. The goal is to move away from that towards the [whatwg/loader standard](https://github.com/whatwg/loader), probably polyfilled with the [es6-module-loader](https://github.com/ModuleLoader/es6-module-loader).
## Things that are not supported
- Single Spa is the one who controls the `<base>` tag, which means that apps should not control it. single-spa-angular1 makes it possible for angular to still work (even with History API pretty urls!) without the angular app putting a `<base>` tag in the app's index.html.
## View the demo!
A [demo is live](http://single-spa.surge.sh) on surge.sh, but is based on an old version of single-spa. The demo will soon be updated to use single-spa@2.x

61

src/single-spa.js

@@ -21,3 +21,3 @@ import { handleChildAppError } from './single-spa-child-app-error.js';

// Things that need to be reset with the init function;
let Loader, childApps, bootstrapMaxTime, mountMaxTime, unmountMaxTime, peopleWaitingOnAppChange, appChangeUnderway, capturedEventListeners;
let Loader, childApps, globalTimeoutConfig, peopleWaitingOnAppChange, appChangeUnderway, capturedEventListeners;

@@ -30,7 +30,24 @@ export function reset() {

Loader = typeof SystemJS !== 'undefined' ? SystemJS : null;
if (typeof SystemJS !== 'undefined') {
Loader = SystemJS;
} else if (typeof System !== 'undefined' && typeof System.import === 'function') {
Loader = System;
} else {
Loader = null;
}
bootstrapMaxTime = 4000;
mountMaxTime = 3000;
unmountMaxTime = 3000;
globalTimeoutConfig = {
bootstrap: {
millis: 4000,
dieOnTimeout: false,
},
mount: {
millis: 3000,
dieOnTimeout: false,
},
unmount: {
millis: 3000,
dieOnTimeout: false,
},
}

@@ -101,3 +118,3 @@ window.addEventListener('hashchange', urlReroute);

export function setBootstrapMaxTime(time) {
export function setBootstrapMaxTime(time, dieOnTimeout = false) {
if (typeof time !== 'number' || time <= 0) {

@@ -107,6 +124,9 @@ throw new Error(`bootstrap max time must be a positive integer number of milliseconds`);

bootstrapMaxTime = time;
globalTimeoutConfig.bootstrap = {
millis: time,
dieOnTimeout,
};
}
export function setMountMaxTime(time) {
export function setMountMaxTime(time, dieOnTimeout = false) {
if (typeof time !== 'number' || time <= 0) {

@@ -116,6 +136,9 @@ throw new Error(`mount max time must be a positive integer number of milliseconds`);

mountMaxTime = time;
globalTimeoutConfig.mount = {
millis: time,
dieOnTimeout,
};
}
export function setUnmountMaxTime(time) {
export function setUnmountMaxTime(time, dieOnTimeout = false) {
if (typeof time !== 'number' || time <= 0) {

@@ -125,3 +148,6 @@ throw new Error(`unmount max time must be a positive integer number of milliseconds`);

unmountMaxTime = time;
globalTimeoutConfig.unmount = {
millis: time,
dieOnTimeout,
};
}

@@ -373,14 +399,3 @@

return {
bootstrap: {
millis: bootstrapMaxTime,
dieOnTimeout: false,
},
mount: {
millis: mountMaxTime,
dieOnTimeout: false,
},
unmount: {
millis: unmountMaxTime,
dieOnTimeout: false,
},
...globalTimeoutConfig,
...timeouts,

@@ -387,0 +402,0 @@ };