chore(dev): added ssr mode (#DS-3828) (#799)

Author: NikGurev

.github/dependabot.yml

@@ -115,3 +115,7 @@ updates:
         patterns:
           - 'luxon'
           - '@types/luxon'
+      express:
+        patterns:
+          - 'express'
+          - '@types/express'

angular.json

@@ -1873,6 +1873,41 @@
                 }
             }
         },
+        "dev-ssr": {
+            "projectType": "application",
+            "root": "packages/components-dev/ssr",
+            "sourceRoot": "packages/components-dev/ssr",
+            "architect": {
+                "build": {
+                    "builder": "@angular-devkit/build-angular:application",
+                    "options": {
+                        "outputPath": {
+                            "base": "dist/components-dev/ssr"
+                        },
+                        "tsConfig": "packages/components-dev/ssr/tsconfig.app.json",
+                        "index": "packages/components-dev/index.html",
+                        "styles": ["packages/components-dev/main.scss"],
+                        "polyfills": ["zone.js"],
+                        "extractLicenses": false,
+                        "sourceMap": true,
+                        "optimization": false,
+                        "namedChunks": true,
+                        "browser": "packages/components-dev/ssr/main.ts",
+                        "server": "packages/components-dev/ssr/main.server.ts",
+                        "prerender": true,
+                        "ssr": {
+                            "entry": "packages/components-dev/ssr/server.ts"
+                        }
+                    }
+                },
+                "serve": {
+                    "builder": "@angular-devkit/build-angular:dev-server",
+                    "options": {
+                        "buildTarget": "dev-ssr:build"
+                    }
+                }
+            }
+        },
         "dev-table": {
             "projectType": "application",
             "root": "packages/components-dev/table",

docs/guides/09-ssr-dev.md

@@ -0,0 +1,45 @@
+## Server-side rendering (SSR) setup for local development
+
+This guide explains how to enable SSR for your component development.
+
+### Set up server config
+
+Update `main.server.ts` with specific component development app:
+
+```typescript
+// ...other imports
+import { DevApp } from '../<component>/module';
+// ...other code
+```
+
+Replace `<component>` with the actual component name (e.g., `button`, `modal`, etc.).
+
+---
+
+### Client Hydration with live server
+
+Update `main.ts` with specific component development app:
+
+```typescript
+// ...other imports
+import { DevApp } from '../<component>/module';
+// ...other code
+```
+
+Replace `<component>` with the actual component name (e.g., `button`, `modal`, etc.).
+
+---
+
+### How to run SSR locally
+
+Build and run the server using the following commands:
+
+```bash
+yarn run dev:ssr-start
+```
+
+or for live server with client hydration
+
+```bash
+yarn run dev:ssr
+```

package.json

@@ -58,6 +58,7 @@
         "@angular/platform-browser-dynamic": "18.2.13",
         "@angular/platform-server": "18.2.13",
         "@angular/router": "18.2.13",
+        "@angular/ssr": "18.2.19",
         "@commitlint/cli": "^19.8.1",
         "@commitlint/config-conventional": "^19.8.1",
         "@cspell/dict-markdown": "^2.0.10",
@@ -85,6 +86,7 @@
         "@types/conventional-changelog": "^3.1.5",
         "@types/conventional-changelog-writer": "^4.0.10",
         "@types/eslint": "^8.56.12",
+        "@types/express": "^4",
         "@types/fs-extra": "^5.1.0",
         "@types/glob": "^7.1.4",
         "@types/inquirer": "^7.3.3",
@@ -113,6 +115,7 @@
         "eslint-plugin-prettier": "^5.4.1",
         "eslint-plugin-promise": "^7.2.1",
         "eslint-plugin-rxjs": "^5.0.3",
+        "express": "^4.18.2",
         "firebase-tools": "^13.35.1",
         "fs-extra": "^5.0.0",
         "glob": "^7.1.3",
@@ -245,6 +248,8 @@
         "dev:sidebar": "ng serve dev-sidebar --port 3003",
         "dev:sidepanel": "ng serve dev-sidepanel --port 3003",
         "dev:splitter": "ng serve dev-splitter --port 3003",
+        "dev:ssr": "ng serve dev-ssr --port 3003",
+        "dev:ssr-start": "ng build dev-ssr && node dist/components-dev/ssr/server/server.mjs",
         "dev:table": "ng serve dev-table --port 3003",
         "dev:tabs": "ng serve dev-tabs --port 3003",
         "dev:tag": "ng serve dev-tag --port 3003",

packages/components-dev/breadcrumbs/main.ts

@@ -1,9 +1,10 @@
+import { ApplicationConfig } from '@angular/core';
 import { bootstrapApplication } from '@angular/platform-browser';
 import { provideAnimations } from '@angular/platform-browser/animations';
 import { provideRouter, Routes } from '@angular/router';
 import { DevAboutPage, DevApp, DevProductDetailsPage, DevProductsPage } from './module';
 
-const routes: Routes = [
+export const devRoutes: Routes = [
     {
         path: '',
         data: { breadcrumb: 'Home' },
@@ -29,8 +30,10 @@ const routes: Routes = [
     }
 ];
 
-bootstrapApplication(DevApp, {
+export const devAppConfig: ApplicationConfig = {
     providers: [
         provideAnimations(),
-        provideRouter(routes)]
-}).catch((error) => console.error(error));
+        provideRouter(devRoutes)]
+};
+
+bootstrapApplication(DevApp, devAppConfig).catch((error) => console.error(error));

packages/components-dev/ssr/app.config.server.ts

@@ -0,0 +1,11 @@
+import { ApplicationConfig } from '@angular/core';
+import { provideClientHydration, withEventReplay } from '@angular/platform-browser';
+import { provideServerRendering } from '@angular/platform-server';
+import { provideRouter } from '@angular/router';
+
+export const devConfig: ApplicationConfig = {
+    providers: [
+        provideClientHydration(withEventReplay()),
+        provideServerRendering(),
+        provideRouter([])]
+};

packages/components-dev/ssr/main.server.ts

@@ -0,0 +1,7 @@
+import { bootstrapApplication } from '@angular/platform-browser';
+import { DevApp } from '../breadcrumbs/module';
+import { devConfig } from './app.config.server';
+
+const devBootstrap = () => bootstrapApplication(DevApp, devConfig);
+
+export default devBootstrap;

packages/components-dev/ssr/main.ts

@@ -0,0 +1,5 @@
+import { bootstrapApplication } from '@angular/platform-browser';
+import { devAppConfig } from '../breadcrumbs/main';
+import { DevApp } from '../breadcrumbs/module';
+
+bootstrapApplication(DevApp, devAppConfig).catch((error) => console.error(error));

packages/components-dev/ssr/server.ts

@@ -0,0 +1,62 @@
+import { APP_BASE_HREF } from '@angular/common';
+import { CommonEngine } from '@angular/ssr';
+import express from 'express';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import devBootstrap from './main.server';
+
+// The Express app is exported so that it can be used by serverless Functions.
+export function devApp(): express.Express {
+    const server = express();
+    const serverDistFolder = dirname(fileURLToPath(import.meta.url));
+    const browserDistFolder = resolve(serverDistFolder, '../browser');
+    const indexHtml = join(serverDistFolder, 'index.server.html');
+
+    const commonEngine = new CommonEngine();
+
+    server.set('view engine', 'html');
+    server.set('views', browserDistFolder);
+
+    // Example Express Rest API endpoints
+    // server.get('/api/**', (req, res) => { });
+    // Serve static files from /browser
+    server.get(
+        '**',
+        express.static(browserDistFolder, {
+            maxAge: '1y',
+            index: 'index.html'
+        })
+    );
+
+    // All regular routes use the Angular engine
+    server.get('**', (req, res, next) => {
+        const { protocol, originalUrl, baseUrl, headers } = req;
+
+        commonEngine
+            .render({
+                bootstrap: devBootstrap,
+                documentFilePath: indexHtml,
+                url: `${protocol}://${headers.host}${originalUrl}`,
+                publicPath: browserDistFolder,
+                providers: [{ provide: APP_BASE_HREF, useValue: baseUrl }]
+            })
+            .then((html) => res.send(html))
+            // eslint-disable-next-line promise/no-callback-in-promise
+            .catch((err) => next(err));
+    });
+
+    return server;
+}
+
+function run(): void {
+    const port = process.env['PORT'] || 4000;
+
+    // Start up the Node server
+    const server = devApp();
+
+    server.listen(port, () => {
+        console.log(`Node Express server listening on http://localhost:${port}`);
+    });
+}
+
+run();

packages/components-dev/ssr/tsconfig.app.json

@@ -0,0 +1,16 @@
+{
+    "extends": "../tsconfig.json",
+    "include": ["**/*.d.ts"],
+    "files": [
+        "main.ts",
+        "main.server.ts",
+        "server.ts",
+        "../breadcrumbs/main.ts",
+        "../breadcrumbs/module.ts"
+    ],
+    "compilerOptions": {
+        "types": [
+            "node"
+        ]
+    }
+}

tools/cspell-locales/en.json

@@ -31,6 +31,7 @@
         "timepicker",
         "unclickable",
         "overlayscrollbars",
-        "Topbar"
+        "Topbar",
+        "prerender"
     ]
 }