feat: Migrate existing apps with application builder to use `index.server.html` in server file #19848

pawelfras · 2025-01-09T13:25:36Z

This PR provides an automation that migrates SPA apps using application builder (created with SPA >=2211.19) to use server/index.server.html instead of browser/index.html due to changes in Angular 19 and what's the output of built application.

QA (installation script):

build and deploy Spartacus packages locally:
npx ts-node ./tools/schematics/testing.ts in the SPA root folder
create new app npx @angular/cli@17 new my-app --standalone=false --style=scss --routing=false
go to the project's directory and install latest SPA 2211.x, e.g. from RBSC
migrate to Angualr 18, then 19 (following migration docs
update SPA to v2211.35.0:
`npx @angular/cli@17 update @spartacus/schematics@latest
verify if migration runs (logs in console):
verify server.ts file if changes are applied:
run npm run build and NODE_TLS_REJECT_UNAUTHORIZED=0 run serve:ssr:my-app to test if app works

Required actions:
-[ ] change the migration from 2212.32.0 to the proper one, when it's known

- ran `npx nx migrate latest` (bump most of libraries to the latest version) and `npx nx migrate --run-migration` (run packages' migration, all except angular's migration from initializer tokens to helper functions) - bump '@angular/animations' to version '^19.0.3' - bump '@angular/common' to version '^19.0.3' - bump '@angular/compiler' to version '^19.0.3' - bump '@angular/core' to version '^19.0.3' - bump '@angular/forms' to version '^19.0.3' - bump '@angular/platform-browser' to version '^19.0.3' - bump '@angular/platform-browser-dynamic' to version '^19.0.3' - bump '@angular/platform-server' to version '^19.0.3' - bump '@angular/pwa' to version '^19.0.4' - bump '@angular/router' to version '^19.0.3' - bump '@angular/service-worker' to version '^19.0.3' - bump '@angular/ssr' to version '^19.0.4' - bump '@ng-select/ng-select' to version '^14.1.0' - bump 'angular-oauth2-oidc' to version '19.0.0' - bump 'ngx-infinite-scroll' to version '^19.0.0' - bump 'zone.js' to version '0.15.0' - bump '@angular-devkit/build-angular' to version '^19.0.4' - bump '@angular-devkit/core' to version '^19.0.4' - bump '@angular-devkit/schematics' to version '^19.0.4' - bump '@angular-eslint/builder' to version '19.0.2' - bump '@angular-eslint/eslint-plugin' to version '^19.0.2' - bump '@angular-eslint/eslint-plugin-template' to version '^19.0.2' - bump '@angular-eslint/schematics' to version '^19.0.2' - bump '@angular-eslint/template-parser' to version '^19.0.2' - bump '@angular-eslint/test-utils' to version '^19.0.2' - bump '@angular-eslint/utils' to version '^19.0.2' - bump '@angular/cli' to version '^19.0.4' - bump '@angular/compiler-cli' to version '^19.0.3' - bump '@angular/language-service' to version '^19.0.3' - bump '@nx/angular' to version '^20.2.2' - bump '@nx/devkit' to version '^20.2.2' - bump '@nx/eslint-plugin' to version '^20.2.2' - bump '@nx/jest' to version '^20.2.2' - bump '@nx/workspace' to version '^20.2.2' - bump '@schematics/angular' to version '^19.0.4' - bump 'jest-preset-angular' to version '14.4.2' - bump 'ng-packagr' to version '^19.0.1' - bump 'nx' to version '^20.2.2' - bump 'typescript' to version '^5.6.3' - add `standalone: false` to all components, directives and pipes for more, see: angular/angular#57643 - add rule `"@angular-eslint/prefer-standalone": "off"` in eslint files - remove deprecated `"angular-eslint/no-host-metadata-property"` for more, see: angular-eslint/angular-eslint#2113 - update '@angular/ssr' import paths to use the new '/node' entry point when 'CommonEngine' is detected for more, see: angular/angular-cli#28278

- change range specifier for typescript library to meet Angular's requirement (>=5.5.0 and <5.7.0)

- fix building libs and CSR by solvig type errors provided with TS 5.6

- this update is required for SSR to work, because previous version use Angualr 18 API which is no longer part of @angular/core in v19. for more, see: angular/angular#58891

- fix type issues - use `takeUntil` with destroy subject in `trending-searches.service.ts` as a more reliable cleanup method to properly handle cleanup - remove redundant 'declatartion: true' from 'tsconfig.schematics.json' files, that caused issues in unit tests due to type errors in '@schematics/angular' library 'Buffer is not a generic type'. The issue appeared because '*.d.ts' files are taken into consideration when running tests, maybe unnecessary for more, see: https://github.com/angular/angular-cli/blob/4db4dd4315fd8c31872bbf1e82e3414eea15ffef/goldens/public-api/angular_devkit/schematics/index.api.md\?plain\=1\#L498

- update snapshots with new budget thresholds for more, see: angular/angular-cli#28255 - update snapshots with new packages versions - update schematics and related tests with the new `server.ts` location for more, see: angular/angular-cli#28571 - adjust positions in utils tests to reflect the `standalone: false` in component decorators - adjust SSR schematics to remove `withEventReplay()` that Angular installs by default for more, see: - refactor tests for 2211.19 SSR migration to make them independent of Angular's schematics for more, see: angular/angular-cli#28469

- move `@angular-eslint/prefer-standalone` to global eslint rules - add missing `OnDestroy` implementation in cds library - remove `@angular-eslint/no-host-metadata-property` from the config as it is no longer part of the package for more, see: angular-eslint/angular-eslint#2113

- add missing comma to all files where 'standalone: false' was added

- upgrade to version that supports TS >= 5.6.3 - add `@typescript-eslint/rule-tester` which was missing peer dependency of `@angular-eslint/test-utils` - adjust import-utils.ts to meet new typing

- bump `@ngrx/*` libraries to `19.0.0` - adjust failing unit tests to satisfy types

- update snapshots - adjust ssr/engine tests to use new required `standalone: false` - adjust jest config for `setup/ssr` unit tests to use `beasties` from node modules instead of the internalized one provided with `@angular/ssr` due to issues with not supported ES format

….server.html` - adjust server file - update snapshot

- update docs with information about changing path to the index file to be in line with the builder's output

This reverts commit 3fb0b3a.

This reverts commit c304b34.

…io, where indexHtml variable is defined inside function

…file

kpawelczak

Tested the changes and the server.ts is updated after the migration. The SSR application properly uses the index.server.html.
@pawelfras There are sonar errors complaining about the if statement style

The base branch was changed.

projects/schematics/src/shared/utils/package-utils_spec.ts

Platonn · 2025-01-27T08:22:14Z

projects/schematics/src/shared/utils/package-utils.ts

+/**
+ * Reads and parses the angular.json file from the root of the project.
+ *
+ * @param tree - The virtual file tree provided by the Angular schematics
+ * @returns The parsed angular.json content as an object
+ * @throws SchematicsException if angular.json cannot be found or parsed
+ */
+function readAngularJson(tree: Tree): any {
+  const buffer = tree.read('angular.json');
+  if (!buffer) {
+    throw new SchematicsException('Could not find angular.json');
+  }
+  const angularFileBuffer = buffer.toString(UTF_8);
+  return JSON.parse(angularFileBuffer);
+}


[QUESTION]
Why didn't we reuse the existing util function getWorkspace()?

spartacus/projects/schematics/src/shared/utils/workspace-utils.ts

Line 51 in be9b4fe

export function getWorkspace(

Good point! Code from readAngularJson was used in few functions inside this util file so I extracted it to a separate function and reused, but I wasn't aware of getWorkspace util. It works as expected after switching to your proposal 👌

projects/schematics/src/migrations/2211_35/ssr/update-ssr/update-server-files.ts

pawelfras and others added 28 commits December 12, 2024 12:54

chore: Change Version Range Specifier For Typescript

f95bd2c

- change range specifier for typescript library to meet Angular's requirement (>=5.5.0 and <5.7.0)

fix: Build issues

54ca560

- fix building libs and CSR by solvig type errors provided with TS 5.6

chore: Update '@angular-builders/custom-webpack' to '19.0.0-beta.0'

51ae9c4

- this update is required for SSR to work, because previous version use Angualr 18 API which is no longer part of @angular/core in v19. for more, see: angular/angular#58891

chore: Update dependencies

f77c7eb

chore: Fix prettier issues

4048f17

- add missing comma to all files where 'standalone: false' was added

chore: Update NgRx to v19.0.0-beta.0

34574a8

chore: Upgrade @typescript-eslint packages to 8.18.1

b1bc98c

- upgrade to version that supports TS >= 5.6.3 - add `@typescript-eslint/rule-tester` which was missing peer dependency of `@angular-eslint/test-utils` - adjust import-utils.ts to meet new typing

chore: Update package-lock file

6d1bf09

chore: Upgrade NgRx to stable version 19.0.0

ccf37f2

- bump `@ngrx/*` libraries to `19.0.0` - adjust failing unit tests to satisfy types

chore: Update dependencies and package-lock file

c1fa528

Trigger Build

85526ca

Trigger Build

a004277

chore: Initial migration docs

8da6be2

refactor: Adjust installation schematics for SSR to use `server/index…

ef4ede7

….server.html` - adjust server file - update snapshot

docs: Update migration docs

89b2d08

- update docs with information about changing path to the index file to be in line with the builder's output

chore Upgrade '@angular-builders/custom-webpack' to version 19.0.0

1ec74e0

Add license header

3fb0b3a

Revert "Add license header"

587ce7b

This reverts commit 3fb0b3a.

Add license header

c304b34

Revert "Add license header"

c59ccf8

This reverts commit c304b34.

Merge branch 'develop-next-major' into epic/upgrade-to-angular-19

b5500cb

refactor: add util to work with application builder and handle scenar…

9fe60e6

…io, where indexHtml variable is defined inside function

Merge branch 'epic/upgrade-to-angular-19' into feat/use-index-server-…

768edc1

…file

pawelfras requested a review from a team as a code owner January 9, 2025 13:25

Add license header

72a5973

pawelfras mentioned this pull request Jan 9, 2025

Upgrade to Angular 19 #19772

Merged

46 tasks

kpawelczak reviewed Jan 16, 2025

View reviewed changes

pawelfras added 2 commits January 20, 2025 12:14

fix sonar issues

12980b5

chore: fix sonar issues and add JSDOCs

1a504c1

kpawelczak previously approved these changes Jan 20, 2025

View reviewed changes

Base automatically changed from epic/upgrade-to-angular-19 to develop January 23, 2025 07:35

pawelfras requested review from a team as code owners January 23, 2025 07:35

Merge branch 'develop' into feat/use-index-server-file

ffa0564

github-actions bot marked this pull request as draft January 23, 2025 09:26

pawelfras and others added 6 commits January 23, 2025 10:28

chore: revert changes in migration.md

d7d60c9

Merge branch 'develop' into feat/use-index-server-file

120b7f2

chore: revert changes in package-lock.json

6c16b8b

chore: update migration version and related parts to 2211.35.0

b33f694

Merge branch 'develop' into feat/use-index-server-file

68435b4

Merge branch 'develop' into feat/use-index-server-file

be9b4fe

Platonn reviewed Jan 27, 2025

View reviewed changes

Platonn mentioned this pull request Jan 27, 2025

fix: prevent removing new-lines from original server.ts file #19933

Merged

Platonn and others added 4 commits January 28, 2025 10:17

fix: prevent removing new-lines from original server.ts file (#19933)

ba97e49

refactor after review

b1207c9

fix sonanr issue

6f28a3d

Merge branch 'develop' into feat/use-index-server-file

c4cbd53

pawelfras marked this pull request as ready for review January 28, 2025 11:51

Platonn approved these changes Jan 28, 2025

View reviewed changes

pawelfras merged commit 0ab6454 into develop Jan 28, 2025
18 checks passed

pawelfras deleted the feat/use-index-server-file branch January 28, 2025 12:44

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: Migrate existing apps with application builder to use `index.server.html` in server file #19848

feat: Migrate existing apps with application builder to use `index.server.html` in server file #19848

pawelfras commented Jan 9, 2025 •

edited

Loading

kpawelczak left a comment

Platonn Jan 27, 2025

pawelfras Jan 28, 2025

feat: Migrate existing apps with application builder to use index.server.html in server file #19848

feat: Migrate existing apps with application builder to use index.server.html in server file #19848

Conversation

pawelfras commented Jan 9, 2025 • edited Loading

kpawelczak left a comment

Choose a reason for hiding this comment

Platonn Jan 27, 2025

Choose a reason for hiding this comment

pawelfras Jan 28, 2025

Choose a reason for hiding this comment

feat: Migrate existing apps with application builder to use `index.server.html` in server file #19848

feat: Migrate existing apps with application builder to use `index.server.html` in server file #19848

pawelfras commented Jan 9, 2025 •

edited

Loading