npm - @nestjs-ssr/react - Versions diffs - 0.1.12 → 0.2.0 - Mend

@nestjs-ssr/react 0.1.12 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (22) hide show

package/README.md +53 -85
package/dist/cli/init.js +2 -2
package/dist/cli/init.mjs +2 -2
package/dist/{index-BiaVDe9J.d.mts → index-C5Knql-9.d.mts} +124 -8
package/dist/{index-BiaVDe9J.d.ts → index-C5Knql-9.d.ts} +124 -8
package/dist/index.d.mts +377 -69
package/dist/index.d.ts +377 -69
package/dist/index.js +460 -89
package/dist/index.mjs +459 -85
package/dist/render/index.d.mts +1 -1
package/dist/render/index.d.ts +1 -1
package/dist/render/index.js +253 -64
package/dist/render/index.mjs +253 -63
package/dist/templates/entry-client.tsx +80 -13
package/dist/templates/entry-server.tsx +33 -2
package/dist/templates/index.html +0 -3
package/etc/react.api.md +262 -0
package/package.json +28 -7
package/src/global.d.ts +1 -1
package/src/templates/entry-client.tsx +80 -13
package/src/templates/entry-server.tsx +33 -2
package/src/templates/index.html +0 -3

package/dist/index.d.ts CHANGED Viewed

@@ -1,17 +1,20 @@
-import { H as HeadData } from './index-BiaVDe9J.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-BiaVDe9J.js';
-import React from 'react';
+import { H as HeadData, R as RenderResponse } from './index-C5Knql-9.js';
+export { E as ErrorPageDevelopment, f as ErrorPageProduction, d as RenderConfig, c as RenderInterceptor, a as RenderModule, b as RenderService, e as SSRMode, S as StreamingErrorHandler, T as TemplateParserService } from './index-C5Knql-9.js';
+import React$1, { ComponentType, ReactNode } from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
 import '@nestjs/common';
 import 'vite';
 import 'express';
 import '@nestjs/core';
 import 'rxjs';
