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

@nestjs-ssr/react 0.2.0 → 0.2.2

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 (26) hide show

package/README.md +1 -1
package/dist/cli/init.js +339 -91
package/dist/cli/init.mjs +341 -93
package/dist/client.d.mts +319 -0
package/dist/client.d.ts +319 -0
package/dist/client.js +207 -0
package/dist/client.mjs +200 -0
package/dist/{index-C5Knql-9.d.mts → index-CaGD266H.d.ts} +2 -104
package/dist/{index-C5Knql-9.d.ts → index-Dq1yt0sX.d.mts} +2 -104
package/dist/index.d.mts +9 -321
package/dist/index.d.ts +9 -321
package/dist/index.js +144 -91
package/dist/index.mjs +115 -63
package/dist/render/index.d.mts +2 -1
package/dist/render/index.d.ts +2 -1
package/dist/render/index.js +134 -81
package/dist/render/index.mjs +115 -63
package/dist/render-response.interface-Dc-Kwb09.d.mts +104 -0
package/dist/render-response.interface-Dc-Kwb09.d.ts +104 -0
package/dist/templates/entry-client.tsx +6 -3
package/dist/templates/entry-server.tsx +33 -2
package/dist/templates/index.html +15 -12
package/package.json +13 -1
package/src/templates/entry-client.tsx +6 -3
package/src/templates/entry-server.tsx +33 -2
package/src/templates/index.html +15 -12

package/dist/client.d.mts ADDED Viewed

@@ -0,0 +1,319 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React from 'react';
+import { H as HeadData } from './render-response.interface-Dc-Kwb09.mjs';
+/**
+ * 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 = {
+ *   url: '/users/123',
+ *   path: '/users/123',
+ *   query: { tab: 'profile' },
+ *   params: { id: '123' },
+ *   method: 'GET',
+ * };
+ *
+ * @example
+ * // Extended usage - add custom properties for your app
+ * interface AppRenderContext extends RenderContext {
+ *   user?: {
+ *     id: string;
+ *     name: string;
+ *     email: string;
+ *     roles: string[];
+ *   };
+ *   tenant?: {
+ *     id: string;
+ *     name: string;
+ *   };
+ *   featureFlags?: Record<string, boolean>;
+ *   theme?: string;  // From cookie
+ * }
+ *
+ * // 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,
+ *   featureFlags: await featureFlagService.getFlags(req),
+ * };
+ */
+interface RenderContext {
+    url: string;
+    path: string;
+    query: Record<string, string | string[]>;
+    params: Record<string, string>;
+    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 } = props;
+ *   const context = usePageContext(); // Fully typed!
+ *
+ *   return (
+ *     <html>
+ *       <head>
+ *         <title>{head?.title || product.name}</title>
+ *       </head>
+ *       <body>
+ *         <h1>{product.name}</h1>
+ *         <p>Current path: {context.path}</p>
+ *       </body>
+ *     </html>
+ *   );
+ * }
+ * ```
+ */
+type PageProps<TProps = {}> = TProps & {
+    /**
+     * Optional head metadata for SEO (title, description, og tags, etc.)
+     * Pass from controller to populate meta tags, Open Graph, etc.
+     *
+     * @example
+     * ```typescript
+     * // In controller:
+     * return {
+     *   product,
+     *   head: {
+     *     title: product.name,
+     *     description: product.description,
+     *   }
+     * };
+     *
+     * // In component:
+     * <head>
+     *   <title>{props.head?.title}</title>
+     *   <meta name="description" content={props.head?.description} />
+     * </head>
+     * ```
+     */
+    head?: HeadData;
+};
+/**
+ * Provider component that makes page context available to all child components.
+ * Should wrap the entire app in entry-server and entry-client.
+ */
+declare function PageContextProvider({ context, children, }: {
+    context: RenderContext;
+    children: React.ReactNode;
+}): react_jsx_runtime.JSX.Element;
+/**
+ * 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
+ * ```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');
+ * ```
+ *
+ * @example
+ * ```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 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 { PageContextProvider, type PageProps, type RenderContext, createSSRHooks };

package/dist/client.d.ts ADDED Viewed

@@ -0,0 +1,319 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React from 'react';
+import { H as HeadData } from './render-response.interface-Dc-Kwb09.js';
+/**
+ * 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 = {
+ *   url: '/users/123',
+ *   path: '/users/123',
+ *   query: { tab: 'profile' },
+ *   params: { id: '123' },
+ *   method: 'GET',
+ * };
+ *
+ * @example
+ * // Extended usage - add custom properties for your app
+ * interface AppRenderContext extends RenderContext {
+ *   user?: {
+ *     id: string;
+ *     name: string;
+ *     email: string;
+ *     roles: string[];
+ *   };
+ *   tenant?: {
+ *     id: string;
+ *     name: string;
+ *   };
+ *   featureFlags?: Record<string, boolean>;
+ *   theme?: string;  // From cookie
+ * }
+ *
+ * // 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,
+ *   featureFlags: await featureFlagService.getFlags(req),
+ * };
+ */
+interface RenderContext {
+    url: string;
+    path: string;
+    query: Record<string, string | string[]>;
+    params: Record<string, string>;
+    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 } = props;
+ *   const context = usePageContext(); // Fully typed!
+ *
+ *   return (
+ *     <html>
+ *       <head>
+ *         <title>{head?.title || product.name}</title>
+ *       </head>
+ *       <body>
+ *         <h1>{product.name}</h1>
+ *         <p>Current path: {context.path}</p>
+ *       </body>
+ *     </html>
+ *   );
+ * }
+ * ```
+ */
+type PageProps<TProps = {}> = TProps & {
+    /**
+     * Optional head metadata for SEO (title, description, og tags, etc.)
+     * Pass from controller to populate meta tags, Open Graph, etc.
+     *
+     * @example
+     * ```typescript
+     * // In controller:
+     * return {
+     *   product,
+     *   head: {
+     *     title: product.name,
+     *     description: product.description,
+     *   }
+     * };
+     *
+     * // In component:
+     * <head>
+     *   <title>{props.head?.title}</title>
+     *   <meta name="description" content={props.head?.description} />
+     * </head>
+     * ```
+     */
+    head?: HeadData;
+};
+/**
+ * Provider component that makes page context available to all child components.
+ * Should wrap the entire app in entry-server and entry-client.
+ */
+declare function PageContextProvider({ context, children, }: {
+    context: RenderContext;
+    children: React.ReactNode;
+}): react_jsx_runtime.JSX.Element;
+/**
+ * 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
+ * ```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');
+ * ```
+ *
+ * @example
+ * ```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 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 { PageContextProvider, type PageProps, type RenderContext, createSSRHooks };