From Monolith to Microfrontend: Angular with Single-SPA — Step By Step Guide

Single-SPA is a JavaScript framework that lets you combine multiple microfrontends into one frontend app. It’s ideal for large projects where teams use different frameworks like Angular, React, or Vue. It helps you load parts of your site only when needed and deploy them independently.

🚀 Why Use Single-SPA?

Key Benefits:

1. Use multiple frameworks on one page without full page reloads.
2. Independently deploy different parts of your application.
3. Adopt new frameworks gradually without rewriting everything.
4. Lazy load parts of your app to make it load faster.

🧩 Types of Microfrontends in Single-SPA

1. Applications

• Handle routes and render parts of the page.
• Active apps listen to URL changes and show content.
• Inactive apps are removed from the page and stop listening.

2. Parcels

• Don’t control routes.
• Used for small widgets or UI parts.

3. Utility Modules

• Share logic or services across apps.
• Don’t show anything on the screen.

📁 Structure of a Single-SPA Setup

1. Root Config

• Registers each microfrontend.
• Activates or deactivates apps based on the current URL.

2. Applications

• Standalone frontend apps (usually Angular, React, etc.).
• Mounted and unmounted based on routing.

🖼 Handling Images in Angular Microfrontends

Use a custom pipe to resolve image paths from the root config.

Create asset-url.pipe.ts:

import { Injectable, Pipe, PipeTransform } from "@angular/core";
import { assetUrl } from "../../../single-spa/asset-url";

@Pipe({ name: "assetUrl", standalone: true })
@Injectable({ providedIn: 'root' })
export class AssetUrlPipe implements PipeTransform {
  transform(value: string): string {
    return assetUrl(value);
  }
}

Use in HTML:

<img [src]="'images/dashboard-topshape-img.svg' | assetUrl" />

Import AssetUrlPipe in your component/module.

🛠 Run Angular Locally with Single-SPA

• Development: Use ng serve with normal setup.
• Production: Use special single-spa build configuration.

🧱 Create the Root Config Application

Steps:

npm install --global create-single-spa
npx create-single-spa

• Choose Root Config
• Register it as the host application

🏗 Setup Angular 19 (Standalone) with Single-SPA

1. Initialize Angular App:

ng add single-spa-angular
npm install

2. Update main.single-spa.ts:

bootstrapFunction: singleSpaProps => {
  singleSpaPropsSubject.next(singleSpaProps);
  return bootstrapApplication(AppComponent, appConfig);
}

3. Add Provider in app.config.ts:

getSingleSpaExtraProviders()

4. Build and Serve:

// check command in package.json file 
npm run build:single-spa:solution-name
npm run serve:single-spa:solution-name

5. Add These Files:

• extra-webpack.config-single-spa.js
• tsconfig.app-single-spa.json

6. Update angular.json for production environment:

"main": "src/main.single-spa.ts",
"customWebpackConfig": {
  "path": "extra-webpack.config-single-spa.js",
  "libraryName": "AIStudio-UserManagement-ng",
  "libraryTarget": "umd"
},
"tsConfig": "tsconfig.app-single-spa.json"

Also add the default config:

"main": "src/main.ts"

7. Update package.json Scripts:

    "start": "ng serve --configuration development --port 4205",
    "build": "ng build --configuration development",
    "build:single-spa:angular-mfe1": "ng build angular-mfe1 --configuration production",
    "serve:single-spa:angular-mfe1": "ng s --project angular-mfe1 --configuration production --disable-host-check --port 4205 --live-reload false"

🧱 Angular Module-Based Setup (e.g., Angular 17)

1. Create App:

npx @angular/cli@17 new project_name
ng add single-spa-angular

2. Convert to AppModule if using standalone

3. Remove SSR-related configs from angular.json

4. Add in app.module.ts:

provideClientHydration(withEventReplay())

5. Build & Serve:

npm run build:single-spa:SOLUTION_NAME
npm run serve:single-spa:SOLUTION_NAME

6. Use the same AssetUrlPipe method for image paths

📚 Helpful Link

• Official Docs: https://single-spa.js.org/docs/api/

✅ Final Notes

• ✅ With the right setup, Angular microfrontends run and deploy smoothly.
• ✅ Image paths should be handled from the root config.
• ✅ Use the setup that fits your Angular version (standalone or module).

🎯 This guide helps you set up Angular microfrontends using Single-SPA for real-world, production-ready projects.