@nestjs-ssr/react 0.1.5 → 0.1.7

package/README.md

@@ -12,23 +12,29 @@ If you value [Uncle Bob's Clean Architecture](https://blog.cleancoder.com/uncle-
 
 **Clear Separation of Concerns:**
 ```typescript
+// View component with typed props (Presentation Layer)
+export interface UserProfileProps {
+  user: User;
+}
+
+export default function UserProfile(props: PageProps<UserProfileProps>) {
+  return <div>{props.user.name}</div>;  // Pure presentation
+}
+
 // Server logic stays in controllers (Application Layer)
+import UserProfile from './views/user-profile';
+
 @Controller()
 export class UserController {
   constructor(private userService: UserService) {}  // Proper DI
 
   @Get('/users/:id')
-  @Render('views/user-profile')
+  @Render(UserProfile)  // Type-safe! Cmd+Click to navigate
   async getUserProfile(@Param('id') id: string) {
     const user = await this.userService.findById(id);  // Business logic
-    return { user };  // Pure data - no rendering concerns
+    return { user };  // ✅ TypeScript validates this matches UserProfileProps
   }
 }
-
-// View logic stays in React components (Presentation Layer)
-export default function UserProfile({ data }: PageProps<{ user: User }>) {
-  return <div>{data.user.name}</div>;  // Pure presentation
-}
 ```
 
 **No Server/Client Confusion:**
@@ -73,24 +79,30 @@ export default function Page() {
 
 **NestJS SSR maintains boundaries:**
 ```tsx
+// ✅ View: Client-only, pure presentation
+export interface ProductsProps {
+  products: Product[];
+}
+
+export default function Products(props: PageProps<ProductsProps>) {
+  const [selected, setSelected] = useState(null);
+  return <ProductList products={props.products} onSelect={setSelected} />;
+}
+
 // ✅ Controller: Server-only, testable, uses DI
+import Products from './views/products';
+
 @Controller()
 export class ProductController {
   constructor(private productService: ProductService) {}
 
   @Get('/products')
   @UseGuards(AuthGuard)  // Proper middleware
-  @Render('views/products')
+  @Render(Products)  // Type-safe component reference
   async list() {
     return { products: await this.productService.findAll() };
   }
 }
-
-// ✅ View: Client-only, pure presentation
-export default function Products({ data }: PageProps) {
-  const [selected, setSelected] = useState(null);
-  return <ProductList products={data.products} onSelect={setSelected} />;
-}
 ```
 
 ### Performance as a Bonus
@@ -105,6 +117,8 @@ Following clean architecture doesn't mean sacrificing performance. In our benchm
 
 ## Features
 
+✅ **Type-Safe Props** - Automatic validation of controller return types against component props
+✅ **IDE Navigation** - Cmd+Click on components to jump to view files
 ✅ **Architectural Integrity** - Respects SOLID and Clean Architecture principles
 ✅ **Dependency Injection** - Full NestJS DI throughout your application
 ✅ **Clear Boundaries** - Server code is server, client code is client
@@ -129,10 +143,15 @@ npm install @nestjs-ssr/react react react-dom vite
 // vite.config.ts
 import { defineConfig } from 'vite';
 import react from '@vitejs/plugin-react';
-import { viewRegistryPlugin } from '@nestjs-ssr/react/vite';
+import { resolve } from 'path';
 
 export default defineConfig({
-  plugins: [react(), viewRegistryPlugin()],
+  plugins: [react()],
+  resolve: {
+    alias: {
+      '@': resolve(__dirname, 'src'),
+    },
+  },
 });
 ```
 
@@ -151,18 +170,18 @@ import { RenderModule } from '@nestjs-ssr/react';
 export class AppModule {}
 ```
 
-### 3. Create a View
+### 3. Create a View Component
 
 ```typescript
 // src/views/home.tsx
 import type { PageProps } from '@nestjs-ssr/react';
 
-interface HomeData {
+export interface HomeProps {
   message: string;
 }
 
-export default function Home({ data }: PageProps<HomeData>) {
-  return <h1>{data.message}</h1>;
+export default function Home(props: PageProps<HomeProps>) {
+  return <h1>{props.message}</h1>;
 }
 ```
 
@@ -172,61 +191,21 @@ export default function Home({ data }: PageProps<HomeData>) {
 // 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('views/home')
+  @Render(Home)  // Type-safe! Cmd+Click to navigate to view
   getHome() {
     return { message: 'Hello from NestJS SSR!' };
   }
 }
 ```
 
-### 5. Add Entry Files
+That's it! No manual view registry or entry files needed - everything is handled automatically.
 
-Create these files in `src/view/`:
-
-**entry-client.tsx**:
-```typescript
-import { StrictMode } from 'react';
-import { hydrateRoot } from 'react-dom/client';
-import { viewRegistry } from './view-registry.generated';
-
-const viewPath = window.__COMPONENT_PATH__;
-const initialProps = window.__INITIAL_STATE__ || {};
-const renderContext = window.__CONTEXT__ || {};
-
-const ViewComponent = viewRegistry[viewPath];
-
-if (!ViewComponent) {
-  throw new Error(`View "${viewPath}" not found in registry`);
-}
-
-hydrateRoot(
-  document.getElementById('root')!,
-  <StrictMode>
-    <ViewComponent data={initialProps} context={renderContext} />
-  </StrictMode>
-);
-```
-
-**entry-server.tsx**:
-```typescript
-import { viewRegistry } from './view-registry.generated';
-
-export function render(viewPath: string, props: any, context: any) {
-  const ViewComponent = viewRegistry[viewPath];
-
-  if (!ViewComponent) {
-    throw new Error(`View "${viewPath}" not found in registry`);
-  }
-
-  return <ViewComponent data={props} context={context} />;
-}
-```
-
-### 6. Run
+### 5. Run
 
 ```bash
 npm run dev
@@ -238,38 +217,46 @@ Visit [http://localhost:3000](http://localhost:3000) 🎉
 
 ### The `@Render` Decorator
 
-The decorator intercepts your controller's response and renders it with React:
+The decorator takes a React component and automatically validates that your controller returns the correct props:
 
 ```typescript
+import UserProfile from './views/user-profile';
+
 @Get('/users/:id')
-@Render('users/views/user-profile')
+@Render(UserProfile)  // Type-safe! Cmd+Click to navigate
 async getUser(@Param('id') id: string) {
   const user = await this.userService.findOne(id);
-  return { user }; // Passed as `data` prop to component
+  return { user }; // ✅ TypeScript validates this matches component props
 }
 ```
 
 ### Type-Safe Props
 
-Components receive props with full TypeScript support:
+Components receive props with full TypeScript support and validation:
 
 ```typescript
-import type { PageProps, RenderContext } from '@nestjs-ssr/react';
+import type { PageProps } from '@nestjs-ssr/react';
 
-interface UserData {
+export interface UserProfileProps {
   user: User;
 }
 
-export default function UserProfile({ data, context }: PageProps<UserData>) {
+export default function UserProfile(props: PageProps<UserProfileProps>) {
   return (
     <div>
-      <h1>{data.user.name}</h1>
-      <p>Requested from: {context.path}</p>
+      <h1>{props.user.name}</h1>
+      <p>Requested from: {props.context.path}</p>
     </div>
   );
 }
 ```
 
+**Benefits:**
+- ✅ Build-time validation - wrong props = compilation error
+- ✅ Cmd+Click navigation from controller to view file
+- ✅ No manual type annotations needed
+- ✅ Refactoring-friendly - rename props with confidence
+
 ### Request Context
 
 Every component receives the request context:

package/dist/{index-Bptct1Q3.d.mts → index-Bpzo1KfR.d.mts}

@@ -295,7 +295,7 @@ declare class TemplateParserService {
      * 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;
+    buildInlineScripts(data: any, context: any, componentName: string): string;
     /**
      * Get client script tag for hydration
      *
@@ -367,12 +367,14 @@ declare class RenderService {
     private serverManifest;
     private isDevelopment;
     private ssrMode;
+    private readonly entryServerPath;
+    private readonly entryClientPath;
     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>;
+    render(viewComponent: any, data?: any, res?: Response, head?: HeadData): Promise<string | void>;
     /**
      * Merge default head with page-specific head
      * Page-specific head values override defaults

package/dist/{index-Bptct1Q3.d.ts → index-Bpzo1KfR.d.ts}

@@ -295,7 +295,7 @@ declare class TemplateParserService {
      * 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;
+    buildInlineScripts(data: any, context: any, componentName: string): string;
     /**
      * Get client script tag for hydration
      *
@@ -367,12 +367,14 @@ declare class RenderService {
     private serverManifest;
     private isDevelopment;
     private ssrMode;
+    private readonly entryServerPath;
+    private readonly entryClientPath;
     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>;
+    render(viewComponent: any, data?: any, res?: Response, head?: HeadData): Promise<string | void>;
     /**
      * Merge default head with page-specific head
      * Page-specific head values override defaults

package/dist/index.d.mts

@@ -1,8 +1,7 @@
-import { H as HeadData } from './index-Bptct1Q3.mjs';
-export { E as ErrorPageDevelopment, f as ErrorPageProduction, c as RenderConfig, b as RenderInterceptor, R as RenderModule, e as RenderResponse, a as RenderService, d as SSRMode, S as StreamingErrorHandler, T as TemplateParserService } from './index-Bptct1Q3.mjs';
-import * as _nestjs_common from '@nestjs/common';
-export { viewRegistryPlugin } from './vite/index.mjs';
-import 'react';
+import { H as HeadData } from './index-Bpzo1KfR.mjs';
+export { E as ErrorPageDevelopment, f as ErrorPageProduction, c as RenderConfig, b as RenderInterceptor, R as RenderModule, e as RenderResponse, a as RenderService, d as SSRMode, S as StreamingErrorHandler, T as TemplateParserService } from './index-Bpzo1KfR.mjs';
+import React from 'react';
+import '@nestjs/common';
 import 'vite';
 import 'express';
 import '@nestjs/core';
@@ -122,39 +121,49 @@ type PageProps<TProps = {}> = TProps & {
 };
 
 /**
- * Interface for view paths - augmented by the generated view registry.
- * This enables type-safe path validation in Render decorator.
+ * Extract the data type T from PageProps<T>.
+ * PageProps<T> = T & { head?, context }, so we extract T by removing those keys.
  */
-interface ViewPaths {
-}
+type ExtractPagePropsData<P> = P extends PageProps<infer T> ? T : P extends {
+    head?: any;
+    context: any;
+} ? Omit<P, 'head' | 'context'> : P;
 /**
- * Type-safe view path - union of all registered view paths.
- * This is populated via module augmentation from the generated view registry.
+ * Extract controller return type from a React component's props.
  */
-type ViewPath = keyof ViewPaths extends never ? string : keyof ViewPaths;
+type ExtractComponentData<T> = T extends React.ComponentType<infer P> ? ExtractPagePropsData<P> : never;
 /**
  * Decorator to render a React component as the response.
- * Provides IDE autocomplete and type checking for view paths.
  *
- * Works the same as NestJS's @Render() decorator for template engines,
- * but renders React components with SSR instead.
+ * Import the component directly for Cmd+Click navigation in your IDE.
+ * TypeScript automatically validates your controller returns the correct props.
  *
- * @param viewPath - Path to the React component (e.g., 'users/views/user-list')
+ * @param component - The React component to render
  *
  * @example
  * ```typescript
+ * // Your view component (views/home.tsx)
+ * export interface HomeProps {
+ *   message: string;
+ * }
+ * export default function Home(props: PageProps<HomeProps>) { ... }
+ *
+ * // Your controller - Cmd+Click on Home navigates to the view file!
+ * import Home from './views/home';
+ *
  * @Get()
- * @Render('users/views/user-list')
- * getUsers() {
- *   return { users: [...] };
+ * @Render(Home)  // Type-safe! Wrong props = build error
+ * getHome() {
+ *   return { message: 'Hello' }; // ✅ Correct
+ *   // return { wrong: 'prop' }; // ❌ Type error!
  * }
  * ```
  */
-declare const Render: (viewPath: ViewPath) => _nestjs_common.CustomDecorator<string>;
+declare function Render<T extends React.ComponentType<any>>(component: T): <TMethod extends (...args: any[]) => ExtractComponentData<T> | Promise<ExtractComponentData<T>>>(target: any, propertyKey: string | symbol, descriptor: TypedPropertyDescriptor<TMethod>) => TypedPropertyDescriptor<TMethod> | void;
 /**
  * @deprecated Use `Render` instead. This alias will be removed in a future version.
  */
-declare const ReactRender: (viewPath: ViewPath) => _nestjs_common.CustomDecorator<string>;
+declare const ReactRender: typeof Render;
 
 /**
  * Hook to access the full page context.
@@ -217,4 +226,4 @@ declare function useQuery(): Record<string, string | string[]>;
  */
 declare function useUserAgent(): string | undefined;
 
-export { HeadData, type PageProps, ReactRender, Render, type RenderContext, type ViewPath, type ViewPaths, usePageContext, useParams, useQuery, useUserAgent };
+export { HeadData, type PageProps, ReactRender, Render, type RenderContext, usePageContext, useParams, useQuery, useUserAgent };

package/dist/index.d.ts

@@ -1,8 +1,7 @@
-import { H as HeadData } from './index-Bptct1Q3.js';
-export { E as ErrorPageDevelopment, f as ErrorPageProduction, c as RenderConfig, b as RenderInterceptor, R as RenderModule, e as RenderResponse, a as RenderService, d as SSRMode, S as StreamingErrorHandler, T as TemplateParserService } from './index-Bptct1Q3.js';
-import * as _nestjs_common from '@nestjs/common';
-export { viewRegistryPlugin } from './vite/index.js';
-import 'react';
+import { H as HeadData } from './index-Bpzo1KfR.js';
+export { E as ErrorPageDevelopment, f as ErrorPageProduction, c as RenderConfig, b as RenderInterceptor, R as RenderModule, e as RenderResponse, a as RenderService, d as SSRMode, S as StreamingErrorHandler, T as TemplateParserService } from './index-Bpzo1KfR.js';
+import React from 'react';
+import '@nestjs/common';
 import 'vite';
 import 'express';
 import '@nestjs/core';
@@ -122,39 +121,49 @@ type PageProps<TProps = {}> = TProps & {
 };
 
 /**
- * Interface for view paths - augmented by the generated view registry.
- * This enables type-safe path validation in Render decorator.
+ * Extract the data type T from PageProps<T>.
+ * PageProps<T> = T & { head?, context }, so we extract T by removing those keys.
  */
-interface ViewPaths {
-}
+type ExtractPagePropsData<P> = P extends PageProps<infer T> ? T : P extends {
+    head?: any;
+    context: any;
+} ? Omit<P, 'head' | 'context'> : P;
 /**
- * Type-safe view path - union of all registered view paths.
- * This is populated via module augmentation from the generated view registry.
+ * Extract controller return type from a React component's props.
  */
-type ViewPath = keyof ViewPaths extends never ? string : keyof ViewPaths;
+type ExtractComponentData<T> = T extends React.ComponentType<infer P> ? ExtractPagePropsData<P> : never;
 /**
  * Decorator to render a React component as the response.
- * Provides IDE autocomplete and type checking for view paths.
  *
- * Works the same as NestJS's @Render() decorator for template engines,
- * but renders React components with SSR instead.
+ * Import the component directly for Cmd+Click navigation in your IDE.
+ * TypeScript automatically validates your controller returns the correct props.
  *
- * @param viewPath - Path to the React component (e.g., 'users/views/user-list')
+ * @param component - The React component to render
  *
  * @example
  * ```typescript
+ * // Your view component (views/home.tsx)
+ * export interface HomeProps {
+ *   message: string;
+ * }
+ * export default function Home(props: PageProps<HomeProps>) { ... }
+ *
+ * // Your controller - Cmd+Click on Home navigates to the view file!
+ * import Home from './views/home';
+ *
  * @Get()
- * @Render('users/views/user-list')
- * getUsers() {
- *   return { users: [...] };
+ * @Render(Home)  // Type-safe! Wrong props = build error
+ * getHome() {
+ *   return { message: 'Hello' }; // ✅ Correct
+ *   // return { wrong: 'prop' }; // ❌ Type error!
  * }
  * ```
  */
-declare const Render: (viewPath: ViewPath) => _nestjs_common.CustomDecorator<string>;
+declare function Render<T extends React.ComponentType<any>>(component: T): <TMethod extends (...args: any[]) => ExtractComponentData<T> | Promise<ExtractComponentData<T>>>(target: any, propertyKey: string | symbol, descriptor: TypedPropertyDescriptor<TMethod>) => TypedPropertyDescriptor<TMethod> | void;
 /**
  * @deprecated Use `Render` instead. This alias will be removed in a future version.
  */
-declare const ReactRender: (viewPath: ViewPath) => _nestjs_common.CustomDecorator<string>;
+declare const ReactRender: typeof Render;
 
 /**
  * Hook to access the full page context.
@@ -217,4 +226,4 @@ declare function useQuery(): Record<string, string | string[]>;
  */
 declare function useUserAgent(): string | undefined;
 
-export { HeadData, type PageProps, ReactRender, Render, type RenderContext, type ViewPath, type ViewPaths, usePageContext, useParams, useQuery, useUserAgent };
+export { HeadData, type PageProps, ReactRender, Render, type RenderContext, usePageContext, useParams, useQuery, useUserAgent };