@nestjs-ssr/react 0.2.6 → 0.3.0

package/dist/{index-rl0S5kqW.d.ts → index-DdE--mA2.d.mts}

@@ -1,6 +1,6 @@
 import { DynamicModule, NestInterceptor, ExecutionContext, CallHandler } from '@nestjs/common';
 import { ComponentType } from 'react';
-import { H as HeadData } from './render-response.interface-Dc-Kwb09.js';
+import { H as HeadData, R as RenderContext } from './render-response.interface-CxbuKGnV.mjs';
 import { ViteDevServer } from 'vite';
 import { Response } from 'express';
 import { Reflector } from '@nestjs/core';
@@ -20,23 +20,14 @@ interface ErrorPageDevelopmentProps$1 {
     phase: 'shell' | 'streaming';
 }
 /**
- * Vite development mode configuration
- */
-type ViteMode = 'proxy' | 'embedded';
-/**
- * Vite configuration options
+ * Vite configuration options for development
+ *
+ * In development, NestJS proxies requests to an external Vite dev server
+ * which provides HMR (Hot Module Replacement) for React components.
  */
 interface ViteConfig {
     /**
-     * Vite mode for development
-     * - 'embedded': Vite runs inside NestJS (no HMR, simplest setup) - DEFAULT
-     * - 'proxy': External Vite server with HMR support (requires running `vite` separately)
-     *
-     * @default 'embedded'
-     */
-    mode?: ViteMode;
-    /**
-     * Port where external Vite dev server is running (proxy mode only)
+     * Port where Vite dev server is running
      *
      * @default 5173
      */
@@ -48,8 +39,18 @@ interface ViteConfig {
 interface RenderConfig {
     /**
      * SSR rendering mode
-     * - 'string': Traditional renderToString (simple, proven, easier debugging)
-     * - 'stream': Modern renderToPipeableStream (better performance, progressive rendering)
+     * - 'string': Traditional renderToString - atomic responses, proper HTTP status codes (default)
+     * - 'stream': Modern renderToPipeableStream - better TTFB, Suspense support (advanced)
+     *
+     * String mode is recommended for most applications because:
+     * - Atomic responses: either complete HTML or error page, never partial
+     * - Proper HTTP status codes: 200 for success, 500 for errors
+     * - Simpler error handling and debugging
+     *
+     * Use stream mode only when you need:
+     * - Better Time to First Byte (TTFB) for performance-critical pages
+     * - Progressive rendering with Suspense boundaries
+     * - And you understand the trade-offs (errors after shell may result in HTTP 200 with partial content)
      *
      * @default 'string'
      */
@@ -64,20 +65,17 @@ interface RenderConfig {
     /**
      * Vite configuration for development
      *
+     * In development, run Vite separately (`pnpm dev:vite`) and NestJS will
+     * proxy requests to it. This enables HMR for React components.
+     *
      * @example
      * ```typescript
-     * // Zero config - embedded mode by default (simplest)
-     * @Module({
-     *   imports: [RenderModule],
-     * })
+     * // Default port 5173
+     * RenderModule.forRoot()
      *
-     * // Proxy mode - external Vite with HMR
-     * @Module({
-     *   imports: [
-     *     RenderModule.forRoot({
-     *       vite: { mode: 'proxy', port: 5173 }
-     *     })
-     *   ],
+     * // Custom Vite port
+     * RenderModule.forRoot({
+     *   vite: { port: 3001 }
      * })
      * ```
      */
@@ -191,6 +189,25 @@ interface TemplateParts {
     htmlEnd: string;
 }
 
+/**
+ * Response format for segment rendering (client-side navigation).
+ * Returned when a GET request includes the X-Current-Layouts header.
+ */
+interface SegmentResponse {
+    /** The rendered HTML for the segment (content below swapTarget layout) */
+    html: string;
+    /** Head metadata to update (title, description, etc.) */
+    head?: HeadData;
+    /** Component props for hydration */
+    props: any;
+    /** Which outlet to swap (the deepest common layout). Null if no common ancestor. */
+    swapTarget: string | null;
+    /** Component name for resolving in module registry during hydration */
+    componentName: string;
+    /** Page context for updating hooks (path, params, query, etc.) */
+    context?: RenderContext;
+}
+
 declare class RenderModule {
     /**
      * Configure the render module
@@ -200,17 +217,17 @@ declare class RenderModule {
      *
      * @example
      * ```ts
-     * // Zero config - uses defaults
+     * // Zero config - uses string mode (default, recommended)
      * RenderModule.forRoot()
      *
-     * // Enable streaming SSR
-     * RenderModule.forRoot({ mode: 'stream' })
-     *
-     * // Enable HMR with proxy mode
+     * // Custom Vite port
      * RenderModule.forRoot({
-     *   vite: { mode: 'proxy', port: 5173 }
+     *   vite: { port: 3001 }
      * })
      *
+     * // Enable streaming SSR (advanced - see mode docs for trade-offs)
+     * RenderModule.forRoot({ mode: 'stream' })
+     *
      * // Custom error pages
      * RenderModule.forRoot({
      *   errorPageDevelopment: DevErrorPage,
@@ -327,6 +344,47 @@ declare class TemplateParserService {
     private buildTag;
 }
 
+interface ViteManifest$1 {
+    [key: string]: {
+        file: string;
+        src?: string;
+        isEntry?: boolean;
+        imports?: string[];
+        css?: string[];
+    };
+}
+interface StringRenderContext {
+    template: string;
+    vite: ViteDevServer | null;
+    manifest: ViteManifest$1 | null;
+    serverManifest: ViteManifest$1 | null;
+    entryServerPath: string;
+    isDevelopment: boolean;
+}
+/**
+ * String-based SSR renderer using React's renderToString
+ *
+ * This is the default renderer that provides:
+ * - Atomic responses (complete HTML or error page)
+ * - Proper HTTP status codes
+ * - Simple error handling
+ * - Easy debugging
+ */
+declare class StringRenderer {
+    private readonly templateParser;
+    private readonly logger;
+    constructor(templateParser: TemplateParserService);
+    /**
+     * Render a React component to a complete HTML string
+     */
+    render(viewComponent: any, data: any, context: StringRenderContext, head?: HeadData): Promise<string>;
+    /**
+     * Render a segment for client-side navigation.
+     * Returns just the HTML and metadata without the full page template.
+     */
+    renderSegment(viewComponent: any, data: any, context: StringRenderContext, swapTarget: string, head?: HeadData): Promise<SegmentResponse>;
+}
+
 /**
  * Error handling strategies for streaming SSR
  *
@@ -358,11 +416,86 @@ declare class StreamingErrorHandler {
      * Render production error page using React component
      */
     private renderProductionErrorPage;
+    /**
+     * Render inline error overlay for when headers are already sent
+     * This gets injected into the stream to show a visible error UI
+     */
+    private renderInlineErrorOverlay;
 }
 
-declare class RenderService {
+interface ViteManifest {
+    [key: string]: {
+        file: string;
+        src?: string;
+        isEntry?: boolean;
+        imports?: string[];
+        css?: string[];
+    };
+}
+interface StreamRenderContext {
+    template: string;
+    vite: ViteDevServer | null;
+    manifest: ViteManifest | null;
+    serverManifest: ViteManifest | null;
+    entryServerPath: string;
+    isDevelopment: boolean;
+}
+/**
+ * Streaming SSR renderer using React's renderToPipeableStream
+ *
+ * This renderer provides:
+ * - Better TTFB (Time to First Byte)
+ * - Progressive rendering with Suspense support
+ * - Lower memory usage for large pages
+ *
+ * Trade-offs:
+ * - More complex error handling (shell vs streaming errors)
+ * - Errors after shell may result in partial responses with HTTP 200
+ * - Requires careful Suspense boundary design
+ *
+ * Use this mode when:
+ * - Performance is critical
+ * - You're using Suspense for data fetching
+ * - You understand the error handling implications
+ */
+declare class StreamRenderer {
     private readonly templateParser;
     private readonly streamingErrorHandler;
+    private readonly logger;
+    constructor(templateParser: TemplateParserService, streamingErrorHandler: StreamingErrorHandler);
+    /**
+     * Render a React component using streaming SSR
+     *
+     * @param viewComponent - The React component to render
+     * @param data - Data to pass to the component
+     * @param res - Express response object (required for streaming)
+     * @param context - Render context with Vite and manifest info
+     * @param head - Head data for SEO tags
+     */
+    render(viewComponent: any, data: any, res: Response, context: StreamRenderContext, head?: HeadData): Promise<void>;
+}
+
+/**
+ * Main render service that orchestrates SSR rendering
+ *
+ * This service:
+ * - Loads and manages HTML templates
+ * - Handles Vite manifest loading for production
+ * - Discovers root layouts
+ * - Delegates rendering to StringRenderer (default) or StreamRenderer
+ *
+ * String mode is the default because it provides:
+ * - Atomic responses (complete HTML or error page)
+ * - Proper HTTP status codes always
+ * - Simpler error handling and debugging
+ *
+ * Stream mode is available for advanced use cases requiring:
+ * - Better TTFB (Time to First Byte)
+ * - Progressive rendering with Suspense
+ */
+declare class RenderService {
+    private readonly stringRenderer;
+    private readonly streamRenderer;
     private readonly defaultHead?;
     private readonly logger;
     private vite;
@@ -374,7 +507,14 @@ declare class RenderService {
     private readonly entryServerPath;
     private rootLayout;
     private rootLayoutChecked;
-    constructor(templateParser: TemplateParserService, streamingErrorHandler: StreamingErrorHandler, ssrMode?: SSRMode, defaultHead?: HeadData | undefined, customTemplate?: string);
+    constructor(stringRenderer: StringRenderer, streamRenderer: StreamRenderer, ssrMode?: SSRMode, defaultHead?: HeadData | undefined, customTemplate?: string);
+    /**
+     * Load HTML template from custom path, package, or local location
+     */
+    private loadTemplate;
+    private loadCustomTemplate;
+    private loadDefaultTemplate;
+    private loadManifests;
     setViteServer(vite: ViteDevServer): void;
     /**
      * Get the root layout component if it exists
@@ -386,21 +526,28 @@ declare class RenderService {
     getRootLayout(): Promise<any | null>;
     /**
      * Main render method that routes to string or stream mode
+     *
+     * String mode (default):
+     * - Returns complete HTML string
+     * - Atomic responses - works completely or fails completely
+     * - Proper HTTP status codes always
+     *
+     * Stream mode:
+     * - Writes directly to response
+     * - Better TTFB, progressive rendering
+     * - Requires response object
      */
     render(viewComponent: any, data?: any, res?: Response, head?: HeadData): Promise<string | void>;
+    /**
+     * Render a segment for client-side navigation.
+     * Always uses string mode (streaming not supported for segments).
+     */
+    renderSegment(viewComponent: any, data: any, swapTarget: string, head?: HeadData): Promise<SegmentResponse>;
     /**
      * Merge default head with page-specific head
      * Page-specific head values override defaults
      */
     private mergeHead;
-    /**
-     * Traditional string-based SSR using renderToString
-     */
-    private renderToString;
-    /**
-     * Modern streaming SSR using renderToPipeableStream
-     */
-    private renderToStream;
 }
 
 declare class RenderInterceptor implements NestInterceptor {
@@ -419,6 +566,22 @@ declare class RenderInterceptor implements NestInterceptor {
      * 3. Dynamic props from controller return (final override)
      */
     private resolveLayoutChain;
+    /**
+     * Detect request type based on headers.
+     * - If X-Current-Layouts header is present, this is a segment request
+     * - Only GET requests can be segments
+     */
+    private detectRequestType;
+    /**
+     * Determine swap target by finding deepest common layout.
+     * Returns null if no common ancestor (client should do full navigation).
+     */
+    private determineSwapTarget;
+    /**
+     * Filter layouts to only include those below the swap target.
+     * The swap target's outlet will contain the filtered layouts.
+     */
+    private filterLayoutsFromSwapTarget;
     intercept(context: ExecutionContext, next: CallHandler): Observable<any>;
 }
 

package/dist/index.d.mts

@@ -1,8 +1,8 @@
-export { 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-BMdluY1g.mjs';
+export { 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-DdE--mA2.mjs';
 import React, { ComponentType, ReactNode } from 'react';
-import { RenderContext, PageProps } from './client.mjs';
-export { PageContextProvider, createSSRHooks } from './client.mjs';
-import { H as HeadData, R as RenderResponse } from './render-response.interface-Dc-Kwb09.mjs';
+import { P as PageProps } from './use-page-context-CGT9woWe.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-CGT9woWe.mjs';
+import { R as RenderContext, H as HeadData, a as RenderResponse } from './render-response.interface-CxbuKGnV.mjs';
 import '@nestjs/common';
 import 'vite';
 import 'express';

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-export { 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-rl0S5kqW.js';
+export { 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-BzOLOiIZ.js';
 import React, { ComponentType, ReactNode } from 'react';
-import { RenderContext, PageProps } from './client.js';
-export { PageContextProvider, createSSRHooks } from './client.js';
-import { H as HeadData, R as RenderResponse } from './render-response.interface-Dc-Kwb09.js';
+import { P as PageProps } from './use-page-context-05ODF4zW.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-05ODF4zW.js';
+import { R as RenderContext, H as HeadData, a as RenderResponse } from './render-response.interface-CxbuKGnV.js';
 import '@nestjs/common';
 import 'vite';
 import 'express';