@nestjs-ssr/react 0.2.6 → 0.3.1

package/dist/client.mjs

@@ -1,10 +1,37 @@
-import React, { createContext, useContext } from 'react';
+import React2, { createContext, useContext, useState, useEffect, useCallback } from 'react';
+import { createRoot } from 'react-dom/client';
 
 var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
-var PageContext = /* @__PURE__ */ createContext(null);
-function PageContextProvider({ context, children }) {
-  return /* @__PURE__ */ React.createElement(PageContext.Provider, {
+var CONTEXT_KEY = /* @__PURE__ */ Symbol.for("nestjs-ssr.PageContext");
+var globalStore = globalThis;
+function getOrCreateContext() {
+  if (!globalStore[CONTEXT_KEY]) {
+    globalStore[CONTEXT_KEY] = /* @__PURE__ */ createContext(null);
+  }
+  return globalStore[CONTEXT_KEY];
+}
+__name(getOrCreateContext, "getOrCreateContext");
+var PageContext = getOrCreateContext();
+var setPageContextState = null;
+function registerPageContextState(setter) {
+  setPageContextState = setter;
+}
+__name(registerPageContextState, "registerPageContextState");
+function updatePageContext(context) {
+  setPageContextState?.(context);
+}
+__name(updatePageContext, "updatePageContext");
+function PageContextProvider({ context: initialContext, children, isSegment = false }) {
+  const [context, setContext] = useState(initialContext);
+  useEffect(() => {
+    if (!isSegment) {
+      registerPageContextState(setContext);
+    }
+  }, [
+    isSegment
+  ]);
+  return /* @__PURE__ */ React2.createElement(PageContext.Provider, {
     value: context
   }, children);
 }
@@ -196,5 +223,309 @@ function createSSRHooks() {
   };
 }
 __name(createSSRHooks, "createSSRHooks");
+var defaultHooks = createSSRHooks();
+var usePageContext = defaultHooks.usePageContext;
+var useParams = defaultHooks.useParams;
+var useQuery = defaultHooks.useQuery;
+var useRequest = defaultHooks.useRequest;
+var useHeaders = defaultHooks.useHeaders;
+var useHeader = defaultHooks.useHeader;
+var useCookies = defaultHooks.useCookies;
+var useCookie = defaultHooks.useCookie;
+var rootRegistry = /* @__PURE__ */ new WeakMap();
+function hydrateSegment(outlet, componentName, props) {
+  const modules = window.__MODULES__;
+  if (!modules) {
+    console.warn("[navigation] Module registry not available for segment hydration. Make sure entry-client.tsx exports window.__MODULES__.");
+    return;
+  }
+  const ViewComponent = resolveComponent(componentName, modules);
+  if (!ViewComponent) {
+    console.warn(`[navigation] Component "${componentName}" not found for hydration. Available components: ` + Object.keys(modules).map((path) => {
+      const c = modules[path].default;
+      return c?.displayName || c?.name || "anonymous";
+    }).join(", "));
+    return;
+  }
+  const context = window.__CONTEXT__ || {};
+  const element = /* @__PURE__ */ React2.createElement(PageContextProvider, {
+    context,
+    isSegment: true
+  }, /* @__PURE__ */ React2.createElement(ViewComponent, props));
+  let wrapper = outlet.querySelector("[data-segment-root]");
+  if (wrapper) {
+    const existingRoot = rootRegistry.get(wrapper);
+    if (existingRoot) {
+      existingRoot.unmount();
+      rootRegistry.delete(wrapper);
+    }
+  }
+  wrapper = document.createElement("div");
+  wrapper.setAttribute("data-segment-root", "true");
+  outlet.innerHTML = "";
+  outlet.appendChild(wrapper);
+  const root = createRoot(wrapper);
+  root.render(element);
+  rootRegistry.set(wrapper, root);
+}
+__name(hydrateSegment, "hydrateSegment");
+function resolveComponent(name, modules) {
+  const componentMap = Object.entries(modules).filter(([path, module]) => {
+    const filename = path.split("/").pop();
+    if (filename === "entry-client.tsx" || filename === "entry-server.tsx") {
+      return false;
+    }
+    return module.default !== void 0;
+  }).map(([path, module]) => {
+    const component = module.default;
+    const componentName = component.displayName || component.name;
+    const filename = path.split("/").pop()?.replace(".tsx", "");
+    const normalizedFilename = filename ? filename.charAt(0).toUpperCase() + filename.slice(1) : void 0;
+    return {
+      component,
+      name: componentName,
+      filename,
+      normalizedFilename
+    };
+  });
+  let match = componentMap.find((c) => c.name === name || c.normalizedFilename === name || c.filename === name.toLowerCase());
+  if (!match && /^default(_\d+)?$/.test(name)) {
+    if (componentMap.length === 1) {
+      match = componentMap[0];
+    } else {
+      const indexMatch = name.match(/^default_(\d+)$/);
+      const index = indexMatch ? parseInt(indexMatch[1], 10) - 1 : 0;
+      const defaultComponents = componentMap.filter((c) => c.name === "default").sort((a, b) => (a.filename || "").localeCompare(b.filename || ""));
+      if (defaultComponents[index]) {
+        match = defaultComponents[index];
+      }
+    }
+  }
+  return match?.component;
+}
+__name(resolveComponent, "resolveComponent");
+
+// src/react/navigation/navigate.ts
+var setNavigationState = null;
+function registerNavigationState(setter) {
+  setNavigationState = setter;
+}
+__name(registerNavigationState, "registerNavigationState");
+async function navigate(url, options = {}) {
+  const { replace = false, scroll = true } = options;
+  setNavigationState?.("loading");
+  const parsedUrl = new URL(url, window.location.origin);
+  const currentContext = window.__CONTEXT__;
+  if (currentContext) {
+    const optimisticContext = {
+      ...currentContext,
+      path: parsedUrl.pathname,
+      url
+    };
+    updatePageContext(optimisticContext);
+  }
+  try {
+    const currentLayouts = getCurrentLayouts();
+    if (currentLayouts.length === 0) {
+      window.location.href = url;
+      return;
+    }
+    const response = await fetchSegment(url, currentLayouts);
+    if (!response.swapTarget) {
+      window.location.href = url;
+      return;
+    }
+    const outlet = await swapContent(response.html, response.swapTarget);
+    if (outlet) {
+      hydrateSegment(outlet, response.componentName, response.props);
+    }
+    if (replace) {
+      history.replaceState({
+        url
+      }, "", url);
+    } else {
+      history.pushState({
+        url
+      }, "", url);
+    }
+    if (response.context) {
+      updatePageContext(response.context);
+      window.__CONTEXT__ = response.context;
+    }
+    if (response.head) {
+      updateHead(response.head);
+    }
+    if (scroll) {
+      window.scrollTo(0, 0);
+    }
+    window.__COMPONENT_NAME__ = response.componentName;
+    window.__INITIAL_STATE__ = response.props;
+  } catch (error) {
+    console.error("Navigation failed:", error);
+    window.location.href = url;
+  } finally {
+    setNavigationState?.("idle");
+  }
+}
+__name(navigate, "navigate");
+function getCurrentLayouts() {
+  return Array.from(document.querySelectorAll("[data-layout]")).map((el) => el.getAttribute("data-layout"));
+}
+__name(getCurrentLayouts, "getCurrentLayouts");
+async function fetchSegment(url, currentLayouts) {
+  const res = await fetch(url, {
+    headers: {
+      "X-Current-Layouts": currentLayouts.join(",")
+    }
+  });
+  if (!res.ok) {
+    throw new Error(`Navigation failed: ${res.status}`);
+  }
+  return res.json();
+}
+__name(fetchSegment, "fetchSegment");
+async function swapContent(html, swapTarget) {
+  const outlet = document.querySelector(`[data-outlet="${swapTarget}"]`);
+  if (!outlet) {
+    window.location.reload();
+    return null;
+  }
+  const swap = /* @__PURE__ */ __name(() => {
+    outlet.innerHTML = html;
+  }, "swap");
+  if ("startViewTransition" in document) {
+    try {
+      await document.startViewTransition(swap).finished;
+    } catch {
+      swap();
+    }
+  } else {
+    swap();
+  }
+  return outlet;
+}
+__name(swapContent, "swapContent");
+function updateHead(head) {
+  if (head.title) {
+    document.title = head.title;
+  }
+  const updateMeta = /* @__PURE__ */ __name((name, content) => {
+    let el = document.querySelector(`meta[name="${name}"]`);
+    if (!el) {
+      el = document.createElement("meta");
+      el.setAttribute("name", name);
+      document.head.appendChild(el);
+    }
+    el.setAttribute("content", content);
+  }, "updateMeta");
+  if (head.description) {
+    updateMeta("description", head.description);
+  }
+  if (head.keywords) {
+    updateMeta("keywords", head.keywords);
+  }
+  const updateOgMeta = /* @__PURE__ */ __name((property, content) => {
+    let el = document.querySelector(`meta[property="${property}"]`);
+    if (!el) {
+      el = document.createElement("meta");
+      el.setAttribute("property", property);
+      document.head.appendChild(el);
+    }
+    el.setAttribute("content", content);
+  }, "updateOgMeta");
+  if (head.ogTitle) {
+    updateOgMeta("og:title", head.ogTitle);
+  }
+  if (head.ogDescription) {
+    updateOgMeta("og:description", head.ogDescription);
+  }
+  if (head.ogImage) {
+    updateOgMeta("og:image", head.ogImage);
+  }
+  if (head.canonical) {
+    let canonical = document.querySelector('link[rel="canonical"]');
+    if (!canonical) {
+      canonical = document.createElement("link");
+      canonical.setAttribute("rel", "canonical");
+      document.head.appendChild(canonical);
+    }
+    canonical.setAttribute("href", head.canonical);
+  }
+}
+__name(updateHead, "updateHead");
+
+// src/react/navigation/navigation-context.tsx
+var NavigationContext = /* @__PURE__ */ createContext(null);
+function NavigationProvider({ children }) {
+  const [state, setState] = useState("idle");
+  useEffect(() => {
+    registerNavigationState(setState);
+  }, []);
+  return /* @__PURE__ */ React2.createElement(NavigationContext.Provider, {
+    value: {
+      state
+    }
+  }, children);
+}
+__name(NavigationProvider, "NavigationProvider");
+function useNavigationContext() {
+  const context = useContext(NavigationContext);
+  if (!context) {
+    return {
+      state: "idle"
+    };
+  }
+  return context;
+}
+__name(useNavigationContext, "useNavigationContext");
+function Link({ href, replace = false, scroll = true, children, onClick, ...props }) {
+  const handleClick = /* @__PURE__ */ __name((e) => {
+    if (e.metaKey || e.ctrlKey || e.shiftKey || e.altKey || e.button !== 0 || props.target === "_blank" || !isSameOrigin(href)) {
+      onClick?.(e);
+      return;
+    }
+    e.preventDefault();
+    onClick?.(e);
+    navigate(href, {
+      replace,
+      scroll
+    });
+  }, "handleClick");
+  return /* @__PURE__ */ React2.createElement("a", {
+    href,
+    onClick: handleClick,
+    ...props
+  }, children);
+}
+__name(Link, "Link");
+function isSameOrigin(url) {
+  try {
+    const parsed = new URL(url, window.location.origin);
+    return parsed.origin === window.location.origin;
+  } catch {
+    return true;
+  }
+}
+__name(isSameOrigin, "isSameOrigin");
+function useNavigation() {
+  const { state } = useNavigationContext();
+  return {
+    state,
+    navigate
+  };
+}
+__name(useNavigation, "useNavigation");
+function useNavigationState() {
+  return useNavigationContext().state;
+}
+__name(useNavigationState, "useNavigationState");
+function useNavigate() {
+  return useCallback(navigate, []);
+}
+__name(useNavigate, "useNavigate");
+function useIsNavigating() {
+  return useNavigationContext().state === "loading";
+}
+__name(useIsNavigating, "useIsNavigating");
 
-export { PageContextProvider, createSSRHooks };
+export { Link, NavigationProvider, PageContextProvider, createSSRHooks, navigate, updatePageContext, useCookie, useCookies, useHeader, useHeaders, useIsNavigating, useNavigate, useNavigation, useNavigationState, usePageContext, useParams, useQuery, useRequest };

package/dist/{index-BMdluY1g.d.mts → index-BzOLOiIZ.d.ts}

@@ -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.mjs';
+import { H as HeadData, R as RenderContext } from './render-response.interface-CxbuKGnV.js';
 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>;
 }