@constructive-io/graphql-codegen 2.20.1 → 2.21.0

package/esm/__tests__/codegen/react-query-optional.test.js

@@ -0,0 +1,290 @@
+/**
+ * Tests for React Query optional flag in code generators
+ *
+ * Verifies that when reactQueryEnabled is false:
+ * - Query generators skip React Query imports and hooks
+ * - Mutation generators return null (since they require React Query)
+ * - Standalone fetch functions are still generated for queries
+ */
+import { generateListQueryHook, generateSingleQueryHook, generateAllQueryHooks } from '../../cli/codegen/queries';
+import { generateCreateMutationHook, generateUpdateMutationHook, generateDeleteMutationHook, generateAllMutationHooks } from '../../cli/codegen/mutations';
+import { generateCustomQueryHook, generateAllCustomQueryHooks } from '../../cli/codegen/custom-queries';
+import { generateCustomMutationHook, generateAllCustomMutationHooks } from '../../cli/codegen/custom-mutations';
+// ============================================================================
+// Test Fixtures
+// ============================================================================
+const fieldTypes = {
+    uuid: { gqlType: 'UUID', isArray: false },
+    string: { gqlType: 'String', isArray: false },
+    int: { gqlType: 'Int', isArray: false },
+    datetime: { gqlType: 'Datetime', isArray: false },
+};
+const emptyRelations = {
+    belongsTo: [],
+    hasOne: [],
+    hasMany: [],
+    manyToMany: [],
+};
+function createTable(partial) {
+    return {
+        name: partial.name,
+        fields: partial.fields ?? [],
+        relations: partial.relations ?? emptyRelations,
+        query: partial.query,
+        inflection: partial.inflection,
+        constraints: partial.constraints,
+    };
+}
+const userTable = createTable({
+    name: 'User',
+    fields: [
+        { name: 'id', type: fieldTypes.uuid },
+        { name: 'email', type: fieldTypes.string },
+        { name: 'name', type: fieldTypes.string },
+        { name: 'createdAt', type: fieldTypes.datetime },
+    ],
+    query: {
+        all: 'users',
+        one: 'user',
+        create: 'createUser',
+        update: 'updateUser',
+        delete: 'deleteUser',
+    },
+});
+function createTypeRef(kind, name, ofType) {
+    return { kind, name, ofType };
+}
+const sampleQueryOperation = {
+    name: 'currentUser',
+    kind: 'query',
+    args: [],
+    returnType: createTypeRef('OBJECT', 'User'),
+    description: 'Get the current authenticated user',
+};
+const sampleMutationOperation = {
+    name: 'login',
+    kind: 'mutation',
+    args: [
+        { name: 'email', type: createTypeRef('NON_NULL', null, createTypeRef('SCALAR', 'String')) },
+        { name: 'password', type: createTypeRef('NON_NULL', null, createTypeRef('SCALAR', 'String')) },
+    ],
+    returnType: createTypeRef('OBJECT', 'LoginPayload'),
+    description: 'Authenticate user',
+};
+const emptyTypeRegistry = new Map();
+// ============================================================================
+// Tests - Query Generators with reactQueryEnabled: false
+// ============================================================================
+describe('Query generators with reactQueryEnabled: false', () => {
+    describe('generateListQueryHook', () => {
+        it('should not include React Query imports when disabled', () => {
+            const result = generateListQueryHook(userTable, { reactQueryEnabled: false });
+            expect(result.content).not.toContain('@tanstack/react-query');
+            expect(result.content).not.toContain('useQuery');
+            expect(result.content).not.toContain('UseQueryOptions');
+        });
+        it('should not include useXxxQuery hook when disabled', () => {
+            const result = generateListQueryHook(userTable, { reactQueryEnabled: false });
+            expect(result.content).not.toContain('export function useUsersQuery');
+        });
+        it('should not include prefetch function when disabled', () => {
+            const result = generateListQueryHook(userTable, { reactQueryEnabled: false });
+            expect(result.content).not.toContain('export async function prefetchUsersQuery');
+        });
+        it('should still include standalone fetch function when disabled', () => {
+            const result = generateListQueryHook(userTable, { reactQueryEnabled: false });
+            expect(result.content).toContain('export async function fetchUsersQuery');
+        });
+        it('should still include GraphQL document when disabled', () => {
+            const result = generateListQueryHook(userTable, { reactQueryEnabled: false });
+            expect(result.content).toContain('usersQueryDocument');
+        });
+        it('should still include query key factory when disabled', () => {
+            const result = generateListQueryHook(userTable, { reactQueryEnabled: false });
+            expect(result.content).toContain('usersQueryKey');
+        });
+        it('should update file header when disabled', () => {
+            const result = generateListQueryHook(userTable, { reactQueryEnabled: false });
+            expect(result.content).toContain('List query functions for User');
+        });
+    });
+    describe('generateSingleQueryHook', () => {
+        it('should not include React Query imports when disabled', () => {
+            const result = generateSingleQueryHook(userTable, { reactQueryEnabled: false });
+            expect(result.content).not.toContain('@tanstack/react-query');
+            expect(result.content).not.toContain('useQuery');
+        });
+        it('should not include useXxxQuery hook when disabled', () => {
+            const result = generateSingleQueryHook(userTable, { reactQueryEnabled: false });
+            expect(result.content).not.toContain('export function useUserQuery');
+        });
+        it('should still include standalone fetch function when disabled', () => {
+            const result = generateSingleQueryHook(userTable, { reactQueryEnabled: false });
+            expect(result.content).toContain('export async function fetchUserQuery');
+        });
+    });
+    describe('generateAllQueryHooks', () => {
+        it('should generate files without React Query when disabled', () => {
+            const results = generateAllQueryHooks([userTable], { reactQueryEnabled: false });
+            expect(results.length).toBe(2); // list + single
+            for (const result of results) {
+                expect(result.content).not.toContain('@tanstack/react-query');
+                expect(result.content).not.toContain('useQuery');
+            }
+        });
+    });
+});
+// ============================================================================
+// Tests - Query Generators with reactQueryEnabled: true (default)
+// ============================================================================
+describe('Query generators with reactQueryEnabled: true (default)', () => {
+    describe('generateListQueryHook', () => {
+        it('should include React Query imports by default', () => {
+            const result = generateListQueryHook(userTable);
+            expect(result.content).toContain('@tanstack/react-query');
+            expect(result.content).toContain('useQuery');
+        });
+        it('should include useXxxQuery hook by default', () => {
+            const result = generateListQueryHook(userTable);
+            expect(result.content).toContain('export function useUsersQuery');
+        });
+        it('should include prefetch function by default', () => {
+            const result = generateListQueryHook(userTable);
+            expect(result.content).toContain('export async function prefetchUsersQuery');
+        });
+        it('should include standalone fetch function by default', () => {
+            const result = generateListQueryHook(userTable);
+            expect(result.content).toContain('export async function fetchUsersQuery');
+        });
+    });
+});
+// ============================================================================
+// Tests - Mutation Generators with reactQueryEnabled: false
+// ============================================================================
+describe('Mutation generators with reactQueryEnabled: false', () => {
+    describe('generateCreateMutationHook', () => {
+        it('should return null when disabled', () => {
+            const result = generateCreateMutationHook(userTable, { reactQueryEnabled: false });
+            expect(result).toBeNull();
+        });
+    });
+    describe('generateUpdateMutationHook', () => {
+        it('should return null when disabled', () => {
+            const result = generateUpdateMutationHook(userTable, { reactQueryEnabled: false });
+            expect(result).toBeNull();
+        });
+    });
+    describe('generateDeleteMutationHook', () => {
+        it('should return null when disabled', () => {
+            const result = generateDeleteMutationHook(userTable, { reactQueryEnabled: false });
+            expect(result).toBeNull();
+        });
+    });
+    describe('generateAllMutationHooks', () => {
+        it('should return empty array when disabled', () => {
+            const results = generateAllMutationHooks([userTable], { reactQueryEnabled: false });
+            expect(results).toEqual([]);
+        });
+    });
+});
+// ============================================================================
+// Tests - Mutation Generators with reactQueryEnabled: true (default)
+// ============================================================================
+describe('Mutation generators with reactQueryEnabled: true (default)', () => {
+    describe('generateCreateMutationHook', () => {
+        it('should return mutation file by default', () => {
+            const result = generateCreateMutationHook(userTable);
+            expect(result).not.toBeNull();
+            expect(result.content).toContain('useMutation');
+        });
+    });
+    describe('generateAllMutationHooks', () => {
+        it('should return mutation files by default', () => {
+            const results = generateAllMutationHooks([userTable]);
+            expect(results.length).toBeGreaterThan(0);
+        });
+    });
+});
+// ============================================================================
+// Tests - Custom Query Generators with reactQueryEnabled: false
+// ============================================================================
+describe('Custom query generators with reactQueryEnabled: false', () => {
+    describe('generateCustomQueryHook', () => {
+        it('should not include React Query imports when disabled', () => {
+            const result = generateCustomQueryHook({
+                operation: sampleQueryOperation,
+                typeRegistry: emptyTypeRegistry,
+                reactQueryEnabled: false,
+            });
+            expect(result.content).not.toContain('@tanstack/react-query');
+            expect(result.content).not.toContain('useQuery');
+        });
+        it('should not include useXxxQuery hook when disabled', () => {
+            const result = generateCustomQueryHook({
+                operation: sampleQueryOperation,
+                typeRegistry: emptyTypeRegistry,
+                reactQueryEnabled: false,
+            });
+            expect(result.content).not.toContain('export function useCurrentUserQuery');
+        });
+        it('should still include standalone fetch function when disabled', () => {
+            const result = generateCustomQueryHook({
+                operation: sampleQueryOperation,
+                typeRegistry: emptyTypeRegistry,
+                reactQueryEnabled: false,
+            });
+            expect(result.content).toContain('export async function fetchCurrentUserQuery');
+        });
+    });
+    describe('generateAllCustomQueryHooks', () => {
+        it('should generate files without React Query when disabled', () => {
+            const results = generateAllCustomQueryHooks({
+                operations: [sampleQueryOperation],
+                typeRegistry: emptyTypeRegistry,
+                reactQueryEnabled: false,
+            });
+            expect(results.length).toBe(1);
+            expect(results[0].content).not.toContain('@tanstack/react-query');
+        });
+    });
+});
+// ============================================================================
+// Tests - Custom Mutation Generators with reactQueryEnabled: false
+// ============================================================================
+describe('Custom mutation generators with reactQueryEnabled: false', () => {
+    describe('generateCustomMutationHook', () => {
+        it('should return null when disabled', () => {
+            const result = generateCustomMutationHook({
+                operation: sampleMutationOperation,
+                typeRegistry: emptyTypeRegistry,
+                reactQueryEnabled: false,
+            });
+            expect(result).toBeNull();
+        });
+    });
+    describe('generateAllCustomMutationHooks', () => {
+        it('should return empty array when disabled', () => {
+            const results = generateAllCustomMutationHooks({
+                operations: [sampleMutationOperation],
+                typeRegistry: emptyTypeRegistry,
+                reactQueryEnabled: false,
+            });
+            expect(results).toEqual([]);
+        });
+    });
+});
+// ============================================================================
+// Tests - Custom Mutation Generators with reactQueryEnabled: true (default)
+// ============================================================================
+describe('Custom mutation generators with reactQueryEnabled: true (default)', () => {
+    describe('generateCustomMutationHook', () => {
+        it('should return mutation file by default', () => {
+            const result = generateCustomMutationHook({
+                operation: sampleMutationOperation,
+                typeRegistry: emptyTypeRegistry,
+            });
+            expect(result).not.toBeNull();
+            expect(result.content).toContain('useMutation');
+        });
+    });
+});

package/esm/cli/codegen/custom-mutations.d.ts

@@ -21,18 +21,24 @@ export interface GenerateCustomMutationHookOptions {
     typeRegistry: TypeRegistry;
     maxDepth?: number;
     skipQueryField?: boolean;
+    /** Whether to generate React Query hooks (default: true for backwards compatibility) */
+    reactQueryEnabled?: boolean;
 }
 /**
  * Generate a custom mutation hook file
+ * When reactQueryEnabled is false, returns null since mutations require React Query
  */
-export declare function generateCustomMutationHook(options: GenerateCustomMutationHookOptions): GeneratedCustomMutationFile;
+export declare function generateCustomMutationHook(options: GenerateCustomMutationHookOptions): GeneratedCustomMutationFile | null;
 export interface GenerateAllCustomMutationHooksOptions {
     operations: CleanOperation[];
     typeRegistry: TypeRegistry;
     maxDepth?: number;
     skipQueryField?: boolean;
+    /** Whether to generate React Query hooks (default: true for backwards compatibility) */
+    reactQueryEnabled?: boolean;
 }
 /**
  * Generate all custom mutation hook files
+ * When reactQueryEnabled is false, returns empty array since mutations require React Query
  */
 export declare function generateAllCustomMutationHooks(options: GenerateAllCustomMutationHooksOptions): GeneratedCustomMutationFile[];

package/esm/cli/codegen/custom-mutations.js

@@ -3,9 +3,14 @@ import { buildCustomMutationString } from './schema-gql-ast';
 import { typeRefToTsType, isTypeRequired, getOperationHookName, getOperationFileName, getOperationVariablesTypeName, getOperationResultTypeName, getDocumentConstName, } from './type-resolver';
 /**
  * Generate a custom mutation hook file
+ * When reactQueryEnabled is false, returns null since mutations require React Query
  */
 export function generateCustomMutationHook(options) {
-    const { operation } = options;
+    const { operation, reactQueryEnabled = true } = options;
+    // Mutations require React Query - skip generation when disabled
+    if (!reactQueryEnabled) {
+        return null;
+    }
     try {
         return generateCustomMutationHookInternal(options);
     }
@@ -131,9 +136,10 @@ function generateHookBody(operation, documentConstName, variablesTypeName, resul
 }
 /**
  * Generate all custom mutation hook files
+ * When reactQueryEnabled is false, returns empty array since mutations require React Query
  */
 export function generateAllCustomMutationHooks(options) {
-    const { operations, typeRegistry, maxDepth = 2, skipQueryField = true } = options;
+    const { operations, typeRegistry, maxDepth = 2, skipQueryField = true, reactQueryEnabled = true } = options;
     return operations
         .filter((op) => op.kind === 'mutation')
         .map((operation) => generateCustomMutationHook({
@@ -141,5 +147,7 @@ export function generateAllCustomMutationHooks(options) {
         typeRegistry,
         maxDepth,
         skipQueryField,
-    }));
+        reactQueryEnabled,
+    }))
+        .filter((result) => result !== null);
 }

package/esm/cli/codegen/custom-queries.d.ts

@@ -21,6 +21,8 @@ export interface GenerateCustomQueryHookOptions {
     typeRegistry: TypeRegistry;
     maxDepth?: number;
     skipQueryField?: boolean;
+    /** Whether to generate React Query hooks (default: true for backwards compatibility) */
+    reactQueryEnabled?: boolean;
 }
 /**
  * Generate a custom query hook file
@@ -31,6 +33,8 @@ export interface GenerateAllCustomQueryHooksOptions {
     typeRegistry: TypeRegistry;
     maxDepth?: number;
     skipQueryField?: boolean;
+    /** Whether to generate React Query hooks (default: true for backwards compatibility) */
+    reactQueryEnabled?: boolean;
 }
 /**
  * Generate all custom query hook files

package/esm/cli/codegen/custom-queries.js

@@ -6,7 +6,7 @@ import { ucFirst } from './utils';
  * Generate a custom query hook file
  */
 export function generateCustomQueryHook(options) {
-    const { operation, typeRegistry, maxDepth = 2, skipQueryField = true } = options;
+    const { operation, typeRegistry, maxDepth = 2, skipQueryField = true, reactQueryEnabled = true } = options;
     const project = createProject();
     const hookName = getOperationHookName(operation.name, 'query');
     const fileName = getOperationFileName(operation.name, 'query');
@@ -23,20 +23,25 @@ export function generateCustomQueryHook(options) {
     });
     const sourceFile = createSourceFile(project, fileName);
     // Add file header
-    sourceFile.insertText(0, createFileHeader(`Custom query hook for ${operation.name}`) + '\n\n');
-    // Add imports
-    sourceFile.addImportDeclarations([
-        createImport({
+    const headerText = reactQueryEnabled
+        ? `Custom query hook for ${operation.name}`
+        : `Custom query functions for ${operation.name}`;
+    sourceFile.insertText(0, createFileHeader(headerText) + '\n\n');
+    // Add imports - conditionally include React Query imports
+    const imports = [];
+    if (reactQueryEnabled) {
+        imports.push(createImport({
             moduleSpecifier: '@tanstack/react-query',
             namedImports: ['useQuery'],
             typeOnlyNamedImports: ['UseQueryOptions', 'QueryClient'],
-        }),
-        createImport({
-            moduleSpecifier: '../client',
-            namedImports: ['execute'],
-            typeOnlyNamedImports: ['ExecuteOptions'],
-        }),
-    ]);
+        }));
+    }
+    imports.push(createImport({
+        moduleSpecifier: '../client',
+        namedImports: ['execute'],
+        typeOnlyNamedImports: ['ExecuteOptions'],
+    }));
+    sourceFile.addImportDeclarations(imports);
     // Add query document constant
     sourceFile.addVariableStatement(createConst(documentConstName, '`\n' + queryDocument + '`', {
         docs: ['GraphQL query document'],
@@ -62,17 +67,19 @@ export function generateCustomQueryHook(options) {
             docs: ['Query key factory for caching'],
         }));
     }
-    // Generate hook function
-    const hookParams = generateHookParameters(operation, variablesTypeName, resultTypeName);
-    const hookBody = generateHookBody(operation, documentConstName, queryKeyName, variablesTypeName, resultTypeName);
-    const hookDoc = generateHookDoc(operation, hookName);
-    sourceFile.addFunction({
-        name: hookName,
-        isExported: true,
-        parameters: hookParams,
-        statements: hookBody,
-        docs: [{ description: hookDoc }],
-    });
+    // Generate hook function (only if React Query is enabled)
+    if (reactQueryEnabled) {
+        const hookParams = generateHookParameters(operation, variablesTypeName, resultTypeName);
+        const hookBody = generateHookBody(operation, documentConstName, queryKeyName, variablesTypeName, resultTypeName);
+        const hookDoc = generateHookDoc(operation, hookName);
+        sourceFile.addFunction({
+            name: hookName,
+            isExported: true,
+            parameters: hookParams,
+            statements: hookBody,
+            docs: [{ description: hookDoc }],
+        });
+    }
     // Add standalone functions section
     sourceFile.addStatements('\n// ============================================================================');
     sourceFile.addStatements('// Standalone Functions (non-React)');
@@ -91,20 +98,22 @@ export function generateCustomQueryHook(options) {
         statements: fetchBody,
         docs: [{ description: fetchDoc }],
     });
-    // Generate prefetch function
-    const prefetchFnName = `prefetch${ucFirst(operation.name)}Query`;
-    const prefetchParams = generatePrefetchParameters(operation, variablesTypeName);
-    const prefetchBody = generatePrefetchBody(operation, documentConstName, queryKeyName, variablesTypeName, resultTypeName);
-    const prefetchDoc = generatePrefetchDoc(operation, prefetchFnName);
-    sourceFile.addFunction({
-        name: prefetchFnName,
-        isExported: true,
-        isAsync: true,
-        parameters: prefetchParams,
-        returnType: 'Promise<void>',
-        statements: prefetchBody,
-        docs: [{ description: prefetchDoc }],
-    });
+    // Generate prefetch function (only if React Query is enabled)
+    if (reactQueryEnabled) {
+        const prefetchFnName = `prefetch${ucFirst(operation.name)}Query`;
+        const prefetchParams = generatePrefetchParameters(operation, variablesTypeName);
+        const prefetchBody = generatePrefetchBody(operation, documentConstName, queryKeyName, variablesTypeName, resultTypeName);
+        const prefetchDoc = generatePrefetchDoc(operation, prefetchFnName);
+        sourceFile.addFunction({
+            name: prefetchFnName,
+            isExported: true,
+            isAsync: true,
+            parameters: prefetchParams,
+            returnType: 'Promise<void>',
+            statements: prefetchBody,
+            docs: [{ description: prefetchDoc }],
+        });
+    }
     return {
         fileName,
         content: getFormattedOutput(sourceFile),
@@ -342,7 +351,7 @@ await ${fnName}(queryClient);
  * Generate all custom query hook files
  */
 export function generateAllCustomQueryHooks(options) {
-    const { operations, typeRegistry, maxDepth = 2, skipQueryField = true } = options;
+    const { operations, typeRegistry, maxDepth = 2, skipQueryField = true, reactQueryEnabled = true } = options;
     return operations
         .filter((op) => op.kind === 'query')
         .map((operation) => generateCustomQueryHook({
@@ -350,5 +359,6 @@ export function generateAllCustomQueryHooks(options) {
         typeRegistry,
         maxDepth,
         skipQueryField,
+        reactQueryEnabled,
     }));
 }

package/esm/cli/codegen/index.js

@@ -23,6 +23,7 @@ export function generate(options) {
     // Extract codegen options
     const maxDepth = config.codegen.maxFieldDepth;
     const skipQueryField = config.codegen.skipQueryField;
+    const reactQueryEnabled = config.reactQuery.enabled;
     // 1. Generate client.ts
     files.push({
         path: 'client.ts',
@@ -34,7 +35,7 @@ export function generate(options) {
         content: generateTypesFile(tables),
     });
     // 3. Generate table-based query hooks (queries/*.ts)
-    const queryHooks = generateAllQueryHooks(tables);
+    const queryHooks = generateAllQueryHooks(tables, { reactQueryEnabled });
     for (const hook of queryHooks) {
         files.push({
             path: `queries/${hook.fileName}`,
@@ -49,6 +50,7 @@ export function generate(options) {
             typeRegistry: customOperations.typeRegistry,
             maxDepth,
             skipQueryField,
+            reactQueryEnabled,
         });
         for (const hook of customQueryHooks) {
             files.push({
@@ -65,7 +67,7 @@ export function generate(options) {
             : generateQueriesBarrel(tables),
     });
     // 6. Generate table-based mutation hooks (mutations/*.ts)
-    const mutationHooks = generateAllMutationHooks(tables);
+    const mutationHooks = generateAllMutationHooks(tables, { reactQueryEnabled });
     for (const hook of mutationHooks) {
         files.push({
             path: `mutations/${hook.fileName}`,
@@ -80,6 +82,7 @@ export function generate(options) {
             typeRegistry: customOperations.typeRegistry,
             maxDepth,
             skipQueryField,
+            reactQueryEnabled,
         });
         for (const hook of customMutationHooks) {
             files.push({

package/esm/cli/codegen/mutations.d.ts

@@ -12,19 +12,27 @@ export interface GeneratedMutationFile {
     fileName: string;
     content: string;
 }
+export interface MutationGeneratorOptions {
+    /** Whether to generate React Query hooks (default: true for backwards compatibility) */
+    reactQueryEnabled?: boolean;
+}
 /**
  * Generate create mutation hook file content using AST
+ * When reactQueryEnabled is false, returns null since mutations require React Query
  */
-export declare function generateCreateMutationHook(table: CleanTable): GeneratedMutationFile;
+export declare function generateCreateMutationHook(table: CleanTable, options?: MutationGeneratorOptions): GeneratedMutationFile | null;
 /**
  * Generate update mutation hook file content using AST
+ * When reactQueryEnabled is false, returns null since mutations require React Query
  */
-export declare function generateUpdateMutationHook(table: CleanTable): GeneratedMutationFile | null;
+export declare function generateUpdateMutationHook(table: CleanTable, options?: MutationGeneratorOptions): GeneratedMutationFile | null;
 /**
  * Generate delete mutation hook file content using AST
+ * When reactQueryEnabled is false, returns null since mutations require React Query
  */
-export declare function generateDeleteMutationHook(table: CleanTable): GeneratedMutationFile | null;
+export declare function generateDeleteMutationHook(table: CleanTable, options?: MutationGeneratorOptions): GeneratedMutationFile | null;
 /**
  * Generate all mutation hook files for all tables
+ * When reactQueryEnabled is false, returns empty array since mutations require React Query
  */
-export declare function generateAllMutationHooks(tables: CleanTable[]): GeneratedMutationFile[];
+export declare function generateAllMutationHooks(tables: CleanTable[], options?: MutationGeneratorOptions): GeneratedMutationFile[];

package/esm/cli/codegen/mutations.js

@@ -6,8 +6,14 @@ import { getTableNames, getCreateMutationHookName, getUpdateMutationHookName, ge
 // ============================================================================
 /**
  * Generate create mutation hook file content using AST
+ * When reactQueryEnabled is false, returns null since mutations require React Query
  */
-export function generateCreateMutationHook(table) {
+export function generateCreateMutationHook(table, options = {}) {
+    const { reactQueryEnabled = true } = options;
+    // Mutations require React Query - skip generation when disabled
+    if (!reactQueryEnabled) {
+        return null;
+    }
     const project = createProject();
     const { typeName, singularName } = getTableNames(table);
     const hookName = getCreateMutationHookName(table);
@@ -137,8 +143,14 @@ mutate({
 // ============================================================================
 /**
  * Generate update mutation hook file content using AST
+ * When reactQueryEnabled is false, returns null since mutations require React Query
  */
-export function generateUpdateMutationHook(table) {
+export function generateUpdateMutationHook(table, options = {}) {
+    const { reactQueryEnabled = true } = options;
+    // Mutations require React Query - skip generation when disabled
+    if (!reactQueryEnabled) {
+        return null;
+    }
     // Check if update mutation exists
     if (table.query?.update === null) {
         return null;
@@ -272,8 +284,14 @@ mutate({
 // ============================================================================
 /**
  * Generate delete mutation hook file content using AST
+ * When reactQueryEnabled is false, returns null since mutations require React Query
  */
-export function generateDeleteMutationHook(table) {
+export function generateDeleteMutationHook(table, options = {}) {
+    const { reactQueryEnabled = true } = options;
+    // Mutations require React Query - skip generation when disabled
+    if (!reactQueryEnabled) {
+        return null;
+    }
     // Check if delete mutation exists
     if (table.query?.delete === null) {
         return null;
@@ -386,16 +404,20 @@ mutate({
 // ============================================================================
 /**
  * Generate all mutation hook files for all tables
+ * When reactQueryEnabled is false, returns empty array since mutations require React Query
  */
-export function generateAllMutationHooks(tables) {
+export function generateAllMutationHooks(tables, options = {}) {
     const files = [];
     for (const table of tables) {
-        files.push(generateCreateMutationHook(table));
-        const updateHook = generateUpdateMutationHook(table);
+        const createHook = generateCreateMutationHook(table, options);
+        if (createHook) {
+            files.push(createHook);
+        }
+        const updateHook = generateUpdateMutationHook(table, options);
         if (updateHook) {
             files.push(updateHook);
         }
-        const deleteHook = generateDeleteMutationHook(table);
+        const deleteHook = generateDeleteMutationHook(table, options);
         if (deleteHook) {
             files.push(deleteHook);
         }