Angular 21 SSR AngularNodeAppEngine | Native federation | Plain Starter Project adding mfes

[CaspianVahagn]

With what library do you have an issue?

native-federation

Reproduction of the bug/regression with instructions

To reproduce the bug:
generate a new project using the angular cli with version 21.

Follow the tutorial Angular Architects Tutorial as described here:

https://www.angulararchitects.io/blog/ssr-and-hydration-with-native-federation-for-angular/

Expected behavior

Run simple mfe application in SSR

Versions of Native/Module Federation, Angular, Node, Browser, and operating system

• Native Federation
• Angular version 21
• @softarc/native-federation-node 3.5.5
• SSR using AngularNodeAppEngine instead of CommonEngine

npm ls:

├── @angular-architects/native-federation@21.2.3
├── @angular-devkit/build-angular@21.2.10
├── @angular/animations@21.2.12
├── @angular/build@21.2.10
├── @angular/cli@21.2.10
├── @angular/common@21.2.12
├── @angular/compiler-cli@21.2.12
├── @angular/compiler@21.2.12
├── @angular/core@21.2.12
├── @angular/forms@21.2.12
├── @angular/platform-browser@21.2.12
├── @angular/platform-server@21.2.12
├── @angular/router@21.2.12
├── @angular/ssr@21.2.10
├── @emnapi/core@1.10.0 extraneous
├── @emnapi/runtime@1.10.0 extraneous
├── @emnapi/wasi-threads@1.2.1 extraneous
├── @napi-rs/wasm-runtime@1.1.4 extraneous
├── @softarc/native-federation-node@3.5.5
├── @tailwindcss/postcss@4.3.0
├── @tybys/wasm-util@0.10.2 extraneous
├── @types/express@5.0.6
├── @types/node@20.19.40
├── cors@2.8.6
├── es-module-shims@1.10.1
├── express@5.2.1
├── jsdom@28.1.0
├── postcss@8.5.14
├── prettier@3.8.3
├── rxjs@7.8.2
├── tailwindcss@4.3.0
├── tslib@2.8.1
├── typescript@5.9.3
└── vitest@4.1.5

Other information

Issues Occuring:

1. ng add @angular-architects/native-federation --project shell --type dynamic-host --port 4200 will add federation config but will incorrectly assume how the bootstrap-server.ts is structured and is missing a bracket } (minor inconvenience)

2. the generated `server.ts' assumes the old express setup hence the server will never run properly. Angular defaults to:

console.log('Starting SSR for Shell');

(async () => {

  await initNodeFederation({
    remotesOrManifestUrl: '../browser/federation.manifest.json',
    relBundlePath: '../browser/',
  });

  await import('./bootstrap-server'); // this will never work since run is not properly invoked
  console.log('Node Federation initialized');

})();

it will crash with:

The 'reqHandler' export in 'server.ts' is either undefined or does not provide a recognized request handler. Using the internal SSR middleware instead.
node:internal/fs/promises:640
return new FileHandle(await PromisePrototypeThen(
^

Error: ENOENT: no such file or directory, open '../browser/federation.manifest.json'

it appears as if the Public folder where the federation.manifest.json is located is not properly resolved.

angular.json:

        "esbuild": {
          "builder": "@angular/build:application",
          "options": {
            "outputPath": "dist/shell",
            "index": "projects/shell/src/index.html",
            "browser": "projects/shell/src/main.ts",
            "tsConfig": "projects/shell/tsconfig.app.json",
            "assets": [
              {
                "glob": "**/*",
                "input": "projects/shell/public" // this should be resolved, and read from the manifest ? 
              }
            ],

I would be willing to submit a PR to fix this issue

• Yes
• No

[CaspianVahagn]

I think I figured out the issue.

The current tutorial does not work out of the box for newer Angular projects using SSR with the new AngularNodeAppEngine setup.

With Angular 20+ (and especially newer greenfield SSR projects), the generated project.json now contains:

"outputMode": "server"

Example:

"esbuild": {
  "builder": "@angular/build:application",
  "options": {
    "browser": "projects/wizard/src/main.ts",
    "tsConfig": "projects/wizard/tsconfig.app.json",
    "assets": [
      {
        "glob": "**/*",
        "input": "projects/wizard/public"
      }
    ],
    "styles": ["projects/wizard/src/styles.css"],
    "server": "projects/wizard/src/main.server.ts",
    "outputMode": "server",
    "security": {
      "allowedHosts": []
    },
    "ssr": {
      "entry": "projects/wizard/src/server.ts"
    },
    "polyfills": ["es-module-shims"]
  }
}

The problem is that the current setup only looks at ./bootstrap-server.ts.

However, with the new app engine setup this file is no longer the actual Angular bootstrap entry. It is effectively just a provider/setup layer for the render server.

In a traditional Angular SSR setup, the bootstrap and server parts are connected through the Angular builder pipeline.

With the new setup, the builder only sees this:

import { initNodeFederation } from '@softarc/native-federation-node';

(async () => {
  await initNodeFederation({
    relBundlePath: '../browser/',
  });

  await import('./bootstrap-server');
})();

The important detail here is:

• bootstrap-server.ts is not the actual application bootstrap
• it is not importing the Angular app
• and most importantly, it is not part of the application's import tree

Because of that, the federation/plugin setup never sees the real server bootstrap.

The fix is actually very simple:

Add an unused import to main.server.ts inside server.ts:

import bootstrap from './main.server';

Even though the import appears unused, it is required so the builder can discover and include the actual Angular server bootstrap tree.

Working example:

import { createRequire } from "module";
const require = createRequire(import.meta.url);

const cors = require("cors");

import {
  AngularNodeAppEngine,
  createNodeRequestHandler,
  isMainModule,
  writeResponseToNodeResponse,
} from '@angular/ssr/node';

import express from 'express';
import { join } from 'node:path';

import bootstrap from './main.server'; // unused but required

const browserDistFolder = join(import.meta.dirname, '../browser');

const app = express();

app.use(cors());
app.set('view engine', 'html');

const angularApp = new AngularNodeAppEngine({});

app.use(
  express.static(browserDistFolder, {
    maxAge: '1y',
    index: false,
    redirect: false,
  }),
);

app.use((req, res, next) => {
  angularApp
    .handle(req)
    .then((response) =>
      response
        ? writeResponseToNodeResponse(response, res)
        : next()
    )
    .catch(next);
});

if (isMainModule(import.meta.url) || process.env['pm_id']) {
  const port = process.env['PORT'] || 4200;

  app.listen(port, (error) => {
    if (error) {
      throw error;
    }

    console.log(
      `Node Express server listening on http://localhost:${port}`
    );
  });
}

