Problems and errors with enforcing SSR using ServerRoutes

[vz-tl]

Which @angular/* package(s) are the source of the bug?

platform-server

Is this a regression?

No

Description

I'm trying to get our SSR application to work with application-builder and the new AngularNodeAppEngine.

In our use case we only want to do SSR, no SSG. Also, we do not want to make use of any ServerRoutes features, as anyway all routes should be SSR, and redirects or status codes will already be handled by the application logic.

In order to enforce all routes being SSR, I had to explicitly configure the app server config with:

provideServerRendering(
  withRoutes([
    {
      path: '**',
      renderMode: RenderMode.Server
    }
  ])
)

Issue 1:

There's no global switch to simply turn off SSG and I'm forced to add withRoutes with a catch-all route, even though I do not want to use any of the related features.

Hence it would be very useful to introduce a withNoRoutes() option, which also should disable the initial route evaluation/extraction while running a dev server - which is simply wasted computation time in our case.

As I do not want SSG, I already configured "outputMode": "server" in angular.json. I'm wondering why this setting isn't enough to turn off SSG completely, so that all pages will be SSR by default, not requiring withRoutes() configured.

Issue 2:

Our routing setup includes a lot of lazy-load child routes. If one of the child routes has a matcher applied, then I get the below error:

Error: Error(s) occurred while extracting routes:
The route 'test/**' has a defined matcher but does not match any route in the server routing configuration. Please ensure this route is added to the server routing configuration.

My (simplified) routing setup is as follows:

App routes:

{
  path: 'test',
  loadChildren: () => import('@my-app/test/feature').then(m => m.testFeatureRoutes)
},

Test feature routes:

  {
    path: '',
    pathMatch: 'full',
    component: TestComponent
  },
  {
    matcher: () => null, <-- this guy here causes the error
    component: TestComponent
  },

Am I really forced now to add for all such routes a dedicated entry like test/** to ServerRoutes? In cases with very dynamic routing it seems to me also impossible or at least cumbersome to add all required sub-route catch-alls. Also, it's actually quite bad DX if one is bothered with having to solve errors for features he/she doesn't want to use anyway.

So, to me the both issues I described are tightly coupled:
If I would be able to turn off server routing completely, I wouldn't have to solve the problems with the catch-alls when using matchers.

Looking forward to some answers explaining to me what can be done to get around the above mentioned obstacles.

Please provide a link to a minimal reproduction of the bug

Please provide the exception or error you saw

See above

Please provide the environment you discovered this bug in (run ng version)

Angular CLI: 20.3.5
Node: 22.18.0
Package Manager: npm 10.9.3
OS: linux x64
    

Angular: 20.3.4
... animations, common, compiler, compiler-cli, core, forms
... language-service, platform-browser, platform-browser-dynamic
... platform-server, router

Package                         Version
---------------------------------------
@angular-devkit/architect       0.2003.5
@angular-devkit/build-angular   20.3.5
@angular-devkit/core            20.3.5
@angular-devkit/schematics      20.3.5
@angular/cdk                    20.2.8
@angular/cli                    20.3.5
@angular/google-maps            20.2.8
@angular/ssr                    20.3.5
@angular/youtube-player         20.2.8
@schematics/angular             20.3.5
ng-packagr                      20.3.0
rxjs                            7.8.2
typescript                      5.9.3
zone.js                         0.15.1

Anything else?

No response

[alan-agius4]

Hi, thanks for the detailed and well-structured report.

Issue 1: Why Route Extraction Runs for SSR

To address your first point about wanting to disable route extraction (e.g., with a withNoRoutes()): the route extraction process is intentionally run even for pure SSR applications (like yours, using "outputMode": "server"). It isn't just for SSG or ServerRoutes.

This process is a key optimization for the SSR server itself. Here's why:

1. Populates a Routing Table: The primary reason is to create a routing table. The server uses this table to quickly know which incoming requests are Angular routes and which are not (e.g., /main.js, /styles.css, /image.png, or 404 pages). This is crucial because it prevents the server from redundantly bootstrapping the full Angular application just to handle a request for an asset.

2. Ahead-of-Time Optimizations: The extraction process is also responsible for other performance features. For example, it determines and adds per-route preload links to the generated HTML.

While these tasks could theoretically be done at runtime on every SSR request, doing them once ahead-of-time during the build is significantly more performant and avoids creating a new performance bottleneck on your live server.

So, while the bug you found with the matcher is a valid issue (and being fixed), the route extraction step itself is a necessary optimization for the SSR engine, even when you are not using SSG.

Issue 2: The Matcher Error

This is a bug and is being addressed in the following pull request: https://github.com/angular/angular-cli/pull/31685](https://github.com/angular/angular-cli/pull/31685

[vz-tl]

Hi @alan-agius4 ,

thanks for the response, which helps a lot! And glad there's a fix on the way for Issue 2! Highly appreciated!

Regarding Issue 1 however, some more thoughts:

I do understand that route extraction seems to be mandatory. But let's not focus on the extraction, rather than the fact the rendering will fallback to SSG if "outputMode": "server" is specified in angular.json respectively in case withRoutes() isn't added to provideServerRendering():

Falling back to SSG if "outputMode": "server" is configured, seems wrong to me: The schema.json explains the option like

'static': Generates a static site for deployment on any static hosting service. 'server': Produces an application designed for deployment on a server that supports server-side rendering (SSR).

So I'd expect, if adding this config option the default should be SSR instead of SSG.

If the above explanation presumes "outputMode": "server" (described as SSR === server-side rendering) is including SSG, then I'd propose to update it for being strictly correct. Additionally, it would be helpful to make this option more flexible to allow SSR-only (then it consequently might require SSG-only and SSR + SSG, too).

When not adding withRoutes(), shouldn't all routes considered for RenderMode.Server. It feels a bit superfluous having to add a catch-all route using withRoutes to explicitly force SSR render-mode.

[alan-agius4]

"outputMode": "server"` refers to the build artifact, not the render mode

• "outputMode": "static" = Generates a folder of static HTML/JS/CSS files.
• "outputMode": "server" = Generates a runnable Node.js server which can be used for application that are only SSG or a mixture of CSR and SSG, or fully SSR. Technically, you could also use "outputMode": "server" for a purely CSR application.

I will send a PR over to make these clear.

No withRoutes()
Your observation is right, if withRoutes() is not provided, the build falls back to SSG.

This was a deliberate design choice, purely to maintain backward compatibility with previous Angular versions. In older versions, SSG was the default behavior.

If we had changed the default for "outputMode": "server" to be "SSR-all-routes," it would have been a breaking change.