doc: 2 guides on modernizing apps: for apps migrated to 2211.19 and f…

…or apps migrated to 2211.35 release (#19924)

**Changes in the PR:**
- This PR adds 2 guides:
  1. for apps migrated to Spa 2211.19 (ng17)  in the past - so they are modernized and mimic a new ng17 apps
  2. for apps migrated to Spa 2211.35 (ng19) - so they are modernized and mimic a new ng19 apps
- Moreover this PR adjusts the main migration guide for 2211.35 (ng19), so it mentions the 2 introduced other guides - the first as a prerequisite and the second as a follow-up (to be prepared better for future next migrations).
- by the way, this PR fixes also an unrelated small glitch in the Bootstrap migration guide

**Why 2 new guides are needed:** 

- Apps migrated from ng15 to ng17 are configured very differently than apps created initially in ng17.
Analogically, apps migrated from ng17 to ng19 are configured a bit differently than apps created initially in ng19. And unfortunately the old configuration is a tech dept that prevents customers from benefiting from some new Angular's features (e.g. faster app builds) and this dept is makes also next future migrations of Angular and Spartacus more complex.
- To be future-proof and to make future next migrations easier, we should help all customers' apps not only to be migrated but also be modernized to use the same new configuration and look like new ng19 apps. This helps both customers and the Spartacus team:
  - customers apps are as modern as possible and easier to migrate to the future versions of Angular and benefit from new Angular's features
  - Spartacus team can spend less time on preparing migrations, because they doesn't need to test scenarios of migrating different apps differently (i.e. apps having different level of legacy configuration):
    1. new ng19 app
    1. ng17 app migrated to ng19 but not modernized - with legacy config
    1. ng15 app migrated to ng17 but not modernized, and then migrated to ng19 but not modernized even more - with double legacy config

fixes https://jira.tools.sap/browse/CXSPA-9217

docs/migration/2211_35/bootstrap.md

@@ -52,12 +52,18 @@
 @import '@spartacus/styles/vendor/bootstrap/scss/reboot';
 ```
 
-4. Some libraries have stopped importing Bootstrap-related styles. Instead, these styles should now be imported directly within the application. For example, the lib-cart.scss file should include the following imports:
+4. Some libraries have stopped importing Bootstrap-related styles. Instead, these styles should now be imported directly within the application. For example, the `cart.scss` file should include the following imports:
 ```scss
 // original imports
 @import '../styles-config';
 @import '@spartacus/cart';
+```
+
+```scss
 // new imports
+@import '../styles-config';
+@import '@spartacus/cart';
+
 @import '@spartacus/styles/vendor/bootstrap/scss/functions';
 @import '@spartacus/styles/vendor/bootstrap/scss/variables';
 @import '@spartacus/styles/vendor/bootstrap/scss/_mixins';

docs/migration/2211_35/migration.md

@@ -1,12 +1,14 @@
-# (EARLY NOTES) Migrating a custom app to use Spartacus with Angular v18
+# Migrating a custom app to use Spartacus 2211.35 with Angular 19
 
 Before upgrading Spartacus to the new version with Angular 18, you need to first:
 
+- **If you've upgraded in the past from Spartacus 6.8 to 2211.19, please first follow the guide**: [Modernize Spartacus apps migrated from 6.8 to 2211.19](./modernize-apps-migrated-from-6.8-to-2211.19.md) and only then please get back here. But apps created initially with Spartacus 2211.19+ should skip this step.
 - upgrade Spartacus to version 2211.32.1
 - install Node 22 version
-- upgrade `@types/node` to version 22
+- if your project uses SSR (Server-Side Rendering), please upgrade `@types/node` to version 22
+
   ```bash
-  npm i @types/node@22
+  npm i @types/node@22 -D
   ```
 - upgrade Angular to version v18 and then to v19
 
@@ -16,7 +18,11 @@ Before upgrading Spartacus to the new version with Angular 18, you need to first
 
 > **Warning**
 >
-> Do not select `use-application-builder` migration when migrating to Angular 18. Applications created before SPA 2211.19 doesn't support this builder. Applications created starting from 2211.19 already support it.
+> While migrating to Angular 18, you'll be asked whether to run the `use-application-builder` migration:
+>
+> `❯◯ [use-application-builder] Migrate application projects to the new build system.`
+>
+> Please do not select this migration, i.e. make sure the circle checkbox is empty `◯ [use-application-builder]` and only then hit ENTER.
 
 Follow the [Angular guidelines for upgrading from v17 to v18](https://angular.dev/update-guide?v=17.0-18.0&l=3) and bump the Angular version locally, and update other 3rd party dependencies from Angular ecosystem  to versions compatible with Angular 18 (e.g. `@ng-select/ng-select@13`, `@ngrx/store@18`, `ngx-infinite-scroll@18`):
 
@@ -31,7 +37,12 @@ git commit -m "update angular 18 and 3rd party deps angular 18 compatible"
 
 > **Warning**
 >
-> Hit SPACE to unselect `use-application-builder` migration when migrating to Angular 19. Applications created before SPA 2211.19 doesn't support this builder. Applications created starting from 2211.19 already support it.
+> While migrating to Angular 19, you'll be asked again whether to run the `use-application-builder` migration, but this time it will be preselected:
+> 
+> `❯◉ [use-application-builder] Migrate application projects to the new build system.`
+> 
+> Please unselect select this migration, i.e. first hit SPACE to make the circle checkbox empty `◯ [use-application-builder]` and only then hit ENTER.
+
 
 Follow the [Angular guidelines for upgrading from v18 to v19](https://angular.dev/update-guide?v=18.0-19.0&l=3) and bump the Angular version locally, and update other 3rd party dependencies from Angular ecosystem  to versions compatible with Angular 19 (e.g. `@ng-select/ng-select@14`, `@ngrx/store@19`, `ngx-infinite-scroll@19`):
 
@@ -48,19 +59,57 @@ git commit -m "update angular 19 and 3rd party deps angular 19 compatible"
 After successfully updating the application to Angular 19, execute this command to initiate the Spartacus update process.
 
 ```bash
-ng update @spartacus/schematics@latest
+ng update @spartacus/schematics@2211.35
 ```
 
 ### If using Server Side Rendering (SSR) and `application` builder
 
-For applications with SSR support that use the Angular's `application` builder (i.e. having in `angular.json` the following value: `... "architect": { "build": { "builder": "@angular-devkit/build-angular:application", ...`), you need to adjust the `server.ts` file to be compatible with the output generated by this builder. 
+For applications with SSR support you need to adjust the `server.ts`:
 
 ```diff
 /* ... */
 - const indexHtml = join(browserDistFolder, 'index.html');
 + const indexHtml = join(serverDistFolder, 'index.server.html');
 ```
 
+## Adjust the Bootstrap usage
+
+Spartacus internalized the Bootstrap 4 styles, so you don't need the Bootstrap being installed in your project anymore.
+
+Please follow the guide: [Spartacus migration - Bootstrap](./bootstrap.md)
+
+## Silence Sass deprecation warnings
+
+In  `angular.json` in the section `architect > build > options > stylePreprocessorOptions` please add the property with object `"sass": { "silenceDeprecations":  ["import"] }`
+
+```diff
+              "stylePreprocessorOptions": {
+                "includePaths": ["node_modules/"],
++               "sass": {
++                 "silenceDeprecations": ["import"]
++               }
+              }
+```
+
+**Why it's needed:**
+We need to silence the deprecation warnings for the Sass `@import` because `@import` is used in the Spartacus styles and in the Bootstrap 4 styles (which are imported by the Spartacus styles).
+
+Otherwise, Angular CLI v19 would pollute the terminal with a wall of deprecation warnings when running `ng serve`, making the developer experience less pleasant.
+
+In the future, we plan to remove all the Sass `@import` usages from the Spartacus styles and drop the usage of Bootstrap 4, and only then we will be able to remove the `silenceDeprecations` option.
+
+For more, see:
+
+- https://sass-lang.com/blog/import-is-deprecated
+- https://angular.dev/reference/configs/workspace-config#style-preprocessor-options
+
+## Modernize your app migrated to Angular 19, so it looks like a new Angular 19 app
+
+Now you've migrated your app to Angular 19 and Spartacus 2211.35, but it's not the end of the migration process.
+
+Apps migrated to Angular 19 are not configured exactly the same as the new Angular 19 apps. 
+It is good to modernize your app to look like a new Angular 19 app, because it will help with migrations to future next versions of Angular and Spartacus. So now please follow the last guide: [Modernize Spartacus app migrated from 2211.32 to 2211.35](./modernize-apps-migrated-from-2211.32-to-2211.35.md)
+
 
 
 

docs/migration/2211_35/modernize-apps-migrated-from-2211.32-to-2211.35.md

@@ -0,0 +1,140 @@
+# Modernize apps upgraded from Angular v2211.32 to v2211.35
+
+New Angular 19 apps are configured a bit differently than the Angular 17 apps migrated to v19. This document is a migration guide for modernizing the migrated apps to look as much as possible like the new Angular 19 apps.
+
+### `angular.json`
+
+1. In the section `architect > build > options > assets`, please replace 2 string values in the array: `"src/favicon.ico"` and `"src/assets"` with a single object `{ "glob": "**/*", "input": "public" }`
+
+```diff
+             "assets": [
+-              "src/favicon.ico",
+-              "src/assets"
++              {
++                "glob": "**/*",
++                "input": "public"
++              },
+```
+
+2. Please do the same but now in the `test` section - `architect > test > options > assets`.
+
+
+### `tsconfig.json`
+
+In the `"compilerOptions"` section, please:
+
+- add a new option `"isolatedModules": true`, 
+- remove options `"sourceMap": true`, `"declaration": false`, `"useDefineForClassFields": false`, `"lib": ["ES2022", "dom"]`
+- change the value of `"moduleResolution"` from `"node"` to `"bundler"`
+
+```diff
+  "compilerOptions": {
++    "isolatedModules": true,
+-    "sourceMap": true,
+-    "declaration": false,
+-    "moduleResolution": "node",
++    "moduleResolution": "bundler",
+-    "useDefineForClassFields": false,
+-    "lib": [
+-      "ES2022",
+-      "dom"
+-    ]
+```
+
+
+### `src/assets`
+
+1. Please rename the folder to `/public`
+2. Please move this folder up to the project's root folder.
+
+Example command on Mac/Linux:
+
+```bash
+mv src/assets public
+```
+
+### `src/favicon.ico`
+
+Please move the file to the folder `/public`.
+
+Example command on Mac/Linux:
+
+```bash
+mv src/favicon.ico public
+```
+
+### `src/main.ts`
+
+Please add an option `{ ngZoneEventCoalescing: true }` to the second argument of the`platformBrowserDynamic().bootstrapModule()` call.
+
+```diff
+- platformBrowserDynamic().bootstrapModule(AppModule)
++ platformBrowserDynamic().bootstrapModule(AppModule, {
++   ngZoneEventCoalescing: true,
++ })
+```
+
+## For SSR projects, additionally:
+
+### `server.ts`
+
+1. Please move the file from the root folder to the folder `/src`
+   `server.ts` -> `src/server.ts`
+
+Example command on Mac/Linux:
+
+```bash
+mv server.ts src/server.ts
+```
+
+2. In the contents of the file, please replace the import path of `AppServerModule` from `./src/main.server` to `./main.server`
+
+```diff
+-import AppServerModule from './src/main.server';
++import AppServerModule from './main.server';
+```
+
+
+### `angular.json`
+
+In the section `architect > build > options > ssr > entry` please replace the value `"server.ts"` to `"src/server.ts"`
+
+```diff
+             "ssr": {
+-              "entry": "server.ts"
++              "entry": "src/server.ts"
+             }
+```
+
+### `tsconfig.app.json`
+
+In the `"files"` array, please change the item `"server.ts"` to `"src/server.ts"`
+
+```diff
+   "files": [
+     "src/main.ts",
+     "src/main.server.ts",
+-    "server.ts"
++    "src/server.ts"
+   ],
+```
+
+## For projects using lazy loaded i18n
+
+If your project uses [lazy loaded i18n](https://help.sap.com/docs/SAP_COMMERCE_COMPOSABLE_STOREFRONT/eaef8c61b6d9477daf75bff9ac1b7eb4/775e61ed219c4999852d43be5244e94a.html?q=i18n#lazy-loading) and if you stored your i18n files in the `src/assets/` folder, now you've just moved them to the `public/` folder.
+
+So please update the Spartacus config for the lazy loading of i18n files (likely in your `spartacus-configuration.module.ts` file) to use the new path:
+
+```diff
+ providers: [
+   provideConfig({
+     i18n: {
+       backend: {
+         loader: (lng: string, ns: string) =>
+-          import(`../../assets/i18n-assets/${lng}/${ns}.json`),
++          import(`../../../public/i18n-assets/${lng}/${ns}.json`),
+```
+
+## Congratulations!
+
+Congratulations! You've modernized your app to look like a new Angular 19 app.