export const reqHandler = createNodeRequestHandler(app);

I now have this running successfully with Angular 21.

I will provide a minimal working example project shortly once I finish validating the full build/deployment flow.

because it will work via ng serve but not on build.

ENOENT: no such file or directory, open '../browser/federation.manifest.json'

It would probably also help to update the documentation/tutorials for:

• Angular 20+
• new greenfield SSR projects
• the new AngularNodeAppEngine setup
• outputMode: "server"

because the current tutorial appears to assume the older SSR bootstrap architecture.

[Aukevanoost]

Thanks for the comprehensive analysis! We'll have a look

[CaspianVahagn]

As of now, I was only able to successfully build and run the application by manually rewriting main.server.ts to use CommonEngine.

After updating angular.json and removing outputMode: "server" (which unfortunately means losing the newer Angular SSR features), everything works correctly.

I also verified that by pulling and updating the reference repository from Angular v20 to v21:
https://github.com/manfredsteyer/poc-nf-ssr

Which works aswell.

This works because it still uses the older CommonEngine server setup.

At the moment, the tutorial does not seem to match the current default SSR setup generated by the Angular CLI. It may require a different CLI template that still generates the older CommonEngine + Express-based setup.

Otherwise, if there is interest in improving or fixing support for AngularNodeAppEngine, here are some findings:

I assume outputMode: "server" is currently not working because SSR entry handling differs between development and production builds.

In development mode, the SSR entry is expected to export:

export const reqHandler = createNodeRequestHandler(app);

However, the default generated setup does not expose this handler because it is wrapped in an immediately executed async function:

(async () => {

  await initNodeFederation({
    remotesOrManifestUrl: '../browser/federation.manifest.json',
    relBundlePath: '../browser/',
  });

  await import('./bootstrap-server');
  console.log('Node Federation initialized');

})();

When using outputMode: "server" in development mode, the SSR entry must instead point to:

"ssr": {
  "entry": "projects/shell/src/bootstrap-server.ts"
}

instead of:

"ssr": {
  "entry": "projects/shell/src/server.ts"
}

Relevant angular.json configuration (esbuild section):

"esbuild": {
  "builder": "@angular/build:application",
  "options": {
    "outputPath": "dist/shell",
    "index": "projects/shell/src/index.html",
    "browser": "projects/shell/src/main.ts",
    "tsConfig": "projects/shell/tsconfig.app.json",

    "assets": [
      {
        "glob": "**/*",
        "input": "projects/shell/public"
      }
    ],
    "styles": ["projects/shell/src/styles.css"],
    "server": "projects/shell/src/main.server.ts",
    "outputMode": "server",
    "security": {
      "allowedHosts": []
    },
    "ssr": {
      "entry": "projects/shell/src/bootstrap-server.ts"
    },
    "polyfills": [
      "es-module-shims"
    ]
  },
  "configurations": {
    "production": {
      "budgets": [
        {
          "type": "initial",
          "maximumWarning": "500kB",
          "maximumError": "1MB"
        },
        {
          "type": "anyComponentStyle",
          "maximumWarning": "4kB",
          "maximumError": "8kB"
        }
      ],
      "outputHashing": "all"
    },
    "development": {
      "optimization": false,
      "extractLicenses": false,
      "sourceMap": true
    }
  },
  "defaultConfiguration": "production"
}

I then initialized Module Federation inside the bootstrap-server.ts before exporting the request handler:

/**
 * Use the generated server setup and only add this:
 */

if (process.env["NODE_ENV"] === "development") {
  await initNodeFederation({
    remotesOrManifestUrl: 'projects/shell/public/federation.manifest.json',
    relBundlePath: 'dist/shell/browser',
  });

  console.log("init fed");
} else {
  await initNodeFederation({
    remotesOrManifestUrl: '../browser/federation.manifest.json',
    relBundlePath: '../browser/',
  });
}

export const reqHandler = createNodeRequestHandler(app);

With this setup, the dev server runs successfully.

However, production mode still does not work because the server starts before Module Federation initialization completes.

I also encountered hydration-related runtime errors when using outputmode server in that scenario:

ERROR TypeError: can't assign to property "hydratedNodes" on true: not an object
    Angular -
        markRNodeAsClaimedByHydration
        retrieveHydrationInfoImpl
        retrieveHydrationInfo
        renderComponent
        renderChildComponents
        renderView
        createComponentRef
        create
        bootstrapImpl
        run
        bootstrapImpl
        bootstrap
        bootstrap
[_effect-chunk2.mjs:2652:14](http://localhost:4200/@angular/core/fesm2022/_effect-chunk2.mjs)