single-spa-angular

This package uses a lock-step versioning strategy where the major version of single-spa-angular matches the major version of Angular. This ensures compatibility is easy to verify. Note that a major version bump in single-spa-angular is driven by Angular updates and does not necessarily imply breaking changes in the single-spa-angular API itself.

The Webpack helper automatically attempts to determine a libraryName to ensure correct code-splitting and lazy loading. The resolution order is:

1. Explicitly provided: Via options.customWebpackConfig.libraryName.
2. Angular Workspace: It searches for angular.json, .angular.json, or workspace.json. In monorepos, it matches the main entry point against the project's architect.build.options.main configuration.
3. Nx Workspace: It looks for nx.json and matches the project path against the current Webpack resolve.roots.
4. Fallback: If no name can be determined, it defaults to 'angular_single_spa_project'.

Warning: Using the default fallback name may cause issues with code-splitting or lazy loading. It is recommended to provide a libraryName explicitly if the automatic detection fails.

If you want to run your Angular application in zoneless mode (where change detection is managed manually rather than via Zone.js), set the NgZone option to 'noop' in the singleSpaAngular configuration.

When NgZone is set to 'noop':

• The library will not attempt to wrap routing events in an Angular zone.
• The requirement to provide provideSingleSpaPlatform() is skipped because the platform location override is not needed for zoneless applications.

const bootstrap = singleSpaAngular({
  NgZone: 'noop' as any,
  bootstrapFunction: (props) => platformBrowser().bootstrapApplication(AppComponent, props),
  template: '<app-root />',
});

To ensure proper URL synchronization and prevent infinite navigation loops between Angular and single-spa, you must provide the SingleSpaPlatformLocation class to the Angular platform. This is required for all applications, whether they use NgZone or are zoneless.

Pass the result of provideSingleSpaPlatform() to platformBrowser() during your application bootstrapping process within the bootstrapFunction of your single-spa-angular configuration.

const lifecycles = singleSpaAngular({
  bootstrapFunction: async () => {
    const platformRef = platformBrowser(provideSingleSpaPlatform());
    return bootstrapApplication(AppComponent, appConfig, { platformRef });
  },
  template: '<app-root />',
  NgZone: 'noop',
  Router,
  NavigationStart,
});

The ng-add schematic automates the integration of single-spa-angular into an existing Angular project. When executed via the Angular CLI, it performs the following sequence of operations:

1. Adds Dependencies: Installs necessary npm packages.
2. Creates Main Entry: Generates the required entry point for the single-spa application.
3. Updates Configuration: Modifies the workspace configuration (e.g., angular.json) to support the single-spa lifecycle.
4. Adds NPM Scripts: Injects relevant scripts into package.json.
5. Routing Check: Issues a warning if Angular routing is already enabled, as this may require specific configuration for single-spa.

To use this, you typically run the command through the Angular CLI in your project directory:

ng add single-spa-angular

To integrate single-spa-angular into an Angular application using standalone APIs, include provideSingleSpa() in your ApplicationConfig providers array. This enables the necessary single-spa lifecycle integration for your Angular microfrontend.

import { ApplicationConfig } from '@angular/core';
import { provideSingleSpa } from 'single-spa-angular';

export const appConfig: ApplicationConfig = {
  providers: [
    provideSingleSpa(),
    // ... other providers
  ],
};

To integrate an Angular application into a single-spa microfrontend architecture, you must include provideSingleSpa() in your application's providers array within the ApplicationConfig. This enables the necessary single-spa lifecycle integration for the Angular application.

import { provideSingleSpa } from 'single-spa-angular';
import type { ApplicationConfig } from '@angular/core';

export const appConfig: ApplicationConfig = {
  providers: [
    provideSingleSpa(),
    // ... other providers
  ],
};

In a single-spa micro-frontend environment, multiple Angular applications share the same browser platform. Standard Angular Location services may trigger popstate events inside the NgZone of the first bootstrapped application, causing other micro-frontends to miss route changes and skip change detection.

To fix this, use provideSingleSpa() to replace the default Angular Location service with SingleSpaLocation. This implementation ensures that every popstate callback is wrapped in the current application's NgZone, guaranteeing that change detection is correctly triggered when routes change.

Add provideSingleSpa() to your application's providers list, such as in bootstrapApplication or an NgModule.

bootstrapApplication(AppComponent, {
  providers: [
    provideSingleSpa()
  ]
});

When running an Angular application as a single-spa microfrontend, you often need to define a specific base href to ensure routing works correctly within the container. This is typically done by providing the APP_BASE_HREF token with the desired path (e.g., /shop).

import { APP_BASE_HREF } from '@angular/common';
import type { ApplicationConfig } from '@angular/core';

export const appConfig: ApplicationConfig = {
  providers: [
    { provide: APP_BASE_HREF, useValue: '/shop' },
  ],
};