Skip to main content
Version: 2.x

Parcels

Most common integration mode, recommended to embed SPAs. This kind of applications are directly managed by the orchestrator, which needs to be supplied with the assets entry point.

danger

Up to now, only JavaScript UMD scripts can be used as parcel application assets.

A single-spa parcel is a framework-agnostic component. It is a chunk of functionality meant to be mounted manually by an application, without having to worry about which framework was used to implement the parcel or application. A parcel can be as large as an application or as small as a component and written in any language as long as it exports the correct lifecycle events.

— single-spa documentation

We provide an extensive list of templates to build your own parcel application using your favourite framework:

caution

If you are using Angular parcels, remember that the framework needs zone.js to work, which is not bundled in micro-lc.

Therefore, you need to import it as a <script> in you micro-lc entrypoint before any micro-lc related module. For example:

<!DOCTYPE html>
<html lang="en">

<head>

  [...]

  <script
    type="module"
    src="https://cdn.jsdelivr.net/npm/zone.js@0.13.0/dist/zone.min.js"
  ></script>

  <script 
    type="module" 
    src="https://cdn.jsdelivr.net/npm/@micro-lc/orchestrator@latest/dist/micro-lc.production.js"
  ></script>
</head>

[...]

</html>

Usage​

For what concerns micro-lc configuration, a parcel is an object with keys html, scripts, and styles (at least one between html and scripts is mandatory). By polymorphism, we allow entry to be a string which will be interpreted as an HTML asset entry.

interface ParcelApplication {
  integrationMode: "parcel"
  entry:
    // Shorthand syntax
    | string
    // Normal syntax
    | (
        | {
            scripts: string | [string, ...string[]]
            styles?: string | string[]
            html?: string
          }
        | {
            scripts?: string | string[]
            styles?: string | string[]
            html: string
          }
      )
  route: string // Path on which the parcel will be rendered
  properties?: Record<string, unknown> // Data passed to the parcel
  injectBase?: boolean // See explanation below
}

Lifecycle methods​

A parcel application has to provide a standard set of lifecycle methods. Those methods must be located either in an inline script in the application HTML asset, or as UMD script export within one of the application scrip assets.

The simplest form of a parcel application is shown in following example.

<!DOCTYPE html>
<html lang="en">
<head>
  <title>Lifecycle methods</title>

  <script src="lifecycle.js"></script>
</head>
<body>
  <div id="root"></div>
</body>
</html>

Lifecycle methods are:

They all return Promise<null>. Update is not mandatory and is available only for error pages. The others take as argument an object with the following interface.

interface LifecycleProps {
  name: string
  container: HTMLElement
  entry: {
    html: string
    scripts: string[]
    styles: string[]
  }
  props: {
    injectBase: boolean
    microlcApi?: Partial<MicrolcApi>
    [key: string]: unknown
  }
}
  • name is the application unique identifier as per micro-lc configuration key applications.
  • container is the application mount point which is provided by micro-lc configuration key mountPointSelector.
  • entry is the application assets object.
  • props is an object including application custom properties and micro-lc injected properties. See dedicated section for a detailed description.

Bootstrap​

This lifecycle function will be called once, right before the parcel is mounted for the first time.

function bootstrap(props: LifecycleProps): Promise<null> {
  /* This is where you do one-time initialization */
}

Mount​

This lifecycle function is called when the router selects the parcel for rendering.

function mount(props: LifecycleProps): Promise<null> {
  /* This is where you tell a framework (e.g., React) to render some UI to the DOM */
}

Unmount​

When redirecting to another application, the parcel is unmounted.

tip

When called, this function should clean up all DOM elements, DOM event listeners, leaked memory, globals, observable subscriptions, etc. that were created at any point when the parcel was mounted.

function unmount(props: LifecycleProps): Promise<null> {
  /* This is where you tell a framework (e.g., React) to un-render some ui from the DOM */
}

Update​

This lifecycle method is only available for error pages.

Properties​

micro-lc injects two default properties, which can be extended in two ways:

  • on a per-application basis with the properties key on the application configuration, and
  • with configuration key shared for properties common to all applications and composed DOM nodes (the content of shared.properties will be spread on first level).

injectBase​

caution

If your application index.html already has a base tag, this property will not override it. micro-lc will consider this plugin to have been built with prior knowledge of its configuration and deploy route.

From micro-lc version 2.1.0, the injectBase property accepts also the value override which discards incoming bundled base tags and injects its own according with the parcel route settings.

  • Type: boolean | 'override'
  • Default: false

Instructs micro-lc on whether to inject a base tag to allow application internal routing to behave as if it was deployed on the bundle selected root, or any root that was selected at build time.

This property is meaningful if set to true or 'override' only on applications that do not have a hash router. On applications without internal routing, this property does provide any feature.

tip

For better compatibility, we recommend to choose ./ as build time public URL.

The example below is a showcase of two minimal React applications, one with a browser router and one with a hash router. The correct usage of injectBase enables both of them to work correctly (and to coexist undisturbed).

microlcApi​

micro-lc injects some useful utils to each application in order to share state, events, and styles. Read the full reference for a detailed description of this property.