@nestjs-ssr/react 0.3.7 → 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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nestjs-ssr/react",
-  "version": "0.3.7",
+  "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",
@@ -141,17 +145,17 @@
     "escape-html": "^1.0.3"
   },
   "devDependencies": {
-    "@microsoft/api-extractor": "^7.56.2",
+    "@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.1",
+    "@playwright/test": "^1.58.2",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.2",
     "@types/escape-html": "^1.0.4",
     "@types/express": "^5.0.6",
-    "@types/node": "^25.2.1",
+    "@types/node": "^25.2.2",
     "@types/react": "^19.2.13",
     "@types/react-dom": "^19.2.3",
     "@types/supertest": "^6.0.3",

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: {} });
 }