@nestjs-ssr/react 0.1.12 → 0.2.0

package/README.md

@@ -1,122 +1,90 @@
-# @nestjs-ssr/react
+# NestJS SSR
+
+[![npm version](https://badge.fury.io/js/%40nestjs-ssr%2Freact.svg)](https://www.npmjs.com/package/@nestjs-ssr/react)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 > **⚠️ Preview Release**
 > This package is currently in active development. The API may change between minor versions. Production use is not recommended yet.
 
-Server-side rendering for React in NestJS with full TypeScript support and type-safe props.
-
-## Features
+Server-rendered React for NestJS. Controllers return data, components render it.
 
-- **Type-Safe Props** - TypeScript validates controller returns match component props
-- **Zero Config** - Works out of the box with sensible defaults
-- **Streaming SSR** - Modern renderToPipeableStream support
-- **HMR in Development** - Powered by Vite for instant feedback
-- **Production Ready** - Code splitting, caching, and optimizations built-in
+Clean Architecture: layers separated, dependencies inward, business logic framework-agnostic.
 
-## Installation
+## When To Use
 
-```bash
-npm install @nestjs-ssr/react
-npx nestjs-ssr  # Set up your project automatically
-```
+**Use this when:**
 
-The CLI installs dependencies, creates entry files, and configures TypeScript/Vite for you.
+- You have NestJS and want React instead of Handlebars/EJS
+- Testable layers matter more than file-based routing
+- You want feature modules (controller + service + view together)
 
-## Usage
+**Use Next.js when:**
 
-**1. Register the module**
+- You're starting fresh without NestJS
+- You want the React ecosystem's defaults
+- File-based routing fits your mental model
 
-```typescript
-// app.module.ts
-import { RenderModule } from '@nestjs-ssr/react';
+## Quick Start
 
-@Module({
-  imports: [RenderModule],
-})
-export class AppModule {}
+```bash
+npx nestjs-ssr init
 ```
 
-**2. Create a view component**
-
 ```typescript
-// src/views/home.tsx
-import type { PageProps } from '@nestjs-ssr/react';
-
-export interface HomeProps {
-  message: string;
+@Get(':id')
+@Render(ProductDetail)
+async getProduct(@Param('id') id: string) {
+  return { product: await this.productService.findById(id) };
 }
+```
 
-export default function Home(props: PageProps<HomeProps>) {
-  return <h1>{props.message}</h1>;
+```tsx
+export default function ProductDetail({
+  data,
+}: PageProps<{ product: Product }>) {
+  return <h1>{data.product.name}</h1>;
 }
 ```
 
-**3. Use in a controller**
+Type mismatch = build fails.
+
+## Test in Isolation
 
 ```typescript
-// app.controller.ts
-import { Controller, Get } from '@nestjs/common';
-import { Render } from '@nestjs-ssr/react';
-import Home from './views/home';
-
-@Controller()
-export class AppController {
-  @Get()
-  @Render(Home)
-  getHome() {
-    return { message: 'Hello World' };  // TypeScript validates this!
-  }
-}
+// Controller: no React
+expect(await controller.getProduct('123')).toEqual({ product: { id: '123' } });
+
+// Component: no NestJS
+render(<ProductDetail data={{ product: mockProduct }} />);
 ```
 
-That's it! Run `npm run dev` and visit http://localhost:3000
+## Features
 
-## API
+**Rendering:**
 
-### React Hooks
+- Type-safe data flow from controller to component
+- Hierarchical layouts (module → controller → method)
+- Head tags via decorators (title, meta, OG, JSON-LD)
 
-```typescript
-import { usePageContext, useParams, useQuery } from '@nestjs-ssr/react';
+**Request Context:**
 
-function MyComponent() {
-  const context = usePageContext();  // { url, path, query, params, ... }
-  const params = useParams();        // Route params
-  const query = useQuery();          // Query string
-  return <div>User ID: {params.id}</div>;
-}
-```
+- Hooks: params, query, headers, session, user agent
+- Whitelist what reaches the client
 
-### Head Tags & SEO
+**Development:**
 
-```typescript
-import { Head } from '@nestjs-ssr/react';
-
-export default function MyPage(props: PageProps<MyProps>) {
-  return (
-    <>
-      <Head>
-        <title>My Page</title>
-        <meta name="description" content="Page description" />
-      </Head>
-      <div>{props.content}</div>
-    </>
-  );
-}
-```
+- Integrated mode: one process, full refresh
+- Proxy mode: separate Vite, true HMR
 
-## Documentation
+## Docs
 
-- [Full Documentation](https://georgialexandrov.github.io/nestjs-ssr/)
-- [Examples](https://github.com/georgialexandrov/nestjs-ssr/tree/main/examples)
-- [GitHub](https://github.com/georgialexandrov/nestjs-ssr)
+[Full documentation →](https://georgialexandrov.github.io/nest-ssr/)
 
-## Requirements
+## Examples
 
-- Node.js 20+
-- NestJS 11+
-- React 19+
-- TypeScript 5+
+**[Minimal](./examples/minimal/)** - Simplest setup with integrated Vite mode
+**[Minimal HMR](./examples/minimal-hmr/)** - Dual-server architecture for full HMR
 
 ## License
 
-MIT © [Georgi Alexandrov](https://github.com/georgialexandrov)
+MIT

package/dist/cli/init.js

@@ -269,9 +269,9 @@ export default defineConfig({
         if (!args["skip-install"]) {
           consola.consola.start("Checking dependencies...");
           const requiredDeps = {
-            "react": "^19.0.0",
+            react: "^19.0.0",
             "react-dom": "^19.0.0",
-            "vite": "^7.0.0",
+            vite: "^7.0.0",
             "@vitejs/plugin-react": "^4.0.0"
           };
           const missingDeps = [];

package/dist/cli/init.mjs

@@ -266,9 +266,9 @@ export default defineConfig({
         if (!args["skip-install"]) {
           consola.start("Checking dependencies...");
           const requiredDeps = {
-            "react": "^19.0.0",
+            react: "^19.0.0",
             "react-dom": "^19.0.0",
-            "vite": "^7.0.0",
+            vite: "^7.0.0",
             "@vitejs/plugin-react": "^4.0.0"
           };
           const missingDeps = [];

package/dist/{index-BiaVDe9J.d.mts → index-C5Knql-9.d.mts}

@@ -40,6 +40,21 @@ interface HeadData {
         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
@@ -57,12 +72,16 @@ interface HeadData {
  *   // Treated as: { props: { message: 'Hello' } }
  * }
  *
- * // Advanced case - with head data
+ * // 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,
@@ -77,6 +96,17 @@ interface RenderResponse<T = any> {
     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>;
 }
 
 /**
@@ -154,6 +184,32 @@ interface RenderConfig {
      * ```
      */
     vite?: ViteConfig;
+    /**
+     * Custom HTML template for SSR
+     * Provide either a file path or template string
+     *
+     * @example
+     * ```typescript
+     * // File path (absolute or relative to cwd)
+     * RenderModule.register({
+     *   template: './src/views/custom-template.html'
+     * })
+     *
+     * // Template string
+     * RenderModule.register({
+     *   template: `<!DOCTYPE html>
+     *     <html>
+     *       <head><!--styles--></head>
+     *       <body>
+     *         <div id="root"><!--app-html--></div>
+     *         <!--initial-state-->
+     *         <!--client-scripts-->
+     *       </body>
+     *     </html>`
+     * })
+     * ```
+     */
+    template?: string;
     /**
      * Custom error page component for development environment
      * Receives error details and renders custom error UI
@@ -186,6 +242,41 @@ interface RenderConfig {
      * ```
      */
     defaultHead?: HeadData;
+    /**
+     * HTTP headers to pass to client
+     * By default, no headers are passed for security
+     * Use this to opt-in to specific headers that are safe to expose
+     *
+     * Common safe headers: user-agent, accept-language, referer
+     * Security warning: Never include sensitive headers like authorization, cookie, etc.
+     *
+     * @default []
+     *
+     * @example
+     * ```typescript
+     * RenderModule.register({
+     *   allowedHeaders: ['user-agent', 'accept-language', 'x-tenant-id', 'x-api-version']
+     * })
+     * ```
+     */
+    allowedHeaders?: string[];
+    /**
+     * Cookie names to pass to client
+     * By default, no cookies are passed to client for security
+     * Use this to opt-in to specific cookies that are safe to expose
+     *
+     * Security warning: Never include sensitive cookies like session tokens, auth cookies, etc.
+     *
+     * @default []
+     *
+     * @example
+     * ```typescript
+     * RenderModule.register({
+     *   allowedCookies: ['theme', 'locale', 'consent']
+     * })
+     * ```
+     */
+    allowedCookies?: string[];
 }
 /**
  * Template parts for streaming SSR
@@ -291,11 +382,14 @@ declare class TemplateParserService {
     /**
      * Build inline script that provides initial state to the client
      *
-     * Safely serializes data using serialize-javascript to avoid XSS vulnerabilities.
-     * This library handles all edge cases including escaping dangerous characters,
-     * functions, dates, regexes, and prevents prototype pollution.
+     * Safely serializes data using devalue to avoid XSS vulnerabilities.
+     * Devalue is designed specifically for SSR, handling complex types safely
+     * while being faster and more secure than alternatives.
      */
-    buildInlineScripts(data: any, context: any, componentName: string): string;
+    buildInlineScripts(data: any, context: any, componentName: string, layouts?: Array<{
+        layout: any;
+        props?: any;
+    }>): string;
     /**
      * Get client script tag for hydration
      *
@@ -368,8 +462,18 @@ declare class RenderService {
     private isDevelopment;
     private ssrMode;
     private readonly entryServerPath;
-    constructor(templateParser: TemplateParserService, streamingErrorHandler: StreamingErrorHandler, ssrMode?: SSRMode, defaultHead?: HeadData | undefined);
+    private rootLayout;
+    private rootLayoutChecked;
+    constructor(templateParser: TemplateParserService, streamingErrorHandler: StreamingErrorHandler, ssrMode?: SSRMode, defaultHead?: HeadData | undefined, customTemplate?: string);
     setViteServer(vite: ViteDevServer): void;
+    /**
+     * Get the root layout component if it exists
+     * Auto-discovers layout files at conventional paths:
+     * - src/views/layout.tsx
+     * - src/views/layout/index.tsx
+     * - src/views/_layout.tsx
+     */
+    getRootLayout(): Promise<any | null>;
     /**
      * Main render method that routes to string or stream mode
      */
@@ -392,7 +496,19 @@ declare class RenderService {
 declare class RenderInterceptor implements NestInterceptor {
     private reflector;
     private renderService;
-    constructor(reflector: Reflector, renderService: RenderService);
+    private allowedHeaders?;
+    private allowedCookies?;
+    constructor(reflector: Reflector, renderService: RenderService, allowedHeaders?: string[] | undefined, allowedCookies?: string[] | undefined);
+    /**
+     * Resolve the layout hierarchy for a given route
+     * Hierarchy: Root Layout → Controller Layout → Method Layout → Page
+     *
+     * Props are merged in priority order:
+     * 1. Static props from @Layout decorator (base)
+     * 2. Static props from @Render decorator (override)
+     * 3. Dynamic props from controller return (final override)
+     */
+    private resolveLayoutChain;
     intercept(context: ExecutionContext, next: CallHandler): Observable<any>;
 }
 
@@ -417,4 +533,4 @@ declare function ErrorPageDevelopment({ error, viewPath, phase, }: ErrorPageDeve
  */
 declare function ErrorPageProduction(): react_jsx_runtime.JSX.Element;
 
-export { ErrorPageDevelopment as E, type HeadData as H, RenderModule as R, StreamingErrorHandler as S, TemplateParserService as T, RenderService as a, RenderInterceptor as b, type RenderConfig as c, type SSRMode as d, type RenderResponse as e, ErrorPageProduction as f };
+export { ErrorPageDevelopment as E, type HeadData as H, type RenderResponse as R, StreamingErrorHandler as S, TemplateParserService as T, RenderModule as a, RenderService as b, RenderInterceptor as c, type RenderConfig as d, type SSRMode as e, ErrorPageProduction as f };

package/dist/{index-BiaVDe9J.d.ts → index-C5Knql-9.d.ts}

@@ -40,6 +40,21 @@ interface HeadData {
         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
@@ -57,12 +72,16 @@ interface HeadData {
  *   // Treated as: { props: { message: 'Hello' } }
  * }
  *
- * // Advanced case - with head data
+ * // 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,
@@ -77,6 +96,17 @@ interface RenderResponse<T = any> {
     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>;
 }
 
 /**
@@ -154,6 +184,32 @@ interface RenderConfig {
      * ```
      */
     vite?: ViteConfig;
+    /**
+     * Custom HTML template for SSR
+     * Provide either a file path or template string
+     *
+     * @example
+     * ```typescript
+     * // File path (absolute or relative to cwd)
+     * RenderModule.register({
+     *   template: './src/views/custom-template.html'
+     * })
+     *
+     * // Template string
+     * RenderModule.register({
+     *   template: `<!DOCTYPE html>
+     *     <html>
+     *       <head><!--styles--></head>
+     *       <body>
+     *         <div id="root"><!--app-html--></div>
+     *         <!--initial-state-->
+     *         <!--client-scripts-->
+     *       </body>
+     *     </html>`
+     * })
+     * ```
+     */
+    template?: string;
     /**
      * Custom error page component for development environment
      * Receives error details and renders custom error UI
@@ -186,6 +242,41 @@ interface RenderConfig {
      * ```
      */
     defaultHead?: HeadData;
+    /**
+     * HTTP headers to pass to client
+     * By default, no headers are passed for security
+     * Use this to opt-in to specific headers that are safe to expose
+     *
+     * Common safe headers: user-agent, accept-language, referer
+     * Security warning: Never include sensitive headers like authorization, cookie, etc.
+     *
+     * @default []
+     *
+     * @example
+     * ```typescript
+     * RenderModule.register({
+     *   allowedHeaders: ['user-agent', 'accept-language', 'x-tenant-id', 'x-api-version']
+     * })
+     * ```
+     */
+    allowedHeaders?: string[];
+    /**
+     * Cookie names to pass to client
+     * By default, no cookies are passed to client for security
+     * Use this to opt-in to specific cookies that are safe to expose
+     *
+     * Security warning: Never include sensitive cookies like session tokens, auth cookies, etc.
+     *
+     * @default []
+     *
+     * @example
+     * ```typescript
+     * RenderModule.register({
+     *   allowedCookies: ['theme', 'locale', 'consent']
+     * })
+     * ```
+     */
+    allowedCookies?: string[];
 }
 /**
  * Template parts for streaming SSR
@@ -291,11 +382,14 @@ declare class TemplateParserService {
     /**
      * Build inline script that provides initial state to the client
      *
-     * Safely serializes data using serialize-javascript to avoid XSS vulnerabilities.
-     * This library handles all edge cases including escaping dangerous characters,
-     * functions, dates, regexes, and prevents prototype pollution.
+     * Safely serializes data using devalue to avoid XSS vulnerabilities.
+     * Devalue is designed specifically for SSR, handling complex types safely
+     * while being faster and more secure than alternatives.
      */
-    buildInlineScripts(data: any, context: any, componentName: string): string;
+    buildInlineScripts(data: any, context: any, componentName: string, layouts?: Array<{
+        layout: any;
+        props?: any;
+    }>): string;
     /**
      * Get client script tag for hydration
      *
@@ -368,8 +462,18 @@ declare class RenderService {
     private isDevelopment;
     private ssrMode;
     private readonly entryServerPath;
-    constructor(templateParser: TemplateParserService, streamingErrorHandler: StreamingErrorHandler, ssrMode?: SSRMode, defaultHead?: HeadData | undefined);
+    private rootLayout;
+    private rootLayoutChecked;
+    constructor(templateParser: TemplateParserService, streamingErrorHandler: StreamingErrorHandler, ssrMode?: SSRMode, defaultHead?: HeadData | undefined, customTemplate?: string);
     setViteServer(vite: ViteDevServer): void;
+    /**
+     * Get the root layout component if it exists
+     * Auto-discovers layout files at conventional paths:
+     * - src/views/layout.tsx
+     * - src/views/layout/index.tsx
+     * - src/views/_layout.tsx
+     */
+    getRootLayout(): Promise<any | null>;
     /**
      * Main render method that routes to string or stream mode
      */
@@ -392,7 +496,19 @@ declare class RenderService {
 declare class RenderInterceptor implements NestInterceptor {
     private reflector;
     private renderService;
-    constructor(reflector: Reflector, renderService: RenderService);
+    private allowedHeaders?;
+    private allowedCookies?;
+    constructor(reflector: Reflector, renderService: RenderService, allowedHeaders?: string[] | undefined, allowedCookies?: string[] | undefined);
+    /**
+     * Resolve the layout hierarchy for a given route
+     * Hierarchy: Root Layout → Controller Layout → Method Layout → Page
+     *
+     * Props are merged in priority order:
+     * 1. Static props from @Layout decorator (base)
+     * 2. Static props from @Render decorator (override)
+     * 3. Dynamic props from controller return (final override)
+     */
+    private resolveLayoutChain;
     intercept(context: ExecutionContext, next: CallHandler): Observable<any>;
 }
 
@@ -417,4 +533,4 @@ declare function ErrorPageDevelopment({ error, viewPath, phase, }: ErrorPageDeve
  */
 declare function ErrorPageProduction(): react_jsx_runtime.JSX.Element;
 
-export { ErrorPageDevelopment as E, type HeadData as H, RenderModule as R, StreamingErrorHandler as S, TemplateParserService as T, RenderService as a, RenderInterceptor as b, type RenderConfig as c, type SSRMode as d, type RenderResponse as e, ErrorPageProduction as f };
+export { ErrorPageDevelopment as E, type HeadData as H, type RenderResponse as R, StreamingErrorHandler as S, TemplateParserService as T, RenderModule as a, RenderService as b, RenderInterceptor as c, type RenderConfig as d, type SSRMode as e, ErrorPageProduction as f };