-import 'react/jsx-runtime';
 /**
  * Request context available to all React components.
  * Contains safe request metadata that can be exposed to the client.
  *
+ * Extend this interface to add app-specific properties (user, tenant, feature flags, etc.).
+ * Use module configuration to pass additional headers or cookies safely.
+ *
  * @example
  * // Basic usage - use as-is
  * const context: RenderContext = {
@@ -19,6 +22,7 @@ import 'react/jsx-runtime';
  *   path: '/users/123',
  *   query: { tab: 'profile' },
  *   params: { id: '123' },
+ *   method: 'GET',
  * };
  *
  * @example
@@ -34,15 +38,22 @@ import 'react/jsx-runtime';
  *     id: string;
  *     name: string;
  *   };
- *   locale?: string;
+ *   featureFlags?: Record<string, boolean>;
+ *   theme?: string;  // From cookie
  * }
  *
- * // Use in interceptor
+ * // Configure module to pass specific cookies/headers
+ * ReactSSRModule.forRoot({
+ *   allowedCookies: ['theme', 'locale'],
+ *   allowedHeaders: ['x-tenant-id'],
+ * })
+ *
+ * // Use in interceptor/controller
  * const context: AppRenderContext = {
  *   ...baseContext,
  *   user: req.user,
  *   tenant: req.tenant,
- *   locale: req.locale,
+ *   featureFlags: await featureFlagService.getFlags(req),
  * };
  */
 interface RenderContext {
@@ -50,27 +61,40 @@ interface RenderContext {
     path: string;
     query: Record<string, string | string[]>;
     params: Record<string, string>;
-    userAgent?: string;
-    acceptLanguage?: string;
-    referer?: string;
-    [key: string]: any;
+    method: string;
 }
 /**
  * Generic type for React page component props.
  * Spreads controller data directly as props (React-standard pattern).
  *
+ * Request context is available via typed hooks created with createSSRHooks().
+ *
  * @template TProps - The shape of props returned by the controller
  *
  * @example
  * ```typescript
+ * // src/lib/ssr-hooks.ts
+ * import { createSSRHooks, RenderContext } from '@nestjs-ssr/react';
+ *
+ * interface AppRenderContext extends RenderContext {
+ *   user?: User;
+ * }
+ *
+ * export const { usePageContext } = createSSRHooks<AppRenderContext>();
+ *
+ * // src/views/product.tsx
+ * import { usePageContext } from '@/lib/ssr-hooks';
+ *
  * interface ProductPageProps {
  *   product: Product;
  *   relatedProducts: Product[];
  * }
  *
  * export default function ProductDetail(props: PageProps<ProductPageProps>) {
- *   const { product, relatedProducts, head, context } = props;
+ *   const { product, relatedProducts, head } = props;
+ *   const context = usePageContext(); // Fully typed!
+ *
  *   return (
  *     <html>
  *       <head>
@@ -78,6 +102,7 @@ interface RenderContext {
  *       </head>
  *       <body>
  *         <h1>{product.name}</h1>
+ *         <p>Current path: {context.path}</p>
  *       </body>
  *     </html>
  *   );
@@ -108,17 +133,98 @@ type PageProps<TProps = {}> = TProps & {
      * ```
      */
     head?: HeadData;
+};
+/**
+ * Props passed to layout components
+ *
+ * Layout components receive children and can access context/head data.
+ * Additional props can be specified via layoutProps static property.
+ *
+ * @example
+ * ```tsx
+ * export default function MainLayout({ children, title }: LayoutProps<{ title: string }>) {
+ *   return (
+ *     <html>
+ *       <head>
+ *         <title>{title || 'Default Title'}</title>
+ *       </head>
+ *       <body>
+ *         <nav>...</nav>
+ *         <main>{children}</main>
+ *       </body>
+ *     </html>
+ *   );
+ * }
+ * ```
+ */
+interface LayoutProps<TProps = {}> {
     /**
-     * Request context containing URL metadata and safe headers.
-     * Always available on every page component.
-     *
-     * @example
-     * ```typescript
-     * const { path, query, method } = props.context;
-     * ```
+     * Child content to render (the page component or nested layout)
      */
-    context: RenderContext;
-};
+    children: ReactNode;
+    /**
+     * Layout-specific props passed via component.layoutProps
+     */
+    layoutProps?: TProps;
+    /**
+     * Request context available to all layouts
+     */
+    context?: RenderContext;
+    /**
+     * Head metadata that can be read by layouts
+     */
+    head?: HeadData;
+}
+/**
+ * Layout component type
+ *
+ * A layout is a React component that wraps page content.
+ * Page components can declare their layout using static properties.
+ *
+ * @example
+ * ```tsx
+ * // Layout definition
+ * const MainLayout: LayoutComponent<{ title: string }> = ({ children, title }) => (
+ *   <html>
+ *     <body>
+ *       <h1>{title}</h1>
+ *       {children}
+ *     </body>
+ *   </html>
+ * );
+ *
+ * // Page using the layout
+ * function HomePage() {
+ *   return <div>Welcome</div>;
+ * }
+ * HomePage.layout = MainLayout;
+ * HomePage.layoutProps = { title: 'Home' };
+ * ```
+ */
+type LayoutComponent<TProps = {}> = ComponentType<LayoutProps<TProps>>;
+/**
+ * Enhanced page component with layout support
+ *
+ * Page components can optionally specify a layout via static properties.
+ * The framework will automatically wrap the page in the specified layout.
+ */
+interface PageComponentWithLayout<TPageProps = {}, TLayoutProps = {}> {
+    /**
+     * The page component function
+     */
+    (props: TPageProps): ReactNode;
+    /**
+     * Optional layout component to wrap this page
+     * If not specified, the page renders without a layout wrapper.
+     */
+    layout?: LayoutComponent<TLayoutProps>;
+    /**
+     * Optional props to pass to the layout component
+     * These props are available as layoutProps in the LayoutProps.
+     */
+    layoutProps?: TLayoutProps;
+}
 /**
  * Extract the data type T from PageProps<T>.
@@ -131,7 +237,29 @@ type ExtractPagePropsData<P> = P extends PageProps<infer T> ? T : P extends {
 /**
  * Extract controller return type from a React component's props.
  */
-type ExtractComponentData<T> = T extends React.ComponentType<infer P> ? ExtractPagePropsData<P> : never;
+type ExtractComponentData<T> = T extends React$1.ComponentType<infer P> ? ExtractPagePropsData<P> : never;
+/**
+ * Valid return types for a @Render decorated controller method.
+ * Supports both simple props format and RenderResponse format with layoutProps.
+ */
+type RenderReturnType<T> = T | RenderResponse<T>;
+/**
+ * Options for the Render decorator
+ */
+interface RenderOptions {
+    /**
+     * Layout component to wrap this specific route.
+     * - LayoutComponent: Use this layout (replaces controller layout if any)
+     * - false: Skip controller layout, keep root layout only
+     * - null: Skip all layouts (render page only)
+     * - undefined: Use controller layout (default)
+     */
+    layout?: LayoutComponent<any> | false | null;
+    /**
+     * Props to pass to the layout component
+     */
+    layoutProps?: Record<string, any>;
+}
 /**
  * Decorator to render a React component as the response.
  *
@@ -139,6 +267,7 @@ type ExtractComponentData<T> = T extends React.ComponentType<infer P> ? ExtractP
  * TypeScript automatically validates your controller returns the correct props.
  *
  * @param component - The React component to render
+ * @param options - Optional rendering options (layout overrides, etc.)
  *
  * @example
  * ```typescript
@@ -157,73 +286,252 @@ type ExtractComponentData<T> = T extends React.ComponentType<infer P> ? ExtractP
  *   return { message: 'Hello' }; // ✅ Correct
  *   // return { wrong: 'prop' }; // ❌ Type error!
  * }
+ *
+ * // With layout override
+ * @Get('custom')
+ * @Render(CustomPage, { layout: CustomLayout })
+ * getCustom() {
+ *   return { data: 'custom' };
+ * }
+ *
+ * // Skip all layouts
+ * @Get('raw')
+ * @Render(RawPage, { layout: null })
+ * getRaw() {
+ *   return { json: {...} };
+ * }
  * ```
  */
-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;
+declare function Render<T extends React$1.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;
 /**
- * @deprecated Use `Render` instead. This alias will be removed in a future version.
+ * Options for the Layout decorator
  */
-declare const ReactRender: typeof Render;
+interface LayoutDecoratorOptions {
+    /**
+     * Whether to skip the root layout for this controller
+     * @default false
+     */
+    skipRoot?: boolean;
+    /**
+     * Props to pass to the layout component
+     */
+    props?: Record<string, any>;
+}
 /**
- * Hook to access the full page context.
- * Contains URL metadata and request headers.
- *
- * For apps with authentication, extend RenderContext and create custom hooks.
+ * Controller-level decorator to apply a layout to all routes in the controller.
  *
- * @throws Error if used outside PageContextProvider
+ * The layout hierarchy is: Root Layout → Controller Layout → Method Layout → Page
  *
- * @example
- * ```tsx
- * const context = usePageContext();
- * console.log(context.path);  // '/users/123'
- * console.log(context.query); // { search: 'foo' }
- * ```
+ * @param layout - The layout component to wrap all routes in this controller
+ * @param options - Optional configuration for the layout
  *
  * @example
- * // Custom hook for extended context
- * interface AppRenderContext extends RenderContext {
- *   user?: { id: string; name: string };
+ * ```typescript
+ * // Simple usage
+ * @Controller('dashboard')
+ * @Layout(DashboardLayout)
+ * export class DashboardController {
+ *   @Get()
+ *   @Render(DashboardPage) // Renders: Root > DashboardLayout > Page
+ *   getDashboard() {
+ *     return { stats: {...} };
+ *   }
  * }
  *
- * export function useUser() {
- *   return (usePageContext() as AppRenderContext).user;
- * }
+ * // With options
+ * @Controller('admin')
+ * @Layout(AdminLayout, { skipRoot: false, props: { theme: 'dark' } })
+ * export class AdminController { }
+ * ```
  */
-declare function usePageContext(): RenderContext;
+declare function Layout(layout: LayoutComponent<any>, options?: LayoutDecoratorOptions): ClassDecorator;
 /**
- * Hook to access route parameters.
- *
- * @example
- * ```tsx
- * // Route: /users/:id
- * const params = useParams();
- * console.log(params.id); // '123'
- * ```
+ * Provider component that makes page context available to all child components.
+ * Should wrap the entire app in entry-server and entry-client.
  */
-declare function useParams(): Record<string, string>;
+declare function PageContextProvider({ context, children, }: {
+    context: RenderContext;
+    children: React.ReactNode;
+}): react_jsx_runtime.JSX.Element;
 /**
- * Hook to access query string parameters.
+ * Factory function to create typed SSR hooks bound to your app's context type.
+ * Use this once in your app to create hooks with full type safety.
+ *
+ * This eliminates the need to pass generic types to every hook call,
+ * providing excellent DX with full IntelliSense support.
+ *
+ * @template T - Your extended RenderContext type with app-specific properties
  *
  * @example
- * ```tsx
- * // URL: /search?q=react&sort=date
- * const query = useQuery();
- * console.log(query.q);    // 'react'
- * console.log(query.sort); // 'date'
+ * ```typescript
+ * // src/lib/ssr-hooks.ts - Define once
+ * import { createSSRHooks, RenderContext } from '@nestjs-ssr/react';
+ *
+ * interface AppRenderContext extends RenderContext {
+ *   user?: {
+ *     id: string;
+ *     name: string;
+ *     email: string;
+ *   };
+ *   tenant?: { id: string; name: string };
+ *   featureFlags?: Record<string, boolean>;
+ *   theme?: string; // From cookie
+ * }
+ *
+ * export const {
+ *   usePageContext,
+ *   useParams,
+ *   useQuery,
+ *   useRequest,
+ *   useHeaders,
+ *   useHeader,
+ *   useCookies,
+ *   useCookie,
+ * } = createSSRHooks<AppRenderContext>();
+ *
+ * // Create custom helper hooks
+ * export const useUser = () => usePageContext().user;
+ * export const useTheme = () => useCookie('theme');
+ * export const useUserAgent = () => useHeader('user-agent');
  * ```
- */
-declare function useQuery(): Record<string, string | string[]>;
-/**
- * Hook to access the User-Agent header.
- * Useful for device detection or analytics.
  *
  * @example
- * ```tsx
- * const userAgent = useUserAgent();
- * const isMobile = /Mobile/.test(userAgent || '');
+ * ```typescript
+ * // src/views/home.tsx - Use everywhere with full types
+ * import { usePageContext, useUser, useTheme, useCookie, useHeader } from '@/lib/ssr-hooks';
+ *
+ * export default function Home() {
+ *   const { user, featureFlags } = usePageContext(); // ✅ Fully typed!
+ *   const user = useUser(); // ✅ Also typed!
+ *   const theme = useTheme(); // ✅ From cookie
+ *   const locale = useCookie('locale'); // ✅ Access specific cookie
+ *   const tenantId = useHeader('x-tenant-id'); // ✅ Access specific header
+ *
+ *   return (
+ *     <div>
+ *       <h1>Welcome {user?.name}</h1>
+ *       <p>Theme: {theme}</p>
+ *       <p>Locale: {locale}</p>
+ *       <p>Tenant: {tenantId}</p>
+ *     </div>
+ *   );
+ * }
  * ```
  */
-declare function useUserAgent(): string | undefined;
+declare function createSSRHooks<T extends RenderContext = RenderContext>(): {
+    /**
+     * Hook to access the full page context with your app's type.
+     * Contains URL metadata, headers, and any custom properties you've added.
+     */
+    usePageContext: () => T;
+    /**
+     * Hook to access route parameters.
+     *
+     * @example
+     * ```tsx
+     * // Route: /users/:id
+     * const params = useParams();
+     * console.log(params.id); // '123'
+     * ```
+     */
+    useParams: () => Record<string, string>;
+    /**
+     * Hook to access query string parameters.
+     *
+     * @example
+     * ```tsx
+     * // URL: /search?q=react&sort=date
+     * const query = useQuery();
+     * console.log(query.q);    // 'react'
+     * console.log(query.sort); // 'date'
+     * ```
+     */
+    useQuery: () => Record<string, string | string[]>;
+    /**
+     * Alias for usePageContext() with a more intuitive name.
+     * Returns the full request context with your app's type.
+     *
+     * @example
+     * ```tsx
+     * const request = useRequest();
+     * console.log(request.path);   // '/users/123'
+     * console.log(request.method); // 'GET'
+     * console.log(request.params); // { id: '123' }
+     * console.log(request.query);  // { search: 'foo' }
+     * ```
+     */
+    useRequest: () => T;
+    /**
+     * Hook to access headers configured via allowedHeaders.
+     * Returns all headers as a Record.
+     *
+     * Configure in module registration:
+     * ```typescript
+     * RenderModule.register({
+     *   allowedHeaders: ['user-agent', 'x-tenant-id', 'x-api-version']
+     * })
+     * ```
+     *
+     * @example
+     * ```tsx
+     * const headers = useHeaders();
+     * console.log(headers['user-agent']); // 'Mozilla/5.0...'
+     * console.log(headers['x-tenant-id']); // 'tenant-123'
+     * console.log(headers['x-api-version']); // 'v2'
+     * ```
+     */
+    useHeaders: () => Record<string, string>;
+    /**
+     * Hook to access a specific custom header by name.
+     * Returns undefined if the header is not configured or not present.
+     *
+     * @param name - The header name (as configured in allowedHeaders)
+     *
+     * @example
+     * ```tsx
+     * const tenantId = useHeader('x-tenant-id');
+     * if (tenantId) {
+     *   console.log(`Tenant: ${tenantId}`);
+     * }
+     * ```
+     */
+    useHeader: (name: string) => string | undefined;
+    /**
+     * Hook to access cookies configured via allowedCookies.
+     * Returns all allowed cookies as a Record.
+     *
+     * Configure in module registration:
+     * ```typescript
+     * RenderModule.register({
+     *   allowedCookies: ['theme', 'locale', 'consent']
+     * })
+     * ```
+     *
+     * @example
+     * ```tsx
+     * const cookies = useCookies();
+     * console.log(cookies.theme);  // 'dark'
+     * console.log(cookies.locale); // 'en-US'
+     * ```
+     */
+    useCookies: () => Record<string, string>;
+    /**
+     * Hook to access a specific cookie by name.
+     * Returns undefined if the cookie is not configured or not present.
+     *
+     * @param name - The cookie name (as configured in allowedCookies)
+     *
+     * @example
+     * ```tsx
+     * const theme = useCookie('theme');
+     * if (theme === 'dark') {
+     *   console.log('Dark mode enabled');
+     * }
+     * ```
+     */
+    useCookie: (name: string) => string | undefined;
+};
-export { HeadData, type PageProps, ReactRender, Render, type RenderContext, usePageContext, useParams, useQuery, useUserAgent };
+export { HeadData, Layout, type LayoutComponent, type LayoutDecoratorOptions, type LayoutProps, type PageComponentWithLayout, PageContextProvider, type PageProps, Render, type RenderContext, type RenderOptions, RenderResponse, createSSRHooks };