@nestjs-ssr/react 0.3.6 → 0.3.8

package/README.md

@@ -3,70 +3,82 @@
 [![npm version](https://img.shields.io/npm/v/@nestjs-ssr/react)](https://www.npmjs.com/package/@nestjs-ssr/react)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-React as a view layer for NestJS. Controllers return data. Components render it. One app.
+**React SSR for NestJS. One app. One deploy. Full type safety from database to DOM.**
 
-**[Documentation](https://georgialexandrov.github.io/nestjs-ssr/)** | **[Getting Started](https://georgialexandrov.github.io/nestjs-ssr/guide/installation)**
+No separate frontend. No second router. No type boundary you maintain by hand. Controllers return data, components render it, TypeScript enforces the contract.
 
-## Quick Start
+**[Documentation](https://georgialexandrov.github.io/nestjs-ssr/)** | **[Get Started](https://georgialexandrov.github.io/nestjs-ssr/guide/installation)**
 
-```bash
-npx @nestjs-ssr/react init
-```
+## The whole contract in two files
 
 ```typescript
-@Get(':id')
-@Render(ProductDetail)
-async getProduct(@Param('id') id: string) {
-  return { product: await this.productService.findById(id) };
+// recipes.controller.ts
+import { Controller, Get, Param } from '@nestjs/common';
+import { Render, Layout } from '@nestjs-ssr/react';
+import { RecipesLayout } from './views/recipes-layout';
+import { RecipeDetail } from './views/recipe-detail';
+
+@Controller('recipes')
+@Layout(RecipesLayout)
+export class RecipesController {
+  @Get(':slug')
+  @Render(RecipeDetail)
+  getRecipe(@Param('slug') slug: string) {
+    const recipe = this.recipes.findBySlug(slug);
+    return {
+      recipe,
+      chef: this.chefs.findById(recipe.chefId),
+      head: { title: recipe.name },
+    };
+  }
 }
 ```
 
 ```tsx
-export default function ProductDetail({
-  product,
-}: PageProps<{ product: Product }>) {
-  return <h1>{product.name}</h1>;
+// recipe-detail.tsx
+import { PageProps } from '@nestjs-ssr/react';
+
+export default function RecipeDetail({
+  recipe,
+  chef,
+}: PageProps<RecipeDetailProps>) {
+  return (
+    <article>
+      <h1>{recipe.name}</h1>
+      <p>{recipe.description}</p>
+      <IngredientList items={recipe.ingredients} />
+      <ChefCard chef={chef} />
+    </article>
+  );
 }
 ```
 
-Type mismatch = build fails.
+Return the wrong shape and TypeScript catches it before the code runs.
 
-## Test in Isolation
+## Nothing breaks
 
-```typescript
-// Controller: no React
-expect(await controller.getProduct('123')).toEqual({ product: { id: '123' } });
-
-// Component: no NestJS
-render(<ProductDetail data={{ product: mockProduct }} />);
-```
+Your NestJS app stays exactly as it is. Routing, guards, pipes, interceptors, services, modules, testing — all unchanged. You're adding a view layer, not rewriting your backend.
 
-## What You Get
+## Everything improves
 
-**Rendering:**
+- **One type, both sides** — controller return type is the component's props. Change one, the other breaks at build time.
+- **Layouts that stay put** — nested layouts persist across navigations. Header, sidebar, shell — rendered once, never re-mounted.
+- **No full reloads** — link clicks fetch only the changed segment. State, scroll position, animations stay alive.
+- **Stream or string** — `renderToString` for simplicity, `renderToPipeableStream` for performance. Suspense boundaries stream as they resolve.
+- **SEO out of the box** — title, meta, Open Graph, JSON-LD. Return `head` from your controller.
+- **Vite HMR** — instant updates, no page refresh. Works with Express and Fastify.
 
-- Type-safe data flow from controller to component
-- Hierarchical layouts (root → controller → method)
-- Head tags (title, meta, OG, JSON-LD)
-- Stream or string mode
+## Add it to an existing NestJS app
 
-**Request Context:**
-
-- Hooks: `useParams()`, `useQuery()`, `useHeader()`, `useCookie()`
-- Whitelist what reaches the client
-
-**Development:**
+```bash
+npx @nestjs-ssr/react init
+```
 
-- Integrated mode: Vite inside NestJS, one process
-- Separate mode: standalone Vite server, true HMR
+One command. Works with Express and Fastify.
 
 ## Requirements
 
-- Node.js 20+
-- NestJS 11+
-- React 19+
-- Vite 6+
-- TypeScript 5+
+Node.js 20+ / NestJS 11+ / React 19+ / Vite 6+ / TypeScript 5+
 
 ## Documentation
 
@@ -74,6 +86,8 @@ render(<ProductDetail data={{ product: mockProduct }} />);
 
 - [Installation](https://georgialexandrov.github.io/nestjs-ssr/guide/installation)
 - [Rendering](https://georgialexandrov.github.io/nestjs-ssr/guide/rendering)
+- [Layouts](https://georgialexandrov.github.io/nestjs-ssr/guide/layouts)
+- [Client-Side Navigation](https://georgialexandrov.github.io/nestjs-ssr/guide/navigation)
 - [Request Context](https://georgialexandrov.github.io/nestjs-ssr/guide/request-context)
 - [Configuration](https://georgialexandrov.github.io/nestjs-ssr/guide/configuration)
 - [API Reference](https://georgialexandrov.github.io/nestjs-ssr/guide/api)

package/dist/client.d.mts

@@ -1,4 +1,4 @@
-export { a as PageContextProvider, P as PageProps, c as createSSRHooks, j as updatePageContext, i as useCookie, h as useCookies, g as useHeader, f as useHeaders, u as usePageContext, b as useParams, d as useQuery, e as useRequest } from './use-page-context-CVC9DHcL.mjs';
+export { a as PageContextProvider, P as PageProps, c as createSSRHooks, j as updatePageContext, u as useCookie, b as useCookies, d as useHeader, e as useHeaders, f as usePageContext, g as useParams, h as useQuery, i as useRequest } from './use-page-context-CmxWHIK3.mjs';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import React from 'react';
 export { R as RenderContext } from './render-response.interface-ClWJXKL4.mjs';

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-export { a as PageContextProvider, P as PageProps, c as createSSRHooks, j as updatePageContext, i as useCookie, h as useCookies, g as useHeader, f as useHeaders, u as usePageContext, b as useParams, d as useQuery, e as useRequest } from './use-page-context-DChgHhL9.js';
+export { a as PageContextProvider, P as PageProps, c as createSSRHooks, j as updatePageContext, u as useCookie, b as useCookies, d as useHeader, e as useHeaders, f as usePageContext, g as useParams, h as useQuery, i as useRequest } from './use-page-context-CUV31oda.js';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import React from 'react';
 export { R as RenderContext } from './render-response.interface-ClWJXKL4.js';

package/dist/{index-CSvZfKpi.d.ts → index-CGfEDKI4.d.ts}

@@ -759,4 +759,4 @@ declare function ErrorPageDevelopment({ error, viewPath, phase, }: ErrorPageDeve
  */
 declare function ErrorPageProduction(): react_jsx_runtime.JSX.Element;
 
-export { type ContextFactory as C, ErrorPageDevelopment as E, RenderModule as R, StreamingErrorHandler as S, TemplateParserService as T, RenderService as a, RenderInterceptor as b, type RenderConfig as c, type SSRMode as d, ErrorPageProduction as e };
+export { type ContextFactory as C, ErrorPageDevelopment as E, type RenderConfig as R, type SSRMode as S, TemplateParserService as T, ErrorPageProduction as a, RenderInterceptor as b, RenderModule as c, RenderService as d, StreamingErrorHandler as e };

package/dist/{index-ZpkYrPcK.d.mts → index-DcpOFSp4.d.mts}

@@ -759,4 +759,4 @@ declare function ErrorPageDevelopment({ error, viewPath, phase, }: ErrorPageDeve
  */
 declare function ErrorPageProduction(): react_jsx_runtime.JSX.Element;
 
-export { type ContextFactory as C, ErrorPageDevelopment as E, RenderModule as R, StreamingErrorHandler as S, TemplateParserService as T, RenderService as a, RenderInterceptor as b, type RenderConfig as c, type SSRMode as d, ErrorPageProduction as e };
+export { type ContextFactory as C, ErrorPageDevelopment as E, type RenderConfig as R, type SSRMode as S, TemplateParserService as T, ErrorPageProduction as a, RenderInterceptor as b, RenderModule as c, RenderService as d, StreamingErrorHandler as e };

package/dist/index.d.mts

@@ -1,7 +1,7 @@
-export { C as ContextFactory, E as ErrorPageDevelopment, e as ErrorPageProduction, c as RenderConfig, b as RenderInterceptor, R as RenderModule, a as RenderService, d as SSRMode, S as StreamingErrorHandler, T as TemplateParserService } from './index-ZpkYrPcK.mjs';
+export { C as ContextFactory, E as ErrorPageDevelopment, a as ErrorPageProduction, R as RenderConfig, b as RenderInterceptor, c as RenderModule, d as RenderService, S as SSRMode, e as StreamingErrorHandler, T as TemplateParserService } from './index-DcpOFSp4.mjs';
 import React, { ComponentType, ReactNode } from 'react';
-import { P as PageProps } from './use-page-context-CVC9DHcL.mjs';
-export { a as PageContextProvider, c as createSSRHooks, i as useCookie, h as useCookies, g as useHeader, f as useHeaders, u as usePageContext, b as useParams, d as useQuery, e as useRequest } from './use-page-context-CVC9DHcL.mjs';
+import { P as PageProps } from './use-page-context-CmxWHIK3.mjs';
+export { a as PageContextProvider, c as createSSRHooks, u as useCookie, b as useCookies, d as useHeader, e as useHeaders, f as usePageContext, g as useParams, h as useQuery, i as useRequest } from './use-page-context-CmxWHIK3.mjs';
 import { R as RenderContext, H as HeadData, a as RenderResponse } from './render-response.interface-ClWJXKL4.mjs';
 import '@nestjs/common';
 import 'http';

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-export { C as ContextFactory, E as ErrorPageDevelopment, e as ErrorPageProduction, c as RenderConfig, b as RenderInterceptor, R as RenderModule, a as RenderService, d as SSRMode, S as StreamingErrorHandler, T as TemplateParserService } from './index-CSvZfKpi.js';
+export { C as ContextFactory, E as ErrorPageDevelopment, a as ErrorPageProduction, R as RenderConfig, b as RenderInterceptor, c as RenderModule, d as RenderService, S as SSRMode, e as StreamingErrorHandler, T as TemplateParserService } from './index-CGfEDKI4.js';
 import React, { ComponentType, ReactNode } from 'react';
-import { P as PageProps } from './use-page-context-DChgHhL9.js';
-export { a as PageContextProvider, c as createSSRHooks, i as useCookie, h as useCookies, g as useHeader, f as useHeaders, u as usePageContext, b as useParams, d as useQuery, e as useRequest } from './use-page-context-DChgHhL9.js';
+import { P as PageProps } from './use-page-context-CUV31oda.js';
+export { a as PageContextProvider, c as createSSRHooks, u as useCookie, b as useCookies, d as useHeader, e as useHeaders, f as usePageContext, g as useParams, h as useQuery, i as useRequest } from './use-page-context-CUV31oda.js';
 import { R as RenderContext, H as HeadData, a as RenderResponse } from './render-response.interface-ClWJXKL4.js';
 import '@nestjs/common';
 import 'http';

package/dist/index.js

@@ -1253,9 +1253,10 @@ exports.RenderInterceptor = class RenderInterceptor {
       if (typeof data === "string") {
         return data;
       }
+      const requestPath = request.path ?? request.url?.split("?")[0] ?? "/";
       const renderContext = {
         url: request.url,
-        path: request.path,
+        path: requestPath,
         query: request.query,
         params: request.params,
         method: request.method

package/dist/index.mjs

@@ -1246,9 +1246,10 @@ var RenderInterceptor = class {
       if (typeof data === "string") {
         return data;
       }
+      const requestPath = request.path ?? request.url?.split("?")[0] ?? "/";
       const renderContext = {
         url: request.url,
-        path: request.path,
+        path: requestPath,
         query: request.query,
         params: request.params,
         method: request.method

package/dist/render/index.d.mts

@@ -1,4 +1,4 @@
-export { E as ErrorPageDevelopment, e as ErrorPageProduction, b as RenderInterceptor, R as RenderModule, a as RenderService, S as StreamingErrorHandler, T as TemplateParserService } from '../index-ZpkYrPcK.mjs';
+export { E as ErrorPageDevelopment, a as ErrorPageProduction, b as RenderInterceptor, c as RenderModule, d as RenderService, e as StreamingErrorHandler, T as TemplateParserService } from '../index-DcpOFSp4.mjs';
 import '@nestjs/common';
 import 'react';
 import '../render-response.interface-ClWJXKL4.mjs';

package/dist/render/index.d.ts

@@ -1,4 +1,4 @@
-export { E as ErrorPageDevelopment, e as ErrorPageProduction, b as RenderInterceptor, R as RenderModule, a as RenderService, S as StreamingErrorHandler, T as TemplateParserService } from '../index-CSvZfKpi.js';
+export { E as ErrorPageDevelopment, a as ErrorPageProduction, b as RenderInterceptor, c as RenderModule, d as RenderService, e as StreamingErrorHandler, T as TemplateParserService } from '../index-CGfEDKI4.js';
 import '@nestjs/common';
 import 'react';
 import '../render-response.interface-ClWJXKL4.js';

package/dist/render/index.js

@@ -1234,9 +1234,10 @@ exports.RenderInterceptor = class RenderInterceptor {
       if (typeof data === "string") {
         return data;
       }
+      const requestPath = request.path ?? request.url?.split("?")[0] ?? "/";
       const renderContext = {
         url: request.url,
-        path: request.path,
+        path: requestPath,
         query: request.query,
         params: request.params,
         method: request.method

package/dist/render/index.mjs

@@ -1228,9 +1228,10 @@ var RenderInterceptor = class {
       if (typeof data === "string") {
         return data;
       }
+      const requestPath = request.path ?? request.url?.split("?")[0] ?? "/";
       const renderContext = {
         url: request.url,
-        path: request.path,
+        path: requestPath,
         query: request.query,
         params: request.params,
         method: request.method

package/dist/templates/entry-client.tsx

@@ -164,9 +164,29 @@ function composeWithLayout(
   return result;
 }
 
-// Build layouts array - use RootLayout if it exists (matching server behavior)
+// Build layouts array from server-provided __LAYOUTS__ data
+// This ensures controller-level layouts (e.g., @Layout(RecipesLayout)) are
+// included during hydration on hard refresh, not just the auto-discovered root layout
+const layoutsData = window.__LAYOUTS__ || [];
 const layouts: Array<{ layout: React.ComponentType<any>; props?: any }> = [];
-if (RootLayout) {
+
+for (const { name: layoutName, props: layoutProps } of layoutsData) {
+  const layoutEntry = componentMap.find(
+    (c) =>
+      c.name === layoutName ||
+      c.normalizedFilename === layoutName ||
+      c.filename === layoutName.toLowerCase(),
+  );
+  if (layoutEntry) {
+    layouts.push({ layout: layoutEntry.component, props: layoutProps || {} });
+  } else if (layoutName === 'RootLayout' && RootLayout) {
+    // Fallback: if the auto-discovered root layout wasn't in componentMap by name
+    layouts.push({ layout: RootLayout, props: layoutProps || {} });
+  }
+}
+
+// Fallback: if no __LAYOUTS__ data, use auto-discovered RootLayout
+if (layouts.length === 0 && RootLayout) {
   layouts.push({ layout: RootLayout, props: {} });
 }
 

package/dist/{use-page-context-DChgHhL9.d.ts → use-page-context-CUV31oda.d.ts}

@@ -279,4 +279,4 @@ declare const useHeader: (name: string) => string | undefined;
 declare const useCookies: () => Record<string, string>;
 declare const useCookie: (name: string) => string | undefined;
 
-export { type PageProps as P, PageContextProvider as a, useParams as b, createSSRHooks as c, useQuery as d, useRequest as e, useHeaders as f, useHeader as g, useCookies as h, useCookie as i, updatePageContext as j, usePageContext as u };
+export { type PageProps as P, PageContextProvider as a, useCookies as b, createSSRHooks as c, useHeader as d, useHeaders as e, usePageContext as f, useParams as g, useQuery as h, useRequest as i, updatePageContext as j, useCookie as u };

package/dist/{use-page-context-CVC9DHcL.d.mts → use-page-context-CmxWHIK3.d.mts}

@@ -279,4 +279,4 @@ declare const useHeader: (name: string) => string | undefined;
 declare const useCookies: () => Record<string, string>;
 declare const useCookie: (name: string) => string | undefined;
 
-export { type PageProps as P, PageContextProvider as a, useParams as b, createSSRHooks as c, useQuery as d, useRequest as e, useHeaders as f, useHeader as g, useCookies as h, useCookie as i, updatePageContext as j, usePageContext as u };
+export { type PageProps as P, PageContextProvider as a, useCookies as b, createSSRHooks as c, useHeader as d, useHeaders as e, usePageContext as f, useParams as g, useQuery as h, useRequest as i, updatePageContext as j, useCookie as u };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nestjs-ssr/react",
-  "version": "0.3.6",
+  "version": "0.3.8",
   "description": "React SSR for NestJS that respects Clean Architecture. Proper DI, SOLID principles, clear separation of concerns.",
   "keywords": [
     "nestjs",
@@ -90,6 +90,10 @@
     "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/*/",
+    "test:e2e:setup": "tsx test/e2e/setup/create-fixtures.ts",
+    "test:e2e:dev": "TEST_MODE=dev playwright test -c test/e2e/playwright.config.ts",
+    "test:e2e:prod": "TEST_MODE=prod playwright test -c test/e2e/playwright.config.ts",
+    "test:e2e:clean": "rm -rf test/e2e/fixtures/*/",
     "size": "size-limit",
     "api:extract": "api-extractor run --local --verbose",
     "api:check": "api-extractor run --verbose",
@@ -109,11 +113,11 @@
     }
   ],
   "peerDependencies": {
+    "@fastify/static": "^8.0.0 || ^7.0.0",
     "@nestjs/common": "^11.0.0",
     "@nestjs/core": "^11.0.0",
     "@nestjs/platform-express": "^11.0.0",
     "@nestjs/platform-fastify": "^11.0.0",
-    "@fastify/static": "^8.0.0 || ^7.0.0",
     "http-proxy-middleware": "^3.0.0 || ^2.0.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
@@ -135,38 +139,38 @@
     }
   },
   "dependencies": {
-    "citty": "^0.1.6",
+    "citty": "^0.2.0",
     "consola": "^3.4.2",
-    "devalue": "^5.6.1",
+    "devalue": "^5.6.2",
     "escape-html": "^1.0.3"
   },
   "devDependencies": {
-    "@microsoft/api-extractor": "^7.55.2",
-    "@nestjs/common": "^11.1.9",
-    "@nestjs/core": "^11.1.9",
-    "@nestjs/platform-express": "^11.1.9",
-    "@nestjs/testing": "^11.1.9",
-    "@playwright/test": "^1.57.0",
+    "@microsoft/api-extractor": "^7.56.3",
+    "@nestjs/common": "^11.1.13",
+    "@nestjs/core": "^11.1.13",
+    "@nestjs/platform-express": "^11.1.13",
+    "@nestjs/testing": "^11.1.13",
+    "@playwright/test": "^1.58.2",
     "@testing-library/jest-dom": "^6.9.1",
-    "@testing-library/react": "^16.3.0",
+    "@testing-library/react": "^16.3.2",
     "@types/escape-html": "^1.0.4",
     "@types/express": "^5.0.6",
-    "@types/node": "^25.0.1",
-    "@types/react": "^19.2.7",
+    "@types/node": "^25.2.2",
+    "@types/react": "^19.2.13",
     "@types/react-dom": "^19.2.3",
     "@types/supertest": "^6.0.3",
-    "@vitejs/plugin-react": "^5.1.2",
-    "@vitest/coverage-v8": "^4.0.15",
-    "@vitest/ui": "^4.0.15",
-    "happy-dom": "^20.0.11",
-    "react": "^19.2.3",
-    "react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.1.3",
+    "@vitest/coverage-v8": "^4.0.18",
+    "@vitest/ui": "^4.0.18",
+    "happy-dom": "^20.5.0",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
     "rxjs": "^7.8.2",
-    "supertest": "^7.1.4",
+    "supertest": "^7.2.2",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
-    "vite": "^7.2.7",
-    "vitest": "^4.0.15"
+    "vite": "^7.3.1",
+    "vitest": "^4.0.18"
   },
   "publishConfig": {
     "access": "public"

package/src/templates/entry-client.tsx

@@ -164,9 +164,29 @@ function composeWithLayout(
   return result;
 }
 
-// Build layouts array - use RootLayout if it exists (matching server behavior)
+// Build layouts array from server-provided __LAYOUTS__ data
+// This ensures controller-level layouts (e.g., @Layout(RecipesLayout)) are
+// included during hydration on hard refresh, not just the auto-discovered root layout
+const layoutsData = window.__LAYOUTS__ || [];
 const layouts: Array<{ layout: React.ComponentType<any>; props?: any }> = [];
-if (RootLayout) {
+
+for (const { name: layoutName, props: layoutProps } of layoutsData) {
+  const layoutEntry = componentMap.find(
+    (c) =>
+      c.name === layoutName ||
+      c.normalizedFilename === layoutName ||
+      c.filename === layoutName.toLowerCase(),
+  );
+  if (layoutEntry) {
+    layouts.push({ layout: layoutEntry.component, props: layoutProps || {} });
+  } else if (layoutName === 'RootLayout' && RootLayout) {
+    // Fallback: if the auto-discovered root layout wasn't in componentMap by name
+    layouts.push({ layout: RootLayout, props: layoutProps || {} });
+  }
+}
+
+// Fallback: if no __LAYOUTS__ data, use auto-discovered RootLayout
+if (layouts.length === 0 && RootLayout) {
   layouts.push({ layout: RootLayout, props: {} });
 }