@nestjs-ssr/react 0.1.1

package/dist/index-Bptct1Q3.d.mts

@@ -0,0 +1,419 @@
+import { DynamicModule, NestInterceptor, ExecutionContext, CallHandler } from '@nestjs/common';
+import { ComponentType } from 'react';
+import { ViteDevServer } from 'vite';
+import { Response } from 'express';
+import { Reflector } from '@nestjs/core';
+import { Observable } from 'rxjs';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/**
+ * HTML head data for SEO and page metadata
+ */
+interface HeadData {
+    /** Page title (appears in browser tab and search results) */
+    title?: string;
+    /** Page description for search engines */
+    description?: string;
+    /** Page keywords (legacy, less important for modern SEO) */
+    keywords?: string;
+    /** Canonical URL for duplicate content */
+    canonical?: string;
+    /** Open Graph title for social media sharing */
+    ogTitle?: string;
+    /** Open Graph description for social media sharing */
+    ogDescription?: string;
+    /** Open Graph image URL for social media previews */
+    ogImage?: string;
+    /** Additional link tags (fonts, icons, preloads, etc.) */
+    links?: Array<{
+        rel: string;
+        href: string;
+        as?: string;
+        type?: string;
+        crossorigin?: string;
+        [key: string]: any;
+    }>;
+    /** Additional meta tags */
+    meta?: Array<{
+        name?: string;
+        property?: string;
+        content: string;
+        [key: string]: any;
+    }>;
+}
+/**
+ * Response structure for SSR rendering
+ *
+ * Can be returned from controllers decorated with @Render.
+ * For backwards compatibility, controllers can also return plain objects
+ * which will be auto-wrapped as { props: data }.
+ *
+ * @example
+ * ```typescript
+ * // Simple case - just props (auto-wrapped)
+ * @Render('views/home')
+ * getHome() {
+ *   return { message: 'Hello' };
+ *   // Treated as: { props: { message: 'Hello' } }
+ * }
+ *
+ * // Advanced case - with head data
+ * @Render('views/user')
+ * getUser(@Param('id') id: string) {
+ *   const user = await this.userService.findOne(id);
+ *   return {
+ *     props: { user },
+ *     head: {
+ *       title: `${user.name} - Profile`,
+ *       description: user.bio,
+ *       ogImage: user.avatar
+ *     }
+ *   };
+ * }
+ * ```
+ */
+interface RenderResponse<T = any> {
+    /** Props passed to the React component */
+    props: T;
+    /** HTML head data (title, meta tags, links) */
+    head?: HeadData;
+}
+
+/**
+ * SSR rendering mode configuration
+ */
+type SSRMode = 'string' | 'stream';
+/**
+ * Props for development error page component
+ */
+interface ErrorPageDevelopmentProps$1 {
+    error: Error;
+    viewPath: string;
+    phase: 'shell' | 'streaming';
+}
+/**
+ * Vite development mode configuration
+ */
+type ViteMode = 'proxy' | 'embedded';
+/**
+ * Vite configuration options
+ */
+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)
+     *
+     * @default 5173
+     */
+    port?: number;
+}
+/**
+ * Configuration options for the render module
+ */
+interface RenderConfig {
+    /**
+     * SSR rendering mode
+     * - 'string': Traditional renderToString (simple, proven, easier debugging)
+     * - 'stream': Modern renderToPipeableStream (better performance, progressive rendering)
+     *
+     * @default 'string'
+     */
+    mode?: SSRMode;
+    /**
+     * Timeout in milliseconds for SSR rendering.
+     * If rendering takes longer than this, the request will be aborted.
+     *
+     * @default 10000 (10 seconds)
+     */
+    timeout?: number;
+    /**
+     * Vite configuration for development
+     *
+     * @example
+     * ```typescript
+     * // Zero config - embedded mode by default (simplest)
+     * @Module({
+     *   imports: [RenderModule],
+     * })
+     *
+     * // Proxy mode - external Vite with HMR
+     * @Module({
+     *   imports: [
+     *     RenderModule.register({
+     *       vite: { mode: 'proxy', port: 5173 }
+     *     })
+     *   ],
+     * })
+     * ```
+     */
+    vite?: ViteConfig;
+    /**
+     * Custom error page component for development environment
+     * Receives error details and renders custom error UI
+     *
+     * @default ErrorPageDevelopment from '@shared/render/error-pages'
+     */
+    errorPageDevelopment?: ComponentType<ErrorPageDevelopmentProps$1>;
+    /**
+     * Custom error page component for production environment
+     * Renders generic error without sensitive details
+     *
+     * @default ErrorPageProduction from '@shared/render/error-pages'
+     */
+    errorPageProduction?: ComponentType;
+    /**
+     * Default head data for all pages
+     * Can be overridden per-page by returning head in controller
+     *
+     * For dynamic default head (e.g., from database), use registerAsync
+     *
+     * @example
+     * ```typescript
+     * RenderModule.register({
+     *   defaultHead: {
+     *     title: 'My App',
+     *     description: 'Default description',
+     *     links: [{ rel: 'icon', href: '/favicon.ico' }]
+     *   }
+     * })
+     * ```
+     */
+    defaultHead?: HeadData;
+}
+/**
+ * Template parts for streaming SSR
+ * Template is split into parts that are written around the React stream
+ */
+interface TemplateParts {
+    /** HTML start through <body> tag */
+    htmlStart: string;
+    /** Opening <div id="root"> tag */
+    rootStart: string;
+    /** Closing </div> tag for root */
+    rootEnd: string;
+    /** Closing </body></html> tags */
+    htmlEnd: string;
+}
+
+declare class RenderModule {
+    /**
+     * Register the render module with optional configuration
+     *
+     * @param config - Optional render configuration
+     * @returns Dynamic module
+     *
+     * @example
+     * ```ts
+     * // Zero config - embedded mode by default (simplest)
+     * @Module({
+     *   imports: [RenderModule],
+     * })
+     *
+     * // Enable HMR with proxy mode
+     * @Module({
+     *   imports: [
+     *     RenderModule.register({
+     *       vite: { mode: 'proxy', port: 5173 }
+     *     })
+     *   ],
+     * })
+     *
+     * // Enable streaming SSR
+     * RenderModule.register({ mode: 'stream' })
+     *
+     * // Custom error pages
+     * RenderModule.register({
+     *   mode: 'stream',
+     *   errorPageDevelopment: MyCustomDevErrorPage,
+     *   errorPageProduction: MyCustomProdErrorPage,
+     * })
+     * ```
+     */
+    static register(config?: RenderConfig): DynamicModule;
+    /**
+     * Register the render module asynchronously with dynamic configuration
+     *
+     * Use this when you need to inject services (e.g., load config from database)
+     *
+     * @param options - Async configuration options
+     * @returns Dynamic module
+     *
+     * @example
+     * ```ts
+     * // Load default head from database
+     * RenderModule.registerAsync({
+     *   imports: [TenantModule],
+     *   inject: [TenantRepository],
+     *   useFactory: async (tenantRepo: TenantRepository) => {
+     *     const tenant = await tenantRepo.findDefaultTenant();
+     *     return {
+     *       defaultHead: {
+     *         title: tenant.appName,
+     *         description: tenant.description,
+     *         links: [
+     *           { rel: 'icon', href: tenant.favicon }
+     *         ]
+     *       }
+     *     };
+     *   }
+     * })
+     * ```
+     */
+    static registerAsync(options: {
+        imports?: any[];
+        inject?: any[];
+        useFactory: (...args: any[]) => Promise<RenderConfig> | RenderConfig;
+    }): DynamicModule;
+}
+
+/**
+ * Service for parsing HTML templates and building inline scripts for SSR
+ */
+declare class TemplateParserService {
+    private readonly headTagRenderers;
+    /**
+     * Parse HTML template into parts for streaming SSR
+     *
+     * Splits the template at strategic injection points:
+     * - Before root div: Shell HTML (head, body start)
+     * - Root div start
+     * - Root div end
+     * - After root: Scripts and closing tags
+     */
+    parseTemplate(html: string): TemplateParts;
+    /**
+     * 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.
+     */
+    buildInlineScripts(data: any, context: any, componentPath: string): string;
+    /**
+     * Get client script tag for hydration
+     *
+     * In development: Direct module import with Vite HMR
+     * In production: Hashed filename from manifest
+     */
+    getClientScriptTag(isDevelopment: boolean, manifest?: any): string;
+    /**
+     * Get stylesheet link tags
+     *
+     * In development: Direct link to source CSS file
+     * In production: Hashed CSS files from manifest
+     */
+    getStylesheetTags(isDevelopment: boolean, manifest?: any): string;
+    /**
+     * Build HTML head tags from HeadData
+     *
+     * Generates title, meta tags, and link tags for SEO and page metadata.
+     * Safely escapes content using escape-html to prevent XSS.
+     */
+    buildHeadTags(head?: HeadData): string;
+    /**
+     * Build an HTML tag from an object of attributes
+     */
+    private buildTag;
+}
+
+/**
+ * Error handling strategies for streaming SSR
+ *
+ * Streaming has different error phases:
+ * 1. Shell errors: Before any content sent (can send 500)
+ * 2. Stream errors: After headers sent (can only log)
+ * 3. Client errors: Handled by ErrorBoundary
+ */
+declare class StreamingErrorHandler {
+    private readonly errorPageDevelopment?;
+    private readonly errorPageProduction?;
+    private readonly logger;
+    constructor(errorPageDevelopment?: ComponentType<ErrorPageDevelopmentProps$1> | undefined, errorPageProduction?: ComponentType | undefined);
+    /**
+     * Handle error that occurred before shell was ready
+     * Can still set HTTP status code and send error page
+     */
+    handleShellError(error: Error, res: Response, viewPath: string, isDevelopment: boolean): void;
+    /**
+     * Handle error that occurred during streaming
+     * Headers already sent, can only log the error
+     */
+    handleStreamError(error: Error, viewPath: string): void;
+    /**
+     * Render development error page using React component
+     */
+    private renderDevelopmentErrorPage;
+    /**
+     * Render production error page using React component
+     */
+    private renderProductionErrorPage;
+}
+
+declare class RenderService {
+    private readonly templateParser;
+    private readonly streamingErrorHandler;
+    private readonly defaultHead?;
+    private readonly logger;
+    private vite;
+    private template;
+    private manifest;
+    private serverManifest;
+    private isDevelopment;
+    private ssrMode;
+    constructor(templateParser: TemplateParserService, streamingErrorHandler: StreamingErrorHandler, ssrMode?: SSRMode, defaultHead?: HeadData | undefined);
+    setViteServer(vite: ViteDevServer): void;
+    /**
+     * Main render method that routes to string or stream mode
+     */
+    render(viewPath: string, data?: any, res?: Response, head?: HeadData): Promise<string | void>;
+    /**
+     * 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 {
+    private reflector;
+    private renderService;
+    constructor(reflector: Reflector, renderService: RenderService);
+    intercept(context: ExecutionContext, next: CallHandler): Observable<any>;
+}
+
+interface ErrorPageDevelopmentProps {
+    error: Error;
+    viewPath: string;
+    phase: 'shell' | 'streaming';
+}
+/**
+ * Default development error page component
+ *
+ * Shows detailed error information with stack trace
+ * App developers can override this by providing their own component
+ */
+declare function ErrorPageDevelopment({ error, viewPath, phase, }: ErrorPageDevelopmentProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Default production error page component
+ *
+ * Shows generic error message without sensitive details
+ * App developers can override this by providing their own component
+ */
+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 };