@nestjs-ssr/react 0.2.0 → 0.2.2

package/dist/render/index.mjs

@@ -5,7 +5,7 @@ import { join, relative } from 'path';
 import { uneval } from 'devalue';
 import escapeHtml from 'escape-html';
 import { renderToStaticMarkup } from 'react-dom/server';
-import { createElement } from 'react';
+import React, { createElement } from 'react';
 import { switchMap } from 'rxjs/operators';
 
 var __defProp = Object.defineProperty;
@@ -185,8 +185,6 @@ window.__LAYOUTS__ = ${uneval(layoutMetadata)};
 TemplateParserService = _ts_decorate([
   Injectable()
 ], TemplateParserService);
-
-// src/render/error-pages/error-page-development.tsx
 function ErrorPageDevelopment({ error, viewPath, phase }) {
   const stackLines = error.stack ? error.stack.split("\n").slice(1) : [];
   return /* @__PURE__ */ React.createElement("html", {
@@ -260,8 +258,6 @@ function ErrorPageDevelopment({ error, viewPath, phase }) {
   }, /* @__PURE__ */ React.createElement("p", null, /* @__PURE__ */ React.createElement("strong", null, "View Path:"), " ", viewPath), /* @__PURE__ */ React.createElement("p", null, /* @__PURE__ */ React.createElement("strong", null, "Error Phase:"), " ", phase === "shell" ? "Shell (before streaming started)" : "Streaming (during content delivery)"), /* @__PURE__ */ React.createElement("p", null, /* @__PURE__ */ React.createElement("strong", null, "Environment:"), " Development")))));
 }
 __name(ErrorPageDevelopment, "ErrorPageDevelopment");
-
-// src/render/error-pages/error-page-production.tsx
 function ErrorPageProduction() {
   return /* @__PURE__ */ React.createElement("html", {
     lang: "en"
@@ -671,60 +667,79 @@ var RenderService = class _RenderService {
   async renderToStream(viewComponent, data = {}, res, head) {
     const startTime = Date.now();
     let shellReadyTime = 0;
-    try {
-      let template = this.template;
-      if (this.vite) {
-        template = await this.vite.transformIndexHtml("/", template);
-      }
-      const templateParts = this.templateParser.parseTemplate(template);
-      let renderModule;
-      if (this.vite) {
-        renderModule = await this.vite.ssrLoadModule(this.entryServerPath);
-      } else {
-        if (this.serverManifest) {
-          const manifestEntry = Object.entries(this.serverManifest).find(([key, value]) => value.isEntry && key.includes("entry-server"));
-          if (manifestEntry) {
-            const [, entry] = manifestEntry;
-            const serverPath = join(process.cwd(), "dist/server", entry.file);
-            renderModule = await import(serverPath);
+    return new Promise((resolve, reject) => {
+      const executeStream = /* @__PURE__ */ __name(async () => {
+        let template = this.template;
+        if (this.vite) {
+          template = await this.vite.transformIndexHtml("/", template);
+        }
+        const templateParts = this.templateParser.parseTemplate(template);
+        let renderModule;
+        if (this.vite) {
+          renderModule = await this.vite.ssrLoadModule(this.entryServerPath);
+        } else {
+          if (this.serverManifest) {
+            const manifestEntry = Object.entries(this.serverManifest).find(([key, value]) => value.isEntry && key.includes("entry-server"));
+            if (manifestEntry) {
+              const [, entry] = manifestEntry;
+              const serverPath = join(process.cwd(), "dist/server", entry.file);
+              renderModule = await import(serverPath);
+            } else {
+              throw new Error("Server bundle not found in manifest. Run `pnpm build:server` to generate the server bundle.");
+            }
           } else {
             throw new Error("Server bundle not found in manifest. Run `pnpm build:server` to generate the server bundle.");
           }
-        } else {
-          throw new Error("Server bundle not found in manifest. Run `pnpm build:server` to generate the server bundle.");
         }
-      }
-      const { data: pageData, __context: context, __layouts: layouts } = data;
-      const componentName = viewComponent.displayName || viewComponent.name || "Component";
-      const inlineScripts = this.templateParser.buildInlineScripts(pageData, context, componentName, layouts);
-      const clientScript = this.templateParser.getClientScriptTag(this.isDevelopment, this.manifest);
-      const stylesheetTags = this.templateParser.getStylesheetTags(this.isDevelopment, this.manifest);
-      const headTags = this.templateParser.buildHeadTags(head);
-      let didError = false;
-      const { pipe, abort } = renderModule.renderComponentStream(viewComponent, data, {
-        onShellReady: /* @__PURE__ */ __name(() => {
-          shellReadyTime = Date.now();
-          res.statusCode = didError ? 500 : 200;
-          res.setHeader("Content-Type", "text/html; charset=utf-8");
-          let htmlStart = templateParts.htmlStart;
-          htmlStart = htmlStart.replace("<!--styles-->", stylesheetTags);
-          htmlStart = htmlStart.replace("<!--head-meta-->", headTags);
-          res.write(htmlStart);
-          res.write(templateParts.rootStart);
-          pipe(res);
-          if (this.isDevelopment) {
-            const ttfb = shellReadyTime - startTime;
-            this.logger.log(`[SSR] ${componentName} shell ready in ${ttfb}ms (stream mode - TTFB)`);
+        const { data: pageData, __context: context, __layouts: layouts } = data;
+        const componentName = viewComponent.displayName || viewComponent.name || "Component";
+        const inlineScripts = this.templateParser.buildInlineScripts(pageData, context, componentName, layouts);
+        const clientScript = this.templateParser.getClientScriptTag(this.isDevelopment, this.manifest);
+        const stylesheetTags = this.templateParser.getStylesheetTags(this.isDevelopment, this.manifest);
+        const headTags = this.templateParser.buildHeadTags(head);
+        let didError = false;
+        let shellErrorOccurred = false;
+        const { PassThrough } = await import('stream');
+        const reactStream = new PassThrough();
+        let allReadyFired = false;
+        const { pipe, abort } = renderModule.renderComponentStream(viewComponent, data, {
+          onShellReady: /* @__PURE__ */ __name(() => {
+            shellReadyTime = Date.now();
+            if (!res.headersSent) {
+              res.statusCode = didError ? 500 : 200;
+              res.setHeader("Content-Type", "text/html; charset=utf-8");
+            }
+            let htmlStart = templateParts.htmlStart;
+            htmlStart = htmlStart.replace("<!--styles-->", stylesheetTags);
+            htmlStart = htmlStart.replace("<!--head-meta-->", headTags);
+            res.write(htmlStart);
+            res.write(templateParts.rootStart);
+            pipe(reactStream);
+            reactStream.pipe(res, {
+              end: false
+            });
+            if (this.isDevelopment) {
+              const ttfb = shellReadyTime - startTime;
+              this.logger.log(`[SSR] ${componentName} shell ready in ${ttfb}ms (stream mode - TTFB)`);
+            }
+          }, "onShellReady"),
+          onShellError: /* @__PURE__ */ __name((error) => {
+            shellErrorOccurred = true;
+            this.streamingErrorHandler.handleShellError(error, res, componentName, this.isDevelopment);
+            resolve();
+          }, "onShellError"),
+          onError: /* @__PURE__ */ __name((error) => {
+            didError = true;
+            this.streamingErrorHandler.handleStreamError(error, componentName);
+          }, "onError"),
+          onAllReady: /* @__PURE__ */ __name(() => {
+            allReadyFired = true;
+          }, "onAllReady")
+        });
+        reactStream.on("end", () => {
+          if (shellErrorOccurred) {
+            return;
           }
-        }, "onShellReady"),
-        onShellError: /* @__PURE__ */ __name((error) => {
-          this.streamingErrorHandler.handleShellError(error, res, componentName, this.isDevelopment);
-        }, "onShellError"),
-        onError: /* @__PURE__ */ __name((error) => {
-          didError = true;
-          this.streamingErrorHandler.handleStreamError(error, componentName);
-        }, "onError"),
-        onAllReady: /* @__PURE__ */ __name(() => {
           res.write(inlineScripts);
           res.write(clientScript);
           res.write(templateParts.rootEnd);
@@ -733,17 +748,25 @@ var RenderService = class _RenderService {
           if (this.isDevelopment) {
             const totalTime = Date.now() - startTime;
             const streamTime = Date.now() - shellReadyTime;
-            this.logger.log(`[SSR] ${componentName} streaming complete in ${totalTime}ms total (${streamTime}ms streaming)`);
+            const viaAllReady = allReadyFired ? " (onAllReady fired)" : " (onAllReady never fired)";
+            this.logger.log(`[SSR] ${componentName} streaming complete in ${totalTime}ms total (${streamTime}ms streaming)${viaAllReady}`);
           }
-        }, "onAllReady")
+          resolve();
+        });
+        reactStream.on("error", (error) => {
+          reject(error);
+        });
+        res.on("close", () => {
+          abort();
+          resolve();
+        });
+      }, "executeStream");
+      executeStream().catch((error) => {
+        const componentName = typeof viewComponent === "function" ? viewComponent.name : String(viewComponent);
+        this.streamingErrorHandler.handleShellError(error, res, componentName, this.isDevelopment);
+        resolve();
       });
-      res.on("close", () => {
-        abort();
-      });
-    } catch (error) {
-      const componentName = typeof viewComponent === "function" ? viewComponent.name : String(viewComponent);
-      this.streamingErrorHandler.handleShellError(error, res, componentName, this.isDevelopment);
-    }
+    });
   }
 };
 RenderService = _ts_decorate3([
@@ -859,6 +882,9 @@ var RenderInterceptor = class {
       const httpContext = context.switchToHttp();
       const request = httpContext.getRequest();
       const response = httpContext.getResponse();
+      if (typeof data === "string") {
+        return data;
+      }
       const renderContext = {
         url: request.url,
         path: request.path,
@@ -949,11 +975,23 @@ var ViteInitializerService = class _ViteInitializerService {
   viteMode;
   vitePort;
   viteServer = null;
+  isShuttingDown = false;
   constructor(renderService, httpAdapterHost, viteConfig) {
     this.renderService = renderService;
     this.httpAdapterHost = httpAdapterHost;
     this.viteMode = viteConfig?.mode || "embedded";
     this.vitePort = viteConfig?.port || 5173;
+    this.registerSignalHandlers();
+  }
+  registerSignalHandlers() {
+    const cleanup = /* @__PURE__ */ __name(async (signal) => {
+      if (this.isShuttingDown) return;
+      this.isShuttingDown = true;
+      this.logger.log(`Received ${signal}, closing Vite server...`);
+      await this.closeViteServer();
+    }, "cleanup");
+    process.once("SIGTERM", () => cleanup("SIGTERM"));
+    process.once("SIGINT", () => cleanup("SIGINT"));
   }
   async onModuleInit() {
     const isDevelopment = process.env.NODE_ENV !== "production";
@@ -1042,9 +1080,23 @@ var ViteInitializerService = class _ViteInitializerService {
   * This prevents port conflicts on hot reload
   */
   async onModuleDestroy() {
+    await this.closeViteServer();
+  }
+  /**
+  * Cleanup: Close Vite server on application shutdown
+  * Belt-and-suspenders approach with onModuleDestroy
+  */
+  async onApplicationShutdown() {
+    await this.closeViteServer();
+  }
+  async closeViteServer() {
+    if (this.isShuttingDown && !this.viteServer) return;
+    this.isShuttingDown = true;
     if (this.viteServer) {
       try {
+        this.renderService.setViteServer(null);
         await this.viteServer.close();
+        this.viteServer = null;
         this.logger.log("\u2713 Vite server closed");
       } catch (error) {
         this.logger.warn(`Failed to close Vite server: ${error.message}`);

package/dist/render-response.interface-Dc-Kwb09.d.mts

@@ -0,0 +1,104 @@
+/**
+ * HTML head data for SEO and page metadata
+ */
+interface HeadData {
+    /** Page title (appears in browser tab and search results) */
+    title?: string;
+    /** Page description for search engines */
+    description?: string;
+    /** Page keywords (legacy, less important for modern SEO) */
+    keywords?: string;
+    /** Canonical URL for duplicate content */
+    canonical?: string;
+    /** Open Graph title for social media sharing */
+    ogTitle?: string;
+    /** Open Graph description for social media sharing */
+    ogDescription?: string;
+    /** Open Graph image URL for social media previews */
+    ogImage?: string;
+    /** Additional link tags (fonts, icons, preloads, etc.) */
+    links?: Array<{
+        rel: string;
+        href: string;
+        as?: string;
+        type?: string;
+        crossorigin?: string;
+        [key: string]: any;
+    }>;
+    /** Additional meta tags */
+    meta?: Array<{
+        name?: string;
+        property?: string;
+        content: string;
+        [key: string]: any;
+    }>;
+    /** Script tags for analytics, tracking, etc. */
+    scripts?: Array<{
+        src?: string;
+        async?: boolean;
+        defer?: boolean;
+        type?: string;
+        innerHTML?: string;
+        [key: string]: any;
+    }>;
+    /** JSON-LD structured data for search engines */
+    jsonLd?: Array<Record<string, any>>;
+    /** Attributes to add to <html> tag (e.g., lang, dir) */
+    htmlAttributes?: Record<string, string>;
+    /** Attributes to add to <body> tag (e.g., class, data-theme) */
+    bodyAttributes?: Record<string, string>;
+}
+/**
+ * Response structure for SSR rendering
+ *
+ * Can be returned from controllers decorated with @Render.
+ * For backwards compatibility, controllers can also return plain objects
+ * which will be auto-wrapped as { props: data }.
+ *
+ * @example
+ * ```typescript
+ * // Simple case - just props (auto-wrapped)
+ * @Render('views/home')
+ * getHome() {
+ *   return { message: 'Hello' };
+ *   // Treated as: { props: { message: 'Hello' } }
+ * }
+ *
+ * // Advanced case - with head data and layout props
+ * @Render('views/user')
+ * getUser(@Param('id') id: string) {
+ *   const user = await this.userService.findOne(id);
+ *   return {
+ *     props: { user },
+ *     layoutProps: {
+ *       title: user.name,
+ *       subtitle: 'User Profile'
+ *     },
+ *     head: {
+ *       title: `${user.name} - Profile`,
+ *       description: user.bio,
+ *       ogImage: user.avatar
+ *     }
+ *   };
+ * }
+ * ```
+ */
+interface RenderResponse<T = any> {
+    /** Props passed to the React component */
+    props: T;
+    /** HTML head data (title, meta tags, links) */
+    head?: HeadData;
+    /**
+     * Props passed to layout components (dynamic, per-request)
+     *
+     * These props are merged with static layout props from decorators:
+     * - Static props from @Layout decorator (controller level)
+     * - Static props from @Render decorator (method level)
+     * - Dynamic props from this field (highest priority)
+     *
+     * All layout components in the hierarchy receive the merged props.
+     */
+    layoutProps?: Record<string, any>;
+}
+
+export type { HeadData as H, RenderResponse as R };

package/dist/render-response.interface-Dc-Kwb09.d.ts

@@ -0,0 +1,104 @@
+/**
+ * HTML head data for SEO and page metadata
+ */
+interface HeadData {
+    /** Page title (appears in browser tab and search results) */
+    title?: string;
+    /** Page description for search engines */
+    description?: string;
+    /** Page keywords (legacy, less important for modern SEO) */
+    keywords?: string;
+    /** Canonical URL for duplicate content */
+    canonical?: string;
+    /** Open Graph title for social media sharing */
+    ogTitle?: string;
+    /** Open Graph description for social media sharing */
+    ogDescription?: string;
+    /** Open Graph image URL for social media previews */
+    ogImage?: string;
+    /** Additional link tags (fonts, icons, preloads, etc.) */
+    links?: Array<{
+        rel: string;
+        href: string;
+        as?: string;
+        type?: string;
+        crossorigin?: string;
+        [key: string]: any;
+    }>;
+    /** Additional meta tags */
+    meta?: Array<{
+        name?: string;
+        property?: string;
+        content: string;
+        [key: string]: any;
+    }>;
+    /** Script tags for analytics, tracking, etc. */
+    scripts?: Array<{
+        src?: string;
+        async?: boolean;
+        defer?: boolean;
+        type?: string;
+        innerHTML?: string;
+        [key: string]: any;
+    }>;
+    /** JSON-LD structured data for search engines */
+    jsonLd?: Array<Record<string, any>>;
+    /** Attributes to add to <html> tag (e.g., lang, dir) */
+    htmlAttributes?: Record<string, string>;
+    /** Attributes to add to <body> tag (e.g., class, data-theme) */
+    bodyAttributes?: Record<string, string>;
+}
+/**
+ * Response structure for SSR rendering
+ *
+ * Can be returned from controllers decorated with @Render.
+ * For backwards compatibility, controllers can also return plain objects
+ * which will be auto-wrapped as { props: data }.
+ *
+ * @example
+ * ```typescript
+ * // Simple case - just props (auto-wrapped)
+ * @Render('views/home')
+ * getHome() {
+ *   return { message: 'Hello' };
+ *   // Treated as: { props: { message: 'Hello' } }
+ * }
+ *
+ * // Advanced case - with head data and layout props
+ * @Render('views/user')
+ * getUser(@Param('id') id: string) {
+ *   const user = await this.userService.findOne(id);
+ *   return {
+ *     props: { user },
+ *     layoutProps: {
+ *       title: user.name,
+ *       subtitle: 'User Profile'
+ *     },
+ *     head: {
+ *       title: `${user.name} - Profile`,
+ *       description: user.bio,
+ *       ogImage: user.avatar
+ *     }
+ *   };
+ * }
+ * ```
+ */
+interface RenderResponse<T = any> {
+    /** Props passed to the React component */
+    props: T;
+    /** HTML head data (title, meta tags, links) */
+    head?: HeadData;
+    /**
+     * Props passed to layout components (dynamic, per-request)
+     *
+     * These props are merged with static layout props from decorators:
+     * - Static props from @Layout decorator (controller level)
+     * - Static props from @Render decorator (method level)
+     * - Dynamic props from this field (highest priority)
+     *
+     * All layout components in the hierarchy receive the merged props.
+     */
+    layoutProps?: Record<string, any>;
+}
+
+export type { HeadData as H, RenderResponse as R };

package/dist/templates/entry-client.tsx

@@ -1,16 +1,19 @@
-/// <reference path="../global.d.ts" />
+/// <reference types="@nestjs-ssr/react/global" />
 import React, { StrictMode } from 'react';
 import { hydrateRoot } from 'react-dom/client';
-import { PageContextProvider } from '../react/hooks/use-page-context';
+import { PageContextProvider } from '@nestjs-ssr/react/client';
 
 const componentName = window.__COMPONENT_NAME__;
 const initialProps = window.__INITIAL_STATE__ || {};
 const renderContext = window.__CONTEXT__ || {};
 
 // Auto-import all view components using Vite's glob feature
+// Exclude entry-client.tsx and entry-server.tsx from the glob
 // @ts-ignore - Vite-specific API
 const modules: Record<string, { default: React.ComponentType<any> }> =
-  import.meta.glob('@/views/**/*.tsx', { eager: true });
+  import.meta.glob(['@/views/**/*.tsx', '!@/views/entry-*.tsx'], {
+    eager: true,
+  });
 
 // Build a map of components with their metadata
 // Filter out entry files and modules without default exports

package/dist/templates/entry-server.tsx

@@ -1,6 +1,6 @@
 import React from 'react';
-import { renderToString } from 'react-dom/server';
-import { PageContextProvider } from '../react/hooks/use-page-context';
+import { renderToString, renderToPipeableStream } from 'react-dom/server';
+import { PageContextProvider } from '@nestjs-ssr/react';
 
 /**
  * Compose a component with its layouts from the interceptor
@@ -23,6 +23,10 @@ function composeWithLayouts(
   return result;
 }
 
+/**
+ * String-based SSR (mode: 'string')
+ * Simple, synchronous rendering
+ */
 export function renderComponent(
   ViewComponent: React.ComponentType<any>,
   data: any,
@@ -39,3 +43,30 @@ export function renderComponent(
 
   return renderToString(wrappedElement);
 }
+
+/**
+ * Streaming SSR (mode: 'stream' - default)
+ * Modern approach with progressive rendering and Suspense support
+ */
+export function renderComponentStream(
+  ViewComponent: React.ComponentType<any>,
+  data: any,
+  callbacks?: {
+    onShellReady?: () => void;
+    onShellError?: (error: unknown) => void;
+    onError?: (error: unknown) => void;
+    onAllReady?: () => void;
+  },
+) {
+  const { data: pageData, __context: context, __layouts: layouts } = data;
+  const composedElement = composeWithLayouts(ViewComponent, pageData, layouts);
+
+  // Wrap with PageContextProvider to make context available via hooks
+  const wrappedElement = (
+    <PageContextProvider context={context}>
+      {composedElement}
+    </PageContextProvider>
+  );
+
+  return renderToPipeableStream(wrappedElement, callbacks);
+}

package/dist/templates/index.html

@@ -1,14 +1,17 @@
 <!DOCTYPE html>
 <html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>NestJS React SSR</title>
-    <!--styles-->
-  </head>
-  <body>
-    <div id="root"><!--app-html--></div>
-    <!--initial-state-->
-    <!--client-scripts-->
-  </body>
-</html>
+
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <!--head-meta-->
+  <!--styles-->
+</head>
+
+<body>
+  <div id="root"><!--app-html--></div>
+  <!--initial-state-->
+  <!--client-scripts-->
+</body>
+
+</html>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nestjs-ssr/react",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "React SSR for NestJS that respects Clean Architecture. Proper DI, SOLID principles, clear separation of concerns.",
   "keywords": [
     "nestjs",
@@ -47,6 +47,11 @@
       "import": "./dist/index.mjs",
       "require": "./dist/index.js"
     },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.mjs",
+      "require": "./dist/client.js"
+    },
     "./render": {
       "types": "./dist/render/index.d.ts",
       "import": "./dist/render/index.mjs",
@@ -79,6 +84,12 @@
     "test:watch": "vitest",
     "test:ui": "vitest --ui",
     "test:coverage": "vitest run --coverage",
+    "test:integration": "pnpm test:integration:setup && pnpm test:integration:dev && pnpm test:integration:prod",
+    "test:integration:setup": "tsx test/integration/setup/create-fixtures.ts",
+    "test:integration:dev": "TEST_MODE=dev playwright test -c test/integration/playwright.config.ts",
+    "test:integration:prod": "TEST_MODE=prod playwright test -c test/integration/playwright.config.ts",
+    "test:integration:run": "pnpm test:integration:dev",
+    "test:integration:clean": "rm -rf test/integration/fixtures/*/",
     "size": "size-limit",
     "api:extract": "api-extractor run --local --verbose",
     "api:check": "api-extractor run --verbose",
@@ -120,6 +131,7 @@
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.55.2",
+    "@playwright/test": "^1.49.0",
     "@nestjs/common": "^11.0.0",
     "@nestjs/core": "^11.0.0",
     "@nestjs/platform-express": "^11.0.0",

package/src/templates/entry-client.tsx

@@ -1,16 +1,19 @@
-/// <reference path="../global.d.ts" />
+/// <reference types="@nestjs-ssr/react/global" />
 import React, { StrictMode } from 'react';
 import { hydrateRoot } from 'react-dom/client';
-import { PageContextProvider } from '../react/hooks/use-page-context';
+import { PageContextProvider } from '@nestjs-ssr/react/client';
 
 const componentName = window.__COMPONENT_NAME__;
 const initialProps = window.__INITIAL_STATE__ || {};
 const renderContext = window.__CONTEXT__ || {};
 
 // Auto-import all view components using Vite's glob feature
+// Exclude entry-client.tsx and entry-server.tsx from the glob
 // @ts-ignore - Vite-specific API
 const modules: Record<string, { default: React.ComponentType<any> }> =
-  import.meta.glob('@/views/**/*.tsx', { eager: true });
+  import.meta.glob(['@/views/**/*.tsx', '!@/views/entry-*.tsx'], {
+    eager: true,
+  });
 
 // Build a map of components with their metadata
 // Filter out entry files and modules without default exports