@intrig/plugin-next 0.0.2-2 → 0.0.2-4

package/dist/index.cjs

@@ -8,6 +8,7 @@ var fsx = require('fs-extra');
 var mimeType = require('mime-types');
 var _ = require('lodash');
 var fs = require('fs');
+var chalk = require('chalk');
 
 function _interopNamespaceDefault(e) {
   var n = Object.create(null);
@@ -1650,6 +1651,7 @@ function providerHooksTemplate() {
   useMemo,
   useState,
   useRef,
+  useEffect,
 } from 'react';
 import {
   ErrorState,
@@ -1693,6 +1695,16 @@ export function useNetworkState<T>({
   const context = useContext(Context);
 
   const [abortController, setAbortController] = useState<AbortController>();
+  
+  const contextRef = useRef(context);
+  const schemaRef = useRef(schema);
+  const errorSchemaRef = useRef(errorSchema);
+  
+  useEffect(() => {
+    contextRef.current = context;
+    schemaRef.current = schema;
+    errorSchemaRef.current = errorSchema;
+  });
 
   const networkState = useMemo(() => {
     logger.info(${"`Updating status ${key} ${operation} ${source}`"});
@@ -1701,7 +1713,7 @@ export function useNetworkState<T>({
       (context.state?.[${"`${source}:${operation}:${key}`"}] as NetworkState<T>) ??
       init()
     );
-  }, [JSON.stringify(context.state?.[${"`${source}:${operation}:${key}`"}])]);
+  }, [context.state, key, operation, source]);
 
   const dispatch = useCallback(
     (state: NetworkState<T>) => {
@@ -1749,30 +1761,30 @@ export function useNetworkState<T>({
         signal: abortController.signal,
       };
 
-      await context.execute(
+      await contextRef.current.execute(
         requestConfig,
         dispatch,
-        schema,
-        errorSchema as any,
+        schemaRef.current,
+        errorSchemaRef.current as any,
       );
     },
-    [networkState, context.dispatch],
+    [dispatch, key, operation, source],
   );
 
   const deboundedExecute = useMemo(
-    () => debounce(execute, debounceDelay ?? 0),
-    [execute],
+    () => debounce(execute, debounceDelay),
+    [execute, debounceDelay],
   );
 
   const clear = useCallback(() => {
     logger.info(${"`Clearing request ${key} ${operation} ${source}`"});
     dispatch(init());
-    setAbortController((abortController) => {
+    setAbortController((prev) => {
       logger.info(${"`Aborting request ${key} ${operation} ${source}`"});
-      abortController?.abort();
+      prev?.abort();
       return undefined;
     });
-  }, [dispatch, abortController]);
+  }, [dispatch, key, operation, source]);
 
   return [networkState, deboundedExecute, clear, dispatch];
 }
@@ -1789,6 +1801,14 @@ export function useTransitionCall<T>({
 }): [(request: RequestType) => Promise<T>, () => void] {
   const ctx = useContext(Context);
   const controller = useRef<AbortController | undefined>(undefined);
+  
+  const schemaRef = useRef(schema);
+  const errorSchemaRef = useRef(errorSchema);
+  
+  useEffect(() => {
+    schemaRef.current = schema;
+    errorSchemaRef.current = errorSchema;
+  });
 
   const call = useCallback(
     async (request: RequestType) => {
@@ -1806,12 +1826,12 @@ export function useTransitionCall<T>({
               reject(state.error);
             }
           },
-          schema,
-          errorSchema,
+          schemaRef.current,
+          errorSchemaRef.current,
         );
       });
     },
-    [ctx, schema, errorSchema],
+    [ctx],
   );
 
   const abort = useCallback(() => {
@@ -2447,7 +2467,7 @@ async function requestHookTemplate({ source, data: { paths, operationId, respons
     const modifiedRequestUrl = `${requestUrl == null ? void 0 : requestUrl.replace(/\{/g, "${")}`;
     const imports = new Set();
     imports.add(`import { z } from 'zod'`);
-    imports.add(`import { useCallback, useEffect } from 'react'`);
+    imports.add(`import { useCallback, useEffect, useRef } from 'react'`);
     imports.add(`import {useNetworkState, NetworkState, DispatchState, error, successfulDispatch, validationError, encode, requestValidationError} from "@intrig/react"`);
     const { hookShape, optionsShape } = extractHookShapeAndOptionsShape$1(response, requestBody, imports);
     const { paramExpression, paramType } = extractParamDeconstruction$3(variables != null ? variables : [], requestBody);
@@ -2500,6 +2520,11 @@ async function requestHookTemplate({ source, data: { paths, operationId, respons
         schema,
         errorSchema
       });
+      
+      const optionsRef = useRef(options);
+      useEffect(() => {
+        optionsRef.current = options;
+      });
 
       const doExecute = useCallback<(${paramType}) => DispatchState<any>>((${paramExpression}) => {
         const { ${paramExplode}} = p
@@ -2525,22 +2550,22 @@ async function requestHookTemplate({ source, data: { paths, operationId, respons
             ${responseTypePart()}
           })
           return successfulDispatch();
-      }, [dispatch])
+      }, [dispatch, dispatchState]) 
 
       useEffect(() => {
-        if (options.fetchOnMount) {
+        if (optionsRef.current.fetchOnMount) {
           doExecute(${[
-        requestBody ? `options.body!` : undefined,
-        "options.params!"
+        requestBody ? `optionsRef.current.body!` : undefined,
+        "optionsRef.current.params!"
     ].filter((a)=>a).join(",")});
         }
 
         return () => {
-          if (options.clearOnUnmount) {
+          if (optionsRef.current.clearOnUnmount) {
             clear();
           }
         }
-      }, [])
+      }, [doExecute, clear])
 
       return [
         state,
@@ -2837,7 +2862,7 @@ async function downloadHookTemplate({ source, data: { paths, operationId, respon
     const modifiedRequestUrl = `${requestUrl == null ? void 0 : requestUrl.replace(/\{/g, "${")}`;
     const imports = new Set();
     imports.add(`import { z } from 'zod'`);
-    imports.add(`import { useCallback, useEffect } from 'react'`);
+    imports.add(`import { useCallback, useEffect, useRef } from 'react'`);
     imports.add(`import {useNetworkState, NetworkState, DispatchState, pending, success, error, init, successfulDispatch, validationError, encode, isSuccess, requestValidationError} from "@intrig/react"`);
     const { hookShape, optionsShape } = extractHookShapeAndOptionsShape(response, requestBody, imports);
     const { paramExpression, paramType } = extractParamDeconstruction$1(variables, requestBody);
@@ -2883,7 +2908,7 @@ async function downloadHookTemplate({ source, data: { paths, operationId, respon
     const source = "${source}"
 
     function use${pluginSdk.pascalCase(operationId)}Hook(options: ${optionsShape} = {}): [NetworkState<Response>, (${paramType}) => DispatchState<any>, () => void] {
-      let [state, dispatch, clear, dispatchState] = useNetworkState<Response>({
+      const [state, dispatch, clear, dispatchState] = useNetworkState<Response>({
         key: options?.key ?? 'default',
         operation,
         source,
@@ -2891,6 +2916,11 @@ async function downloadHookTemplate({ source, data: { paths, operationId, respon
         errorSchema
       });
       
+      const optionsRef = useRef(options);
+      useEffect(() => {
+        optionsRef.current = options;
+      });
+      
       useEffect(() => {
         if (isSuccess(state)) {
           let a = document.createElement('a');
@@ -2923,10 +2953,10 @@ async function downloadHookTemplate({ source, data: { paths, operationId, respon
           document.body.removeChild(a);
           dispatchState(init())
         }
-      }, [state])
+      }, [state, dispatchState])
 
-      let doExecute = useCallback<(${paramType}) => DispatchState<any>>((${paramExpression}) => {
-        let { ${paramExplode}} = p
+      const doExecute = useCallback<(${paramType}) => DispatchState<any>>((${paramExpression}) => {
+        const { ${paramExplode}} = p
 
           ${requestBody ? `
           const validationResult = requestBodySchema.safeParse(data);
@@ -2949,22 +2979,22 @@ async function downloadHookTemplate({ source, data: { paths, operationId, respon
             ${responseTypePart()}
           })
           return successfulDispatch();
-      }, [dispatch])
+      }, [dispatch, dispatchState]) 
       
       useEffect(() => {
-        if (options.fetchOnMount) {
+        if (optionsRef.current.fetchOnMount) {
           doExecute(${[
-        requestBody ? `options.body!` : undefined,
-        "options.params!"
+        requestBody ? `optionsRef.current.body!` : undefined,
+        "optionsRef.current.params!"
     ].filter((a)=>a).join(",")});
         }
 
         return () => {
-          if (options.clearOnUnmount) {
+          if (optionsRef.current.clearOnUnmount) {
             clear();
           }
         }
-      }, [])
+      }, [doExecute, clear])  // Added proper dependencies
 
       return [
         state,
@@ -3581,6 +3611,217 @@ function handleComplexSchema(schema, imports) {
     };
 }
 
+function serverFunctionDocs(descriptor) {
+    const md = pluginSdk.mdLiteral('server-function.md');
+    var _descriptor_data_variables;
+    // ===== Derived names (preserve these) =====
+    const hasPathParams = ((_descriptor_data_variables = descriptor.data.variables) != null ? _descriptor_data_variables : []).some((v)=>{
+        var _v_in;
+        return ((_v_in = v.in) == null ? void 0 : _v_in.toUpperCase()) === 'PATH';
+    });
+    const actionName = pluginSdk.camelCase(descriptor.name) // e.g. getUser
+    ;
+    const executeActionName = `execute${pluginSdk.pascalCase(descriptor.name)}` // e.g. executeGetUser
+    ;
+    const requestBodyVar = descriptor.data.requestBody ? pluginSdk.camelCase(descriptor.data.requestBody) // e.g. createUser
+     : undefined;
+    const requestBodyType = descriptor.data.requestBody ? pluginSdk.pascalCase(descriptor.data.requestBody) // e.g. CreateUser
+     : undefined;
+    const paramsVar = hasPathParams ? `${actionName}Params` : undefined // e.g. getUserParams
+    ;
+    const paramsType = hasPathParams ? `${pluginSdk.pascalCase(descriptor.name)}Params` : undefined // e.g. GetUserParams
+    ;
+    const responseTypeName = `${pluginSdk.pascalCase(descriptor.name)}Response` // e.g. GetUserResponse
+    ;
+    const callArgs = [
+        requestBodyVar,
+        paramsVar
+    ].filter(Boolean).join(', ');
+    return md`
+# Server-Side Functions — Quick Guide
+
+## Copy-paste starter (fast lane)
+
+### 1) Function import (in your Next.js API route or server component)
+${"```ts"}
+import { ${actionName}, ${executeActionName} } from '@intrig/react/${descriptor.path}/server';
+${"```"}
+
+### 2) Use the async function
+${"```ts"}
+// Simple usage - returns parsed response
+const result = await ${actionName}(${callArgs});
+
+// Advanced usage - returns raw data + headers
+const { data, headers } = await ${executeActionName}(${callArgs});
+${"```"}
+
+Server-side functions are for **Next.js API routes** and **server components**. They return **awaitable promises** that directly call your backend API.
+
+---
+
+## TL;DR (copy–paste examples)
+
+### In API Route (\`pages/api\` or \`app/api\`)
+${"```ts"}
+// pages/api/example.ts or app/api/example/route.ts
+import { ${actionName} } from '@intrig/react/${descriptor.path}/server';
+import type { NextApiRequest, NextApiResponse } from 'next';
+
+export default async function handler(req: NextApiRequest, res: NextApiResponse) {
+  try {
+    const result = await ${actionName}(${callArgs});
+    res.status(200).json(result);
+  } catch (error) {
+    console.error('API call failed:', error);
+    res.status(500).json({ error: 'Internal server error' });
+  }
+}
+${"```"}
+
+### In Server Component (App Router)
+${"```tsx"}
+// app/example/page.tsx
+import { ${actionName} } from '@intrig/react/${descriptor.path}/server';
+
+export default async function ExamplePage() {
+  try {
+    const data = await ${actionName}(${callArgs});
+    
+    return (
+      <div>
+        <h1>Server Data</h1>
+        <pre>{JSON.stringify(data, null, 2)}</pre>
+      </div>
+    );
+  } catch (error) {
+    return <div>Error loading data: {error.message}</div>;
+  }
+}
+${"```"}
+
+### In Server Action (App Router)
+${"```ts"}
+// app/actions.ts
+'use server';
+
+import { ${actionName} } from '@intrig/react/${descriptor.path}/server';
+
+export async function serverAction(formData: FormData) {
+  try {
+    const result = await ${actionName}(${callArgs});
+    // Process result...
+    return { success: true, data: result };
+  } catch (error) {
+    return { success: false, error: error.message };
+  }
+}
+${"```"}
+
+${requestBodyType || paramsType ? `### Optional types (if generated by your build)
+${"```ts"}
+${requestBodyType ? `import type { ${requestBodyType} } from '@intrig/react/${descriptor.source}/components/schemas/${requestBodyType}';
+` : ''}${paramsType ? `import type { ${paramsType} } from '@intrig/react/${descriptor.path}/${pluginSdk.pascalCase(descriptor.name)}.params';
+` : ''}import type { ${responseTypeName} } from '@intrig/react/${descriptor.path}/${pluginSdk.pascalCase(descriptor.name)}.response';
+${"```"}
+` : ''}
+
+---
+
+## Function API
+
+${"```ts"}
+// Prefer concrete types if your build emits them:
+// import type { ${responseTypeName} } from '@intrig/react/${descriptor.path}/${pluginSdk.pascalCase(descriptor.name)}.response';
+// ${paramsType ? `import type { ${paramsType} } from '@intrig/react/${descriptor.path}/${pluginSdk.pascalCase(descriptor.name)}.params';` : ''}
+
+type ${pluginSdk.pascalCase(descriptor.name)}Data = ${'unknown'}; // replace with ${responseTypeName} if generated
+type ${pluginSdk.pascalCase(descriptor.name)}Request = {
+  body?: ${requestBodyType != null ? requestBodyType : 'unknown'};
+  params?: ${paramsType != null ? paramsType : 'unknown'};
+};
+
+// Main function - returns parsed response
+declare function ${actionName}(
+  ${requestBodyVar ? `body: ${pluginSdk.pascalCase(descriptor.name)}Request['body'], ` : ''}${paramsVar ? `params: ${pluginSdk.pascalCase(descriptor.name)}Request['params'], ` : ''}options?: AsyncRequestOptions
+): Promise<${pluginSdk.pascalCase(descriptor.name)}Data>;
+
+// Advanced function - returns raw data + headers
+declare function ${executeActionName}(
+  ${requestBodyVar ? `body: ${pluginSdk.pascalCase(descriptor.name)}Request['body'], ` : ''}${paramsVar ? `params: ${pluginSdk.pascalCase(descriptor.name)}Request['params'], ` : ''}options?: AsyncRequestOptions
+): Promise<{ data: any, headers: any }>;
+${"```"}
+
+### Why server-side functions?
+- **Server-only execution:** Perfect for Next.js API routes and server components.
+- **Direct API calls:** No client-side state management needed.
+- **SSR/SSG friendly:** Use in \`getServerSideProps\`, \`getStaticProps\`, or server components.
+- **Built-in error handling:** Automatic network and validation error handling.
+
+### Options
+Both functions accept an optional \`options\` parameter:
+
+${"```ts"}
+type AsyncRequestOptions = {
+  hydrate?: boolean;  // Cache response for client-side hydration
+  key?: string;      // Custom cache key (when hydrate is true)
+};
+${"```"}
+
+### Error Handling
+Server-side functions throw errors for:
+- **Network errors:** Connection issues, HTTP error status codes
+- **Validation errors:** Response doesn't match expected schema
+- **Request errors:** Invalid request body or parameters
+
+Always wrap calls in try-catch blocks for production use.
+
+---
+
+## Next.js Integration Patterns
+
+### 1. API Routes (Pages Router)
+Use server functions in your API routes to proxy requests or process data server-side.
+
+### 2. Server Components (App Router)
+Directly call server functions in your server components for SSR data fetching.
+
+### 3. Server Actions (App Router)
+Use server functions within server actions for form submissions and mutations.
+
+### 4. Middleware
+Server functions can be used in Next.js middleware for request preprocessing.
+
+### 5. getServerSideProps / getStaticProps (Pages Router)
+Perfect for data fetching in traditional Next.js data fetching methods.
+
+---
+
+## Best Practices
+
+1. **Error boundaries:** Always handle errors appropriately for your use case
+2. **Caching:** Use the \`hydrate\` option for data that should be available client-side
+3. **Types:** Import and use the generated TypeScript types for better DX
+4. **Logging:** Server functions include built-in logging for debugging
+
+${"```ts"}
+// Example with proper error handling and types
+import { ${actionName} } from '@intrig/react/${descriptor.path}/server';
+${paramsType ? `import type { ${paramsType} } from '@intrig/react/${descriptor.path}/${pluginSdk.pascalCase(descriptor.name)}.params';` : ''}
+import type { ${responseTypeName} } from '@intrig/react/${descriptor.path}/${pluginSdk.pascalCase(descriptor.name)}.response';
+
+export async function fetchData(${paramsVar ? `params: ${paramsType}` : ''}): Promise<${responseTypeName} | null> {
+  try {
+    return await ${actionName}(${callArgs});
+  } catch (error) {
+    console.error('Failed to fetch data:', error);
+    return null;
+  }
+}
+${"```"}
+`;
+}
+
 async function generateCode(ctx) {
     // Root/project files
     await ctx.dump(packageJsonTemplate(ctx));
@@ -3614,6 +3855,7 @@ async function generateCode(ctx) {
         await ctx.dump(paramsTemplate(restDescriptor));
         await ctx.dump(asyncFunctionHookTemplate(restDescriptor, internalGeneratorContext));
         await ctx.dump(nextRequestMethodTemplate(restDescriptor, internalGeneratorContext));
+        await ctx.dump(serverFunctionDocs(restDescriptor));
         if (restDescriptor.data.isDownloadable) {
             await ctx.dump(downloadHookTemplate(restDescriptor, internalGeneratorContext));
         }
@@ -3659,12 +3901,12 @@ Use this TypeScript type anywhere you need static typing for this object shape i
 
 ## Import
 ${'```ts'}
-${importContent}
+${importContent.content}
 ${'```'}
 
 ## Definition
 ${'```ts'}
-${codeContent}
+${codeContent.content}
 ${'```'}
   `;
 }
@@ -3686,12 +3928,12 @@ Use this JSON Schema with tools that consume JSON Schema: UI form builders (e.g.
 
 ## Import
 ${'```ts'}
-${importContent}
+${importContent.content}
 ${'```'}
 
 ## Definition
 ${'```ts'}
-${codeContent}
+${codeContent.content}
 ${'```'}
   `;
 }
@@ -3713,12 +3955,12 @@ Use this Zod schema for runtime validation and parsing: form validation, client/
 
 ## Import
 ${'```ts'}
-${importContent}
+${importContent.content}
 ${'```'}
 
 ## Definition
 ${'```ts'}
-${codeContent}
+${codeContent.content}
 ${'```'}
   `;
 }
@@ -4738,6 +4980,14 @@ async function initPlugin(ctx) {
     const apiRoutesDir = (options == null ? void 0 : options.apiRoutesDir) || 'src/app/api';
     // Add the directory with (generated) to gitignore
     updateGitIgnore(rootDir, `${apiRoutesDir}/(generated)`);
+    return {
+        postInit: ()=>{
+            console.log(chalk.blue('\n📋 Next Steps:'));
+            console.log(chalk.white('To complete your Next.js setup, please refer to the post-initialization instructions at:'));
+            console.log(chalk.cyan('https://intrig.dev/docs/next/initialization#3-post-initialization-steps'));
+            console.log(chalk.gray('\nThis guide will show you how to add IntrigProvider to your Next.js application.\n'));
+        }
+    };
 }
 
 async function postBuild(ctx) {

package/dist/index.js

@@ -5,6 +5,7 @@ import * as fsx from 'fs-extra';
 import * as mimeType from 'mime-types';
 import * as _ from 'lodash';
 import * as fs from 'fs';
+import chalk from 'chalk';
 
 class InternalGeneratorContext {
     getCounter(sourceId) {
@@ -1624,6 +1625,7 @@ function providerHooksTemplate() {
   useMemo,
   useState,
   useRef,
+  useEffect,
 } from 'react';
 import {
   ErrorState,
@@ -1667,6 +1669,16 @@ export function useNetworkState<T>({
   const context = useContext(Context);
 
   const [abortController, setAbortController] = useState<AbortController>();
+  
+  const contextRef = useRef(context);
+  const schemaRef = useRef(schema);
+  const errorSchemaRef = useRef(errorSchema);
+  
+  useEffect(() => {
+    contextRef.current = context;
+    schemaRef.current = schema;
+    errorSchemaRef.current = errorSchema;
+  });
 
   const networkState = useMemo(() => {
     logger.info(${"`Updating status ${key} ${operation} ${source}`"});
@@ -1675,7 +1687,7 @@ export function useNetworkState<T>({
       (context.state?.[${"`${source}:${operation}:${key}`"}] as NetworkState<T>) ??
       init()
     );
-  }, [JSON.stringify(context.state?.[${"`${source}:${operation}:${key}`"}])]);
+  }, [context.state, key, operation, source]);
 
   const dispatch = useCallback(
     (state: NetworkState<T>) => {
@@ -1723,30 +1735,30 @@ export function useNetworkState<T>({
         signal: abortController.signal,
       };
 
-      await context.execute(
+      await contextRef.current.execute(
         requestConfig,
         dispatch,
-        schema,
-        errorSchema as any,
+        schemaRef.current,
+        errorSchemaRef.current as any,
       );
     },
-    [networkState, context.dispatch],
+    [dispatch, key, operation, source],
   );
 
   const deboundedExecute = useMemo(
-    () => debounce(execute, debounceDelay ?? 0),
-    [execute],
+    () => debounce(execute, debounceDelay),
+    [execute, debounceDelay],
   );
 
   const clear = useCallback(() => {
     logger.info(${"`Clearing request ${key} ${operation} ${source}`"});
     dispatch(init());
-    setAbortController((abortController) => {
+    setAbortController((prev) => {
       logger.info(${"`Aborting request ${key} ${operation} ${source}`"});
-      abortController?.abort();
+      prev?.abort();
       return undefined;
     });
-  }, [dispatch, abortController]);
+  }, [dispatch, key, operation, source]);
 
   return [networkState, deboundedExecute, clear, dispatch];
 }
@@ -1763,6 +1775,14 @@ export function useTransitionCall<T>({
 }): [(request: RequestType) => Promise<T>, () => void] {
   const ctx = useContext(Context);
   const controller = useRef<AbortController | undefined>(undefined);
+  
+  const schemaRef = useRef(schema);
+  const errorSchemaRef = useRef(errorSchema);
+  
+  useEffect(() => {
+    schemaRef.current = schema;
+    errorSchemaRef.current = errorSchema;
+  });
 
   const call = useCallback(
     async (request: RequestType) => {
@@ -1780,12 +1800,12 @@ export function useTransitionCall<T>({
               reject(state.error);
             }
           },
-          schema,
-          errorSchema,
+          schemaRef.current,
+          errorSchemaRef.current,
         );
       });
     },
-    [ctx, schema, errorSchema],
+    [ctx],
   );
 
   const abort = useCallback(() => {
@@ -2421,7 +2441,7 @@ async function requestHookTemplate({ source, data: { paths, operationId, respons
     const modifiedRequestUrl = `${requestUrl == null ? void 0 : requestUrl.replace(/\{/g, "${")}`;
     const imports = new Set();
     imports.add(`import { z } from 'zod'`);
-    imports.add(`import { useCallback, useEffect } from 'react'`);
+    imports.add(`import { useCallback, useEffect, useRef } from 'react'`);
     imports.add(`import {useNetworkState, NetworkState, DispatchState, error, successfulDispatch, validationError, encode, requestValidationError} from "@intrig/react"`);
     const { hookShape, optionsShape } = extractHookShapeAndOptionsShape$1(response, requestBody, imports);
     const { paramExpression, paramType } = extractParamDeconstruction$3(variables != null ? variables : [], requestBody);
@@ -2474,6 +2494,11 @@ async function requestHookTemplate({ source, data: { paths, operationId, respons
         schema,
         errorSchema
       });
+      
+      const optionsRef = useRef(options);
+      useEffect(() => {
+        optionsRef.current = options;
+      });
 
       const doExecute = useCallback<(${paramType}) => DispatchState<any>>((${paramExpression}) => {
         const { ${paramExplode}} = p
@@ -2499,22 +2524,22 @@ async function requestHookTemplate({ source, data: { paths, operationId, respons
             ${responseTypePart()}
           })
           return successfulDispatch();
-      }, [dispatch])
+      }, [dispatch, dispatchState]) 
 
       useEffect(() => {
-        if (options.fetchOnMount) {
+        if (optionsRef.current.fetchOnMount) {
           doExecute(${[
-        requestBody ? `options.body!` : undefined,
-        "options.params!"
+        requestBody ? `optionsRef.current.body!` : undefined,
+        "optionsRef.current.params!"
     ].filter((a)=>a).join(",")});
         }
 
         return () => {
-          if (options.clearOnUnmount) {
+          if (optionsRef.current.clearOnUnmount) {
             clear();
           }
         }
-      }, [])
+      }, [doExecute, clear])
 
       return [
         state,
@@ -2811,7 +2836,7 @@ async function downloadHookTemplate({ source, data: { paths, operationId, respon
     const modifiedRequestUrl = `${requestUrl == null ? void 0 : requestUrl.replace(/\{/g, "${")}`;
     const imports = new Set();
     imports.add(`import { z } from 'zod'`);
-    imports.add(`import { useCallback, useEffect } from 'react'`);
+    imports.add(`import { useCallback, useEffect, useRef } from 'react'`);
     imports.add(`import {useNetworkState, NetworkState, DispatchState, pending, success, error, init, successfulDispatch, validationError, encode, isSuccess, requestValidationError} from "@intrig/react"`);
     const { hookShape, optionsShape } = extractHookShapeAndOptionsShape(response, requestBody, imports);
     const { paramExpression, paramType } = extractParamDeconstruction$1(variables, requestBody);
@@ -2857,7 +2882,7 @@ async function downloadHookTemplate({ source, data: { paths, operationId, respon
     const source = "${source}"
 
     function use${pascalCase(operationId)}Hook(options: ${optionsShape} = {}): [NetworkState<Response>, (${paramType}) => DispatchState<any>, () => void] {
-      let [state, dispatch, clear, dispatchState] = useNetworkState<Response>({
+      const [state, dispatch, clear, dispatchState] = useNetworkState<Response>({
         key: options?.key ?? 'default',
         operation,
         source,
@@ -2865,6 +2890,11 @@ async function downloadHookTemplate({ source, data: { paths, operationId, respon
         errorSchema
       });
       
+      const optionsRef = useRef(options);
+      useEffect(() => {
+        optionsRef.current = options;
+      });
+      
       useEffect(() => {
         if (isSuccess(state)) {
           let a = document.createElement('a');
@@ -2897,10 +2927,10 @@ async function downloadHookTemplate({ source, data: { paths, operationId, respon
           document.body.removeChild(a);
           dispatchState(init())
         }
-      }, [state])
+      }, [state, dispatchState])
 
-      let doExecute = useCallback<(${paramType}) => DispatchState<any>>((${paramExpression}) => {
-        let { ${paramExplode}} = p
+      const doExecute = useCallback<(${paramType}) => DispatchState<any>>((${paramExpression}) => {
+        const { ${paramExplode}} = p
 
           ${requestBody ? `
           const validationResult = requestBodySchema.safeParse(data);
@@ -2923,22 +2953,22 @@ async function downloadHookTemplate({ source, data: { paths, operationId, respon
             ${responseTypePart()}
           })
           return successfulDispatch();
-      }, [dispatch])
+      }, [dispatch, dispatchState]) 
       
       useEffect(() => {
-        if (options.fetchOnMount) {
+        if (optionsRef.current.fetchOnMount) {
           doExecute(${[
-        requestBody ? `options.body!` : undefined,
-        "options.params!"
+        requestBody ? `optionsRef.current.body!` : undefined,
+        "optionsRef.current.params!"
     ].filter((a)=>a).join(",")});
         }
 
         return () => {
-          if (options.clearOnUnmount) {
+          if (optionsRef.current.clearOnUnmount) {
             clear();
           }
         }
-      }, [])
+      }, [doExecute, clear])  // Added proper dependencies
 
       return [
         state,
@@ -3555,6 +3585,217 @@ function handleComplexSchema(schema, imports) {
     };
 }
 
+function serverFunctionDocs(descriptor) {
+    const md = mdLiteral('server-function.md');
+    var _descriptor_data_variables;
+    // ===== Derived names (preserve these) =====
+    const hasPathParams = ((_descriptor_data_variables = descriptor.data.variables) != null ? _descriptor_data_variables : []).some((v)=>{
+        var _v_in;
+        return ((_v_in = v.in) == null ? void 0 : _v_in.toUpperCase()) === 'PATH';
+    });
+    const actionName = camelCase(descriptor.name) // e.g. getUser
+    ;
+    const executeActionName = `execute${pascalCase(descriptor.name)}` // e.g. executeGetUser
+    ;
+    const requestBodyVar = descriptor.data.requestBody ? camelCase(descriptor.data.requestBody) // e.g. createUser
+     : undefined;
+    const requestBodyType = descriptor.data.requestBody ? pascalCase(descriptor.data.requestBody) // e.g. CreateUser
+     : undefined;
+    const paramsVar = hasPathParams ? `${actionName}Params` : undefined // e.g. getUserParams
+    ;
+    const paramsType = hasPathParams ? `${pascalCase(descriptor.name)}Params` : undefined // e.g. GetUserParams
+    ;
+    const responseTypeName = `${pascalCase(descriptor.name)}Response` // e.g. GetUserResponse
+    ;
+    const callArgs = [
+        requestBodyVar,
+        paramsVar
+    ].filter(Boolean).join(', ');
+    return md`
+# Server-Side Functions — Quick Guide
+
+## Copy-paste starter (fast lane)
+
+### 1) Function import (in your Next.js API route or server component)
+${"```ts"}
+import { ${actionName}, ${executeActionName} } from '@intrig/react/${descriptor.path}/server';
+${"```"}
+
+### 2) Use the async function
+${"```ts"}
+// Simple usage - returns parsed response
+const result = await ${actionName}(${callArgs});
+
+// Advanced usage - returns raw data + headers
+const { data, headers } = await ${executeActionName}(${callArgs});
+${"```"}
+
+Server-side functions are for **Next.js API routes** and **server components**. They return **awaitable promises** that directly call your backend API.
+
+---
+
+## TL;DR (copy–paste examples)
+
+### In API Route (\`pages/api\` or \`app/api\`)
+${"```ts"}
+// pages/api/example.ts or app/api/example/route.ts
+import { ${actionName} } from '@intrig/react/${descriptor.path}/server';
+import type { NextApiRequest, NextApiResponse } from 'next';
+
+export default async function handler(req: NextApiRequest, res: NextApiResponse) {
+  try {
+    const result = await ${actionName}(${callArgs});
+    res.status(200).json(result);
+  } catch (error) {
+    console.error('API call failed:', error);
+    res.status(500).json({ error: 'Internal server error' });
+  }
+}
+${"```"}
+
+### In Server Component (App Router)
+${"```tsx"}
+// app/example/page.tsx
+import { ${actionName} } from '@intrig/react/${descriptor.path}/server';
+
+export default async function ExamplePage() {
+  try {
+    const data = await ${actionName}(${callArgs});
+    
+    return (
+      <div>
+        <h1>Server Data</h1>
+        <pre>{JSON.stringify(data, null, 2)}</pre>
+      </div>
+    );
+  } catch (error) {
+    return <div>Error loading data: {error.message}</div>;
+  }
+}
+${"```"}
+
+### In Server Action (App Router)
+${"```ts"}
+// app/actions.ts
+'use server';
+
+import { ${actionName} } from '@intrig/react/${descriptor.path}/server';
+
+export async function serverAction(formData: FormData) {
+  try {
+    const result = await ${actionName}(${callArgs});
+    // Process result...
+    return { success: true, data: result };
+  } catch (error) {
+    return { success: false, error: error.message };
+  }
+}
+${"```"}
+
+${requestBodyType || paramsType ? `### Optional types (if generated by your build)
+${"```ts"}
+${requestBodyType ? `import type { ${requestBodyType} } from '@intrig/react/${descriptor.source}/components/schemas/${requestBodyType}';
+` : ''}${paramsType ? `import type { ${paramsType} } from '@intrig/react/${descriptor.path}/${pascalCase(descriptor.name)}.params';
+` : ''}import type { ${responseTypeName} } from '@intrig/react/${descriptor.path}/${pascalCase(descriptor.name)}.response';
+${"```"}
+` : ''}
+
+---
+
+## Function API
+
+${"```ts"}
+// Prefer concrete types if your build emits them:
+// import type { ${responseTypeName} } from '@intrig/react/${descriptor.path}/${pascalCase(descriptor.name)}.response';
+// ${paramsType ? `import type { ${paramsType} } from '@intrig/react/${descriptor.path}/${pascalCase(descriptor.name)}.params';` : ''}
+
+type ${pascalCase(descriptor.name)}Data = ${'unknown'}; // replace with ${responseTypeName} if generated
+type ${pascalCase(descriptor.name)}Request = {
+  body?: ${requestBodyType != null ? requestBodyType : 'unknown'};
+  params?: ${paramsType != null ? paramsType : 'unknown'};
+};
+
+// Main function - returns parsed response
+declare function ${actionName}(
+  ${requestBodyVar ? `body: ${pascalCase(descriptor.name)}Request['body'], ` : ''}${paramsVar ? `params: ${pascalCase(descriptor.name)}Request['params'], ` : ''}options?: AsyncRequestOptions
+): Promise<${pascalCase(descriptor.name)}Data>;
+
+// Advanced function - returns raw data + headers
+declare function ${executeActionName}(
+  ${requestBodyVar ? `body: ${pascalCase(descriptor.name)}Request['body'], ` : ''}${paramsVar ? `params: ${pascalCase(descriptor.name)}Request['params'], ` : ''}options?: AsyncRequestOptions
+): Promise<{ data: any, headers: any }>;
+${"```"}
+
+### Why server-side functions?
+- **Server-only execution:** Perfect for Next.js API routes and server components.
+- **Direct API calls:** No client-side state management needed.
+- **SSR/SSG friendly:** Use in \`getServerSideProps\`, \`getStaticProps\`, or server components.
+- **Built-in error handling:** Automatic network and validation error handling.
+
+### Options
+Both functions accept an optional \`options\` parameter:
+
+${"```ts"}
+type AsyncRequestOptions = {
+  hydrate?: boolean;  // Cache response for client-side hydration
+  key?: string;      // Custom cache key (when hydrate is true)
+};
+${"```"}
+
+### Error Handling
+Server-side functions throw errors for:
+- **Network errors:** Connection issues, HTTP error status codes
+- **Validation errors:** Response doesn't match expected schema
+- **Request errors:** Invalid request body or parameters
+
+Always wrap calls in try-catch blocks for production use.
+
+---
+
+## Next.js Integration Patterns
+
+### 1. API Routes (Pages Router)
+Use server functions in your API routes to proxy requests or process data server-side.
+
+### 2. Server Components (App Router)
+Directly call server functions in your server components for SSR data fetching.
+
+### 3. Server Actions (App Router)
+Use server functions within server actions for form submissions and mutations.
+
+### 4. Middleware
+Server functions can be used in Next.js middleware for request preprocessing.
+
+### 5. getServerSideProps / getStaticProps (Pages Router)
+Perfect for data fetching in traditional Next.js data fetching methods.
+
+---
+
+## Best Practices
+
+1. **Error boundaries:** Always handle errors appropriately for your use case
+2. **Caching:** Use the \`hydrate\` option for data that should be available client-side
+3. **Types:** Import and use the generated TypeScript types for better DX
+4. **Logging:** Server functions include built-in logging for debugging
+
+${"```ts"}
+// Example with proper error handling and types
+import { ${actionName} } from '@intrig/react/${descriptor.path}/server';
+${paramsType ? `import type { ${paramsType} } from '@intrig/react/${descriptor.path}/${pascalCase(descriptor.name)}.params';` : ''}
+import type { ${responseTypeName} } from '@intrig/react/${descriptor.path}/${pascalCase(descriptor.name)}.response';
+
+export async function fetchData(${paramsVar ? `params: ${paramsType}` : ''}): Promise<${responseTypeName} | null> {
+  try {
+    return await ${actionName}(${callArgs});
+  } catch (error) {
+    console.error('Failed to fetch data:', error);
+    return null;
+  }
+}
+${"```"}
+`;
+}
+
 async function generateCode(ctx) {
     // Root/project files
     await ctx.dump(packageJsonTemplate(ctx));
@@ -3588,6 +3829,7 @@ async function generateCode(ctx) {
         await ctx.dump(paramsTemplate(restDescriptor));
         await ctx.dump(asyncFunctionHookTemplate(restDescriptor, internalGeneratorContext));
         await ctx.dump(nextRequestMethodTemplate(restDescriptor, internalGeneratorContext));
+        await ctx.dump(serverFunctionDocs(restDescriptor));
         if (restDescriptor.data.isDownloadable) {
             await ctx.dump(downloadHookTemplate(restDescriptor, internalGeneratorContext));
         }
@@ -3633,12 +3875,12 @@ Use this TypeScript type anywhere you need static typing for this object shape i
 
 ## Import
 ${'```ts'}
-${importContent}
+${importContent.content}
 ${'```'}
 
 ## Definition
 ${'```ts'}
-${codeContent}
+${codeContent.content}
 ${'```'}
   `;
 }
@@ -3660,12 +3902,12 @@ Use this JSON Schema with tools that consume JSON Schema: UI form builders (e.g.
 
 ## Import
 ${'```ts'}
-${importContent}
+${importContent.content}
 ${'```'}
 
 ## Definition
 ${'```ts'}
-${codeContent}
+${codeContent.content}
 ${'```'}
   `;
 }
@@ -3687,12 +3929,12 @@ Use this Zod schema for runtime validation and parsing: form validation, client/
 
 ## Import
 ${'```ts'}
-${importContent}
+${importContent.content}
 ${'```'}
 
 ## Definition
 ${'```ts'}
-${codeContent}
+${codeContent.content}
 ${'```'}
   `;
 }
@@ -4712,6 +4954,14 @@ async function initPlugin(ctx) {
     const apiRoutesDir = (options == null ? void 0 : options.apiRoutesDir) || 'src/app/api';
     // Add the directory with (generated) to gitignore
     updateGitIgnore(rootDir, `${apiRoutesDir}/(generated)`);
+    return {
+        postInit: ()=>{
+            console.log(chalk.blue('\n📋 Next Steps:'));
+            console.log(chalk.white('To complete your Next.js setup, please refer to the post-initialization instructions at:'));
+            console.log(chalk.cyan('https://intrig.dev/docs/next/initialization#3-post-initialization-steps'));
+            console.log(chalk.gray('\nThis guide will show you how to add IntrigProvider to your Next.js application.\n'));
+        }
+    };
 }
 
 async function postBuild(ctx) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intrig/plugin-next",
-  "version": "0.0.2-2",
+  "version": "0.0.2-4",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -15,7 +15,7 @@
     }
   },
   "dependencies": {
-    "@intrig/plugin-sdk": "^0.0.2-5",
+    "@intrig/plugin-sdk": "^0.0.2-7",
     "@swc/helpers": "~0.5.11"
   },
   "files": [