@nestjs-ssr/react 0.1.12 → 0.2.0

package/etc/react.api.md

@@ -0,0 +1,262 @@
+## API Report File for "@nestjs-ssr/react"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+import { CallHandler } from '@nestjs/common';
+import { ComponentType } from 'react';
+import { DynamicModule } from '@nestjs/common';
+import { ExecutionContext } from '@nestjs/common';
+import { NestInterceptor } from '@nestjs/common';
+import { Observable } from 'rxjs';
+import { default as React_2 } from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { Reflector } from '@nestjs/core';
+import { Response as Response_2 } from 'express';
+import { ViteDevServer } from 'vite';
+
+// Warning: (ae-forgotten-export) The symbol "ErrorPageDevelopmentProps" needs to be exported by the entry point index.d.ts
+//
+// @public
+export function ErrorPageDevelopment({
+  error,
+  viewPath,
+  phase,
+}: ErrorPageDevelopmentProps): react_jsx_runtime.JSX.Element;
+
+// @public
+export function ErrorPageProduction(): react_jsx_runtime.JSX.Element;
+
+// @public
+export interface HeadData {
+  bodyAttributes?: Record<string, string>;
+  canonical?: string;
+  description?: string;
+  htmlAttributes?: Record<string, string>;
+  jsonLd?: Array<Record<string, any>>;
+  keywords?: string;
+  links?: Array<{
+    rel: string;
+    href: string;
+    as?: string;
+    type?: string;
+    crossorigin?: string;
+    [key: string]: any;
+  }>;
+  meta?: Array<{
+    name?: string;
+    property?: string;
+    content: string;
+    [key: string]: any;
+  }>;
+  ogDescription?: string;
+  ogImage?: string;
+  ogTitle?: string;
+  scripts?: Array<{
+    src?: string;
+    async?: boolean;
+    defer?: boolean;
+    type?: string;
+    innerHTML?: string;
+    [key: string]: any;
+  }>;
+  title?: string;
+}
+
+// @public
+export function Layout(
+  layout: LayoutComponent<any>,
+  options?: LayoutDecoratorOptions,
+): ClassDecorator;
+
+// @public
+export type LayoutComponent<TProps = {}> = ComponentType<LayoutProps<TProps>>;
+
+// @public
+export interface LayoutDecoratorOptions {
+  props?: Record<string, any>;
+  skipRoot?: boolean;
+}
+
+// @public
+export interface LayoutProps<TProps = {}> {
+  children: ReactNode;
+  context?: RenderContext;
+  head?: HeadData;
+  layoutProps?: TProps;
+}
+
+// @public
+export interface PageComponentWithLayout<TPageProps = {}, TLayoutProps = {}> {
+  (props: TPageProps): ReactNode;
+  layout?: LayoutComponent<TLayoutProps>;
+  layoutProps?: TLayoutProps;
+}
+
+// @public
+export type PageProps<TProps = {}> = TProps & {
+  head?: HeadData;
+  context: RenderContext;
+};
+
+// Warning: (ae-forgotten-export) The symbol "RenderReturnType" needs to be exported by the entry point index.d.ts
+// Warning: (ae-forgotten-export) The symbol "ExtractComponentData" needs to be exported by the entry point index.d.ts
+//
+// @public
+export function Render<T extends React_2.ComponentType<any>>(
+  component: T,
+  options?: RenderOptions,
+): <
+  TMethod extends (
+    ...args: any[]
+  ) =>
+    | RenderReturnType<ExtractComponentData<T>>
+    | Promise<RenderReturnType<ExtractComponentData<T>>>,
+>(
+  target: any,
+  propertyKey: string | symbol,
+  descriptor: TypedPropertyDescriptor<TMethod>,
+) => TypedPropertyDescriptor<TMethod> | void;
+
+// @public
+export interface RenderConfig {
+  defaultHead?: HeadData;
+  // Warning: (ae-forgotten-export) The symbol "ErrorPageDevelopmentProps$1" needs to be exported by the entry point index.d.ts
+  errorPageDevelopment?: ComponentType<ErrorPageDevelopmentProps$1>;
+  errorPageProduction?: ComponentType;
+  mode?: SSRMode;
+  template?: string;
+  timeout?: number;
+  // Warning: (ae-forgotten-export) The symbol "ViteConfig" needs to be exported by the entry point index.d.ts
+  vite?: ViteConfig;
+}
+
+// @public
+export interface RenderContext {
+  // (undocumented)
+  [key: string]: any;
+  // (undocumented)
+  acceptLanguage?: string;
+  // (undocumented)
+  cookies?: Record<string, string>;
+  // (undocumented)
+  headers?: Record<string, string>;
+  // (undocumented)
+  method: string;
+  // (undocumented)
+  params: Record<string, string>;
+  // (undocumented)
+  path: string;
+  // (undocumented)
+  query: Record<string, string | string[]>;
+  // (undocumented)
+  referer?: string;
+  // (undocumented)
+  url: string;
+  // (undocumented)
+  userAgent?: string;
+}
+
+// @public (undocumented)
+export class RenderInterceptor implements NestInterceptor {
+  constructor(reflector: Reflector, renderService: RenderService);
+  // (undocumented)
+  intercept(context: ExecutionContext, next: CallHandler): Observable<any>;
+}
+
+// @public (undocumented)
+export class RenderModule {
+  static register(config?: RenderConfig): DynamicModule;
+  static registerAsync(options: {
+    imports?: any[];
+    inject?: any[];
+    useFactory: (...args: any[]) => Promise<RenderConfig> | RenderConfig;
+  }): DynamicModule;
+}
+
+// @public
+export interface RenderOptions {
+  layout?: LayoutComponent<any> | false | null;
+  layoutProps?: Record<string, any>;
+}
+
+// @public
+export interface RenderResponse<T = any> {
+  head?: HeadData;
+  layoutProps?: Record<string, any>;
+  props: T;
+}
+
+// @public (undocumented)
+export class RenderService {
+  constructor(
+    templateParser: TemplateParserService,
+    streamingErrorHandler: StreamingErrorHandler,
+    ssrMode?: SSRMode,
+    defaultHead?: HeadData | undefined,
+    customTemplate?: string,
+  );
+  getRootLayout(): Promise<any | null>;
+  render(
+    viewComponent: any,
+    data?: any,
+    res?: Response_2,
+    head?: HeadData,
+  ): Promise<string | void>;
+  // (undocumented)
+  setViteServer(vite: ViteDevServer): void;
+}
+
+// @public
+export type SSRMode = 'string' | 'stream';
+
+// @public
+export class StreamingErrorHandler {
+  constructor(
+    errorPageDevelopment?:
+      | ComponentType<ErrorPageDevelopmentProps$1>
+      | undefined,
+    errorPageProduction?: ComponentType | undefined,
+  );
+  handleShellError(
+    error: Error,
+    res: Response_2,
+    viewPath: string,
+    isDevelopment: boolean,
+  ): void;
+  handleStreamError(error: Error, viewPath: string): void;
+}
+
+// @public
+export class TemplateParserService {
+  buildHeadTags(head?: HeadData): string;
+  buildInlineScripts(
+    data: any,
+    context: any,
+    componentName: string,
+    layouts?: Array<{
+      layout: any;
+      props?: any;
+    }>,
+  ): string;
+  getClientScriptTag(isDevelopment: boolean, manifest?: any): string;
+  getStylesheetTags(isDevelopment: boolean, manifest?: any): string;
+  // Warning: (ae-forgotten-export) The symbol "TemplateParts" needs to be exported by the entry point index.d.ts
+  parseTemplate(html: string): TemplateParts;
+}
+
+// @public
+export function usePageContext(): RenderContext;
+
+// @public
+export function useParams(): Record<string, string>;
+
+// @public
+export function useQuery(): Record<string, string | string[]>;
+
+// @public
+export function useUserAgent(): string | undefined;
+
+// (No @packageDocumentation comment for this package)
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nestjs-ssr/react",
-  "version": "0.1.12",
+  "version": "0.2.0",
   "description": "React SSR for NestJS that respects Clean Architecture. Proper DI, SOLID principles, clear separation of concerns.",
   "keywords": [
     "nestjs",
@@ -63,6 +63,7 @@
   },
   "files": [
     "dist",
+    "etc",
     "src/templates",
     "src/global.d.ts",
     "README.md",
@@ -78,8 +79,24 @@
     "test:watch": "vitest",
     "test:ui": "vitest --ui",
     "test:coverage": "vitest run --coverage",
-    "prepublishOnly": "pnpm build && pnpm typecheck && pnpm test"
+    "size": "size-limit",
+    "api:extract": "api-extractor run --local --verbose",
+    "api:check": "api-extractor run --verbose",
+    "copy:readme": "cp ../../README.md README.md",
+    "prepublishOnly": "pnpm copy:readme && pnpm build && pnpm typecheck && pnpm test"
   },
+  "size-limit": [
+    {
+      "name": "Core (CJS)",
+      "path": "dist/index.js",
+      "limit": "30 KB"
+    },
+    {
+      "name": "Core (ESM)",
+      "path": "dist/index.mjs",
+      "limit": "30 KB"
+    }
+  ],
   "peerDependencies": {
     "@nestjs/common": "^11.0.0",
     "@nestjs/core": "^11.0.0",
@@ -98,13 +115,15 @@
   "dependencies": {
     "citty": "^0.1.6",
     "consola": "^3.4.2",
-    "escape-html": "^1.0.3",
-    "serialize-javascript": "^6.0.2"
+    "devalue": "^5.1.1",
+    "escape-html": "^1.0.3"
   },
   "devDependencies": {
+    "@microsoft/api-extractor": "^7.55.2",
     "@nestjs/common": "^11.0.0",
     "@nestjs/core": "^11.0.0",
     "@nestjs/platform-express": "^11.0.0",
+    "@nestjs/testing": "^11.1.9",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.0",
     "@types/escape-html": "^1.0.4",
@@ -112,17 +131,19 @@
     "@types/node": "^22.0.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
-    "@types/serialize-javascript": "^5.0.4",
+    "@types/supertest": "^6.0.3",
     "@vitejs/plugin-react": "^4.7.0",
-    "@vitest/ui": "^4.0.14",
+    "@vitest/coverage-v8": "^4.0.15",
+    "@vitest/ui": "^4.0.15",
     "happy-dom": "^20.0.11",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "rxjs": "^7.8.2",
+    "supertest": "^7.1.4",
     "tsup": "^8.0.0",
     "typescript": "^5.7.2",
     "vite": "^7.0.5",
-    "vitest": "^4.0.14"
+    "vitest": "^4.0.15"
   },
   "publishConfig": {
     "access": "public"

package/src/global.d.ts

@@ -32,7 +32,7 @@ declare global {
         import?: string;
         query?: string | Record<string, string | number | boolean>;
         as?: string;
-      }
+      },
     ): Record<string, T>;
   }
 }

package/src/templates/entry-client.tsx

@@ -1,6 +1,7 @@
 /// <reference path="../global.d.ts" />
 import React, { StrictMode } from 'react';
 import { hydrateRoot } from 'react-dom/client';
+import { PageContextProvider } from '../react/hooks/use-page-context';
 
 const componentName = window.__COMPONENT_NAME__;
 const initialProps = window.__INITIAL_STATE__ || {};
@@ -8,7 +9,8 @@ const renderContext = window.__CONTEXT__ || {};
 
 // Auto-import all view components using Vite's glob feature
 // @ts-ignore - Vite-specific API
-const modules: Record<string, { default: React.ComponentType<any> }> = import.meta.glob('@/views/**/*.tsx', { eager: true });
+const modules: Record<string, { default: React.ComponentType<any> }> =
+  import.meta.glob('@/views/**/*.tsx', { eager: true });
 
 // Build a map of components with their metadata
 // Filter out entry files and modules without default exports
@@ -26,7 +28,9 @@ const componentMap = Object.entries(modules)
     const component = module.default;
     const name = component.displayName || component.name;
     const filename = path.split('/').pop()?.replace('.tsx', '');
-    const normalizedFilename = filename ? filename.charAt(0).toUpperCase() + filename.slice(1) : undefined;
+    const normalizedFilename = filename
+      ? filename.charAt(0).toUpperCase() + filename.slice(1)
+      : undefined;
 
     return { path, component, name, filename, normalizedFilename };
   });
@@ -40,7 +44,10 @@ let ViewComponent: React.ComponentType<any> | undefined;
 
 // Try exact name match first
 ViewComponent = componentMap.find(
-  (c) => c.name === componentName || c.normalizedFilename === componentName || c.filename === componentName.toLowerCase()
+  (c) =>
+    c.name === componentName ||
+    c.normalizedFilename === componentName ||
+    c.filename === componentName.toLowerCase(),
 )?.component;
 
 // If no match found and component name looks like a generic/minified name (default, default_1, etc.)
@@ -56,7 +63,7 @@ if (!ViewComponent && /^default(_\d+)?$/.test(componentName)) {
 
     // Get all components with name "default" (anonymous functions), sorted by path for consistency
     const defaultComponents = componentMap
-      .filter(c => c.name === 'default')
+      .filter((c) => c.name === 'default')
       .sort((a, b) => a.path.localeCompare(b.path));
 
     // Try to match by index
@@ -67,17 +74,77 @@ if (!ViewComponent && /^default(_\d+)?$/.test(componentName)) {
 }
 
 if (!ViewComponent) {
-  const availableComponents = Object.entries(modules).map(([path, m]) => {
-    const filename = path.split('/').pop()?.replace('.tsx', '');
-    const name = m.default.displayName || m.default.name;
-    return `${filename} (${name})`;
-  }).join(', ');
-  throw new Error(`Component "${componentName}" not found in views directory. Available: ${availableComponents}`);
+  const availableComponents = Object.entries(modules)
+    .map(([path, m]) => {
+      const filename = path.split('/').pop()?.replace('.tsx', '');
+      const name = m.default.displayName || m.default.name;
+      return `${filename} (${name})`;
+    })
+    .join(', ');
+  throw new Error(
+    `Component "${componentName}" not found in views directory. Available: ${availableComponents}`,
+  );
+}
+
+/**
+ * Check if a component has a layout property
+ */
+function hasLayout(
+  component: any,
+): component is { layout: React.ComponentType<any>; layoutProps?: any } {
+  return component && typeof component.layout === 'function';
+}
+
+/**
+ * Compose a component with its layout (and nested layouts if any)
+ * This must match the server-side composition in entry-server.tsx
+ */
+function composeWithLayout(
+  ViewComponent: React.ComponentType<any>,
+  props: any,
+): React.ReactElement {
+  const element = <ViewComponent {...props} />;
+
+  // Check if component has a layout
+  if (!hasLayout(ViewComponent)) {
+    return element;
+  }
+
+  // Collect all layouts in the chain (innermost to outermost)
+  const layoutChain: Array<{
+    Layout: React.ComponentType<any>;
+    layoutProps: any;
+  }> = [];
+  let currentComponent: any = ViewComponent;
+
+  while (hasLayout(currentComponent)) {
+    layoutChain.push({
+      Layout: currentComponent.layout,
+      layoutProps: currentComponent.layoutProps || {},
+    });
+    currentComponent = currentComponent.layout;
+  }
+
+  // Wrap the element with layouts from innermost to outermost
+  let result = element;
+  for (const { Layout, layoutProps } of layoutChain) {
+    result = <Layout layoutProps={layoutProps}>{result}</Layout>;
+  }
+
+  return result;
 }
 
+// Compose the component with its layout (if any)
+const composedElement = composeWithLayout(ViewComponent, initialProps);
+
+// Wrap with PageContextProvider to make context available via hooks
+const wrappedElement = (
+  <PageContextProvider context={renderContext}>
+    {composedElement}
+  </PageContextProvider>
+);
+
 hydrateRoot(
   document.getElementById('root')!,
-  <StrictMode>
-    <ViewComponent {...initialProps} context={renderContext} />
-  </StrictMode>,
+  <StrictMode>{wrappedElement}</StrictMode>,
 );

package/src/templates/entry-server.tsx

@@ -1,10 +1,41 @@
 import React from 'react';
 import { renderToString } from 'react-dom/server';
+import { PageContextProvider } from '../react/hooks/use-page-context';
+
+/**
+ * Compose a component with its layouts from the interceptor
+ * Layouts are passed from the RenderInterceptor based on decorators
+ */
+function composeWithLayouts(
+  ViewComponent: React.ComponentType<any>,
+  props: any,
+  layouts: Array<{ layout: React.ComponentType<any>; props?: any }> = [],
+): React.ReactElement {
+  // Start with the page component
+  let result = <ViewComponent {...props} />;
+
+  // Wrap with each layout in the chain (outermost to innermost in array)
+  // We iterate normally because layouts are already in correct order from interceptor
+  for (const { layout: Layout, props: layoutProps } of layouts) {
+    result = <Layout layoutProps={layoutProps}>{result}</Layout>;
+  }
+
+  return result;
+}
 
 export function renderComponent(
   ViewComponent: React.ComponentType<any>,
   data: any,
 ) {
-  const { data: pageData, __context: context } = data;
-  return renderToString(<ViewComponent {...pageData} context={context} />);
+  const { data: pageData, __context: context, __layouts: layouts } = data;
+  const composedElement = composeWithLayouts(ViewComponent, pageData, layouts);
+
+  // Wrap with PageContextProvider to make context available via hooks
+  const wrappedElement = (
+    <PageContextProvider context={context}>
+      {composedElement}
+    </PageContextProvider>
+  );
+
+  return renderToString(wrappedElement);
 }

package/src/templates/index.html

@@ -4,9 +4,6 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>NestJS React SSR</title>
-    <link rel="preconnect" href="https://fonts.googleapis.com" />
-    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
-    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet" />
     <!--styles-->
   </head>
   <body>