# Root application
The single-spa root application consists of all code that is not part of a
[child application](/docs/child-applications.md). Ideally, this only includes an html file
and a javascript file that declares single-spa child applications. It is best practice to keep your
root application as small as possible and to simply defer to single-spa to manage
all of the child applications. The root application should not be doing client-side html
rendering nor should it be responding to routing events such as `hashchange` or `popstate`.
Instead, all of that functionality should be taken care of either by single-spa itself or by
a child application.

## Index.html file
The main thing that you should be doing in your html file is executing your root application. For your
use case, this could mean something like `<script src="/my-root-application"></script>` or maybe
`System.import('my-root-application')`.

Example:
```js
<html>
  <body>
    <script src="/path-to-root-application.js"></script>
  </body>
</html>
```

## Declaring child applications

Declaring a [child application](/docs/child-applications.md) is registering it with single-spa so that it will be loaded,
initialized, mounted, and unmounted at the right times. Declaration most commonly occurs inside of the root application, but
does not have to. Note that if a child application is declared from within another child application, that no hierarchy
will be maintained between the child applications. Instead, the child applications will be siblings and will be mounted
and unmounted according to their own activity functions.

In order to declare a child application, call the `declareChildApplication(name, howToLoad, activityFunction)` api. Example:

```js
import { declareChildApplication } from 'single-spa';

declareChildApplication("childApplicationName", loadingFunction, activityFunction;

function loadingFunction() {
  return System.import("src/app1/main.js");
}

function activityFunction() {
  return window.location.hash.indexOf("#/app1/") === 0;
}
```

### Child application name
The first argument to `declareChildApplication` must be a string name.

### Loading function
The second argument to `declareChildApplication` must be a function that returns a promise (or an ["async function"](https://ponyfoo.com/articles/understanding-javascript-async-await)).
The function will be called with no arguments when it's time to load the child application for the first time. The returned
promise must be resolved with the child application. The most common implementation of a loading function is a System.import call:
`() => System.import('/path/to/child-application.js')`

### Activity function
The third argument to `declareChildApplication` must be a function that takes in no arguments and returns a truthy
value whenever the child application should be active. Most commonly, the activity function determines if a child application
is active by looking at `window.location`. When this is done, single-spa as a whole is acting as a high-level router
that is framework agnostic.

single-spa will call each child application's activity function under the following scenarios:
- `hashchange` or `popstate` event
- `pushState` or `replaceState` is called
- [`triggerAppChange`](/docs/single-spa-api.md#triggerappchange) api is called on single-spa

## Two child applications simultaneously??
Yep, it's possible. And it's actually not that scary if you do it right. And once you do,
it's really really powerful. One approach to do it is to designate one `<div id="main-content">` for the main
content and then have other divs for navbars, menus, etc. Then choose to have
only one main content application child application at a time, but many navbar/menu child application active
simultaneously. Content applications would put their html into `#main-content`, and then clear out all DOM elements
from that div when unmounting.
