nitro-graphql 1.5.0 → 1.5.1

package/README.md

@@ -210,6 +210,246 @@ query {
 
 ## 🚀 Advanced Features
 
+<details>
+<summary><strong>🎛️ Custom File Generation & Paths</strong></summary>
+
+Control which files are auto-generated and customize their output paths. Perfect for library development, monorepos, or custom project structures.
+
+### Library Mode
+
+Disable all scaffold files for library/module development:
+
+```ts
+// nitro.config.ts
+export default defineNitroConfig({
+  graphql: {
+    framework: 'graphql-yoga',
+    scaffold: false,        // Disable all scaffold files
+    clientUtils: false,     // Disable client utilities
+  }
+})
+```
+
+### Fine-Grained Control
+
+Control each file individually:
+
+```ts
+export default defineNitroConfig({
+  graphql: {
+    framework: 'graphql-yoga',
+
+    // Scaffold files
+    scaffold: {
+      graphqlConfig: false,     // Don't generate graphql.config.ts
+      serverSchema: true,       // Generate server/graphql/schema.ts
+      serverConfig: true,       // Generate server/graphql/config.ts
+      serverContext: false,     // Don't generate server/graphql/context.ts
+    },
+
+    // Client utilities (Nuxt only)
+    clientUtils: {
+      index: true,              // Generate app/graphql/index.ts
+      ofetch: false,            // Don't generate ofetch wrappers
+    },
+
+    // SDK files
+    sdk: {
+      main: true,               // Generate default SDK
+      external: true,           // Generate external service SDKs
+    },
+
+    // Type files
+    types: {
+      server: true,             // Generate server types
+      client: true,             // Generate client types
+      external: true,           // Generate external service types
+    }
+  }
+})
+```
+
+### Custom Paths
+
+Customize where files are generated:
+
+```ts
+export default defineNitroConfig({
+  graphql: {
+    framework: 'graphql-yoga',
+
+    // Method 1: Global paths (affects all files)
+    paths: {
+      serverGraphql: 'src/server/graphql',
+      clientGraphql: 'src/client/graphql',
+      buildDir: '.build',
+      typesDir: '.build/types',
+    },
+
+    // Method 2: Specific file paths
+    scaffold: {
+      serverSchema: 'lib/graphql/schema.ts',
+      serverConfig: 'lib/graphql/config.ts',
+    },
+
+    sdk: {
+      main: 'app/graphql/organization/sdk.ts',
+      external: 'app/graphql/{serviceName}/client-sdk.ts',
+    },
+
+    types: {
+      server: 'types/graphql-server.d.ts',
+      client: 'types/graphql-client.d.ts',
+    }
+  }
+})
+```
+
+### Path Placeholders
+
+Use placeholders in custom paths:
+
+| Placeholder | Description | Example |
+|------------|-------------|---------|
+| `{serviceName}` | External service name | `github`, `stripe` |
+| `{buildDir}` | Build directory | `.nitro` or `.nuxt` |
+| `{rootDir}` | Root directory | `/Users/you/project` |
+| `{framework}` | Framework name | `nuxt` or `nitro` |
+| `{typesDir}` | Types directory | `.nitro/types` |
+| `{serverGraphql}` | Server GraphQL dir | `server/graphql` |
+| `{clientGraphql}` | Client GraphQL dir | `app/graphql` |
+
+Example:
+```ts
+sdk: {
+  external: '{clientGraphql}/{serviceName}/sdk.ts'
+}
+// → app/graphql/github/sdk.ts
+// → app/graphql/stripe/sdk.ts
+```
+
+### Service-Specific Paths
+
+Customize paths for individual external services:
+
+```ts
+export default defineNuxtConfig({
+  nitro: {
+    graphql: {
+      framework: 'graphql-yoga',
+
+      // Global default for all external services
+      sdk: {
+        external: 'app/graphql/{serviceName}/sdk.ts'
+      },
+
+      externalServices: [
+        {
+          name: 'github',
+          endpoint: 'https://api.github.com/graphql',
+          schema: 'https://api.github.com/graphql',
+
+          // GitHub-specific paths (override global config)
+          paths: {
+            sdk: 'app/graphql/organization/github-sdk.ts',
+            types: 'types/github.d.ts',
+            ofetch: 'app/graphql/organization/github-client.ts'
+          }
+        },
+        {
+          name: 'stripe',
+          endpoint: 'https://api.stripe.com/graphql',
+          schema: 'https://api.stripe.com/graphql',
+
+          // Stripe-specific paths
+          paths: {
+            sdk: 'app/graphql/payments/stripe-sdk.ts',
+            types: 'types/payments/stripe.d.ts',
+            // ofetch uses global config
+          }
+        },
+        {
+          name: 'shopify',
+          endpoint: 'https://api.shopify.com/graphql',
+          // No paths → uses global config
+          // → app/graphql/shopify/sdk.ts
+        }
+      ]
+    }
+  }
+})
+```
+
+### Path Resolution Priority
+
+When resolving file paths, the system follows this priority order:
+
+1. **Service-specific path** (for external services): `service.paths.sdk`
+2. **Category config**: `sdk.external` or `sdk.main`
+3. **Global paths**: `paths.clientGraphql`
+4. **Framework defaults**: Nuxt vs Nitro defaults
+
+Example:
+```ts
+// Given this config:
+{
+  paths: { clientGraphql: 'custom/graphql' },
+  sdk: { external: '{clientGraphql}/{serviceName}/sdk.ts' },
+  externalServices: [
+    {
+      name: 'github',
+      paths: { sdk: 'app/org/github-sdk.ts' }  // ← Wins (priority 1)
+    },
+    {
+      name: 'stripe',
+      // Uses sdk.external (priority 2)
+      // → custom/graphql/stripe/sdk.ts
+    }
+  ]
+}
+```
+
+### Use Cases
+
+**Monorepo structure:**
+```ts
+paths: {
+  serverGraphql: 'packages/api/src/graphql',
+  clientGraphql: 'packages/web/src/graphql',
+  typesDir: 'packages/types/src/generated',
+}
+```
+
+**Multiple external service organizations:**
+```ts
+externalServices: [
+  {
+    name: 'github',
+    paths: { sdk: 'app/graphql/vcs/github-sdk.ts' }
+  },
+  {
+    name: 'gitlab',
+    paths: { sdk: 'app/graphql/vcs/gitlab-sdk.ts' }
+  },
+  {
+    name: 'stripe',
+    paths: { sdk: 'app/graphql/billing/stripe-sdk.ts' }
+  }
+]
+```
+
+**Library development (no scaffolding):**
+```ts
+{
+  scaffold: false,
+  clientUtils: false,
+  sdk: { enabled: true },    // Only generate SDKs
+  types: { enabled: true },  // Only generate types
+}
+```
+
+</details>
+
 <details>
 <summary><strong>🎭 Custom Directives</strong></summary>
 

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 import { StandardSchemaV1 } from "./types/standard-schema.js";
-import { CodegenClientConfig, CodegenServerConfig, ExternalGraphQLService, FederationConfig, GenImport, GenericSdkConfig, NitroGraphQLOptions } from "./types/index.js";
+import { ClientUtilsConfig, CodegenClientConfig, CodegenServerConfig, ExternalGraphQLService, ExternalServicePaths, FederationConfig, FileGenerationConfig, GenImport, GenericSdkConfig, NitroGraphQLOptions, PathsConfig, ScaffoldConfig, SdkConfig, TypesConfig } from "./types/index.js";
 import * as nitropack0 from "nitropack";
 
 //#region src/index.d.ts
 declare const _default: nitropack0.NitroModule;
 //#endregion
-export { CodegenClientConfig, CodegenServerConfig, ExternalGraphQLService, FederationConfig, GenImport, GenericSdkConfig, NitroGraphQLOptions, StandardSchemaV1, _default as default };
+export { ClientUtilsConfig, CodegenClientConfig, CodegenServerConfig, ExternalGraphQLService, ExternalServicePaths, FederationConfig, FileGenerationConfig, GenImport, GenericSdkConfig, NitroGraphQLOptions, PathsConfig, ScaffoldConfig, SdkConfig, StandardSchemaV1, TypesConfig, _default as default };

package/dist/index.js

@@ -1,8 +1,10 @@
 import { generateDirectiveSchemas } from "./utils/directive-parser.js";
 import { generateLayerIgnorePatterns, getLayerAppDirectories, getLayerServerDirectories, relativeWithDot, scanDirectives, scanDocs, scanResolvers, scanSchemas, validateExternalServices } from "./utils/index.js";
+import { writeFileIfNotExists } from "./utils/file-generator.js";
+import { getDefaultPaths, getScaffoldConfig, resolveFilePath, shouldGenerateScaffold } from "./utils/path-resolver.js";
 import { clientTypeGeneration, serverTypeGeneration } from "./utils/type-generation.js";
 import { rollupConfig } from "./rollup.js";
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { watch } from "chokidar";
 import consola from "consola";
@@ -236,31 +238,36 @@ var src_default = defineNitroModule({
 			const nuxtOptions = nitro._nuxt?.options;
 			if (nuxtOptions) nuxtOptions.nitroGraphqlExternalServices = nitro.options.graphql?.externalServices || [];
 		});
-		if (!existsSync(join(nitro.options.rootDir, "graphql.config.ts"))) {
-			const schemaPath = relativeWithDot(nitro.options.rootDir, resolve(nitro.graphql.buildDir, "schema.graphql"));
-			const documentsPath = relativeWithDot(nitro.options.rootDir, resolve(nitro.graphql.clientDir, "**/*.{graphql,js,ts,jsx,tsx}"));
-			writeFileSync(join(nitro.options.rootDir, "graphql.config.ts"), `
+		if (shouldGenerateScaffold(nitro)) {
+			const placeholders = getDefaultPaths(nitro);
+			const scaffoldConfig = getScaffoldConfig(nitro);
+			const graphqlConfigPath = resolveFilePath(scaffoldConfig.graphqlConfig, scaffoldConfig.enabled, true, "graphql.config.ts", placeholders);
+			if (graphqlConfigPath) writeFileIfNotExists(graphqlConfigPath, `
 import type { IGraphQLConfig } from 'graphql-config'
 
 export default <IGraphQLConfig> {
     projects: {
       default: {
         schema: [
-          '${schemaPath}',
+          '${relativeWithDot(nitro.options.rootDir, resolve(nitro.graphql.buildDir, "schema.graphql"))}',
         ],
         documents: [
-          '${documentsPath}',
+          '${relativeWithDot(nitro.options.rootDir, resolve(nitro.graphql.clientDir, "**/*.{graphql,js,ts,jsx,tsx}"))}',
         ],
       },
     },
-}`, "utf-8");
-		}
-		if (!existsSync(nitro.graphql.serverDir)) mkdirSync(nitro.graphql.serverDir, { recursive: true });
-		if (!existsSync(join(nitro.graphql.serverDir, "schema.ts"))) writeFileSync(join(nitro.graphql.serverDir, "schema.ts"), `export default defineSchema({
+}`, "graphql.config.ts");
+			const serverSchemaPath = resolveFilePath(scaffoldConfig.serverSchema, scaffoldConfig.enabled, true, "{serverGraphql}/schema.ts", placeholders);
+			const serverConfigPath = resolveFilePath(scaffoldConfig.serverConfig, scaffoldConfig.enabled, true, "{serverGraphql}/config.ts", placeholders);
+			const serverContextPath = resolveFilePath(scaffoldConfig.serverContext, scaffoldConfig.enabled, true, "{serverGraphql}/context.ts", placeholders);
+			if (serverSchemaPath || serverConfigPath || serverContextPath) {
+				if (!existsSync(nitro.graphql.serverDir)) mkdirSync(nitro.graphql.serverDir, { recursive: true });
+			}
+			if (serverSchemaPath) writeFileIfNotExists(serverSchemaPath, `export default defineSchema({
 
 })
-`, "utf-8");
-		if (!existsSync(join(nitro.graphql.serverDir, "config.ts"))) writeFileSync(join(nitro.graphql.serverDir, "config.ts"), `// Example GraphQL config file please change it to your needs
+`, "server schema.ts");
+			if (serverConfigPath) writeFileIfNotExists(serverConfigPath, `// Example GraphQL config file please change it to your needs
 // import * as tables from '../drizzle/schema/index'
 // import { useDatabase } from '../utils/useDb'
 
@@ -275,8 +282,8 @@ export default defineGraphQLConfig({
 //   }
 // },
 })
-`, "utf-8");
-		if (!existsSync(join(nitro.graphql.serverDir, "context.ts"))) writeFileSync(join(nitro.graphql.serverDir, "context.ts"), `// Example context definition - please change it to your needs
+`, "server config.ts");
+			if (serverContextPath) writeFileIfNotExists(serverContextPath, `// Example context definition - please change it to your needs
 // import type { Database } from '../utils/useDb'
 
 declare module 'h3' {
@@ -291,11 +298,12 @@ declare module 'h3' {
     //   }
     // }
   }
-}`, "utf-8");
-		if (existsSync(join(nitro.graphql.serverDir, "context.d.ts"))) {
-			consola.warn("nitro-graphql: Found context.d.ts file. Please rename it to context.ts for the new structure.");
-			consola.info("The context file should now be context.ts instead of context.d.ts");
-		}
+}`, "server context.ts");
+			if (existsSync(join(nitro.graphql.serverDir, "context.d.ts"))) {
+				consola.warn("nitro-graphql: Found context.d.ts file. Please rename it to context.ts for the new structure.");
+				consola.info("The context file should now be context.ts instead of context.d.ts");
+			}
+		} else consola.info("[nitro-graphql] Scaffold file generation is disabled (library mode)");
 	}
 });
 

package/dist/routes/apollo-server.d.ts

@@ -1,6 +1,6 @@
-import * as h31 from "h3";
+import * as h35 from "h3";
 
 //#region src/routes/apollo-server.d.ts
-declare const _default: h31.EventHandler<h31.EventHandlerRequest, Promise<any>>;
+declare const _default: h35.EventHandler<h35.EventHandlerRequest, Promise<any>>;
 //#endregion
 export { _default as default };

package/dist/routes/debug.d.ts

@@ -1,4 +1,4 @@
-import * as h33 from "h3";
+import * as h31 from "h3";
 
 //#region src/routes/debug.d.ts
 
@@ -10,7 +10,7 @@ import * as h33 from "h3";
  * - /_nitro/graphql/debug - HTML dashboard
  * - /_nitro/graphql/debug?format=json - JSON API
  */
-declare const _default: h33.EventHandler<h33.EventHandlerRequest, Promise<string | {
+declare const _default: h31.EventHandler<h31.EventHandlerRequest, Promise<string | {
   timestamp: string;
   environment: {
     dev: any;

package/dist/routes/health.d.ts

@@ -1,7 +1,7 @@
-import * as h35 from "h3";
+import * as h33 from "h3";
 
 //#region src/routes/health.d.ts
-declare const _default: h35.EventHandler<h35.EventHandlerRequest, Promise<{
+declare const _default: h33.EventHandler<h33.EventHandlerRequest, Promise<{
   status: string;
   message: string;
   timestamp: string;

package/dist/types/index.d.ts

@@ -57,6 +57,18 @@ declare module 'nitropack' {
     graphql?: NitroGraphQLOptions;
   }
 }
+/**
+ * Service-specific path overrides for external GraphQL services
+ * These paths override global config for this specific service
+ */
+interface ExternalServicePaths {
+  /** SDK file path (overrides global sdk.external config) */
+  sdk?: FileGenerationConfig;
+  /** Type definitions file path (overrides global types.external config) */
+  types?: FileGenerationConfig;
+  /** ofetch client wrapper path (overrides global clientUtils.ofetch config) */
+  ofetch?: FileGenerationConfig;
+}
 interface ExternalGraphQLService {
   /** Unique name for this service (used for file naming and type generation) */
   name: string;
@@ -83,6 +95,12 @@ interface ExternalGraphQLService {
     client?: CodegenClientConfig;
     clientSDK?: GenericSdkConfig;
   };
+  /**
+   * Optional: Service-specific path overrides
+   * These paths take precedence over global config (sdk, types, clientUtils)
+   * Supports placeholders: {serviceName}, {buildDir}, {rootDir}, {framework}, {typesDir}, {clientGraphql}
+   */
+  paths?: ExternalServicePaths;
 }
 interface FederationConfig {
   /** Enable Apollo Federation subgraph support */
@@ -94,6 +112,81 @@ interface FederationConfig {
   /** Service URL for federation gateway */
   serviceUrl?: string;
 }
+/**
+ * File generation control:
+ * - false: Do not generate this file
+ * - true: Generate at default location
+ * - string: Generate at custom path (supports placeholders: {serviceName}, {buildDir}, {rootDir}, {framework})
+ */
+type FileGenerationConfig = boolean | string;
+/**
+ * Scaffold files configuration
+ * Control auto-generation of scaffold/boilerplate files
+ */
+interface ScaffoldConfig {
+  /** Enable/disable all scaffold files */
+  enabled?: boolean;
+  /** graphql.config.ts - GraphQL Config file for IDE tooling */
+  graphqlConfig?: FileGenerationConfig;
+  /** server/graphql/schema.ts - Schema definition file */
+  serverSchema?: FileGenerationConfig;
+  /** server/graphql/config.ts - GraphQL server configuration */
+  serverConfig?: FileGenerationConfig;
+  /** server/graphql/context.ts - H3 context augmentation */
+  serverContext?: FileGenerationConfig;
+}
+/**
+ * Client utilities configuration
+ * Control auto-generation of client-side utility files (Nuxt only)
+ */
+interface ClientUtilsConfig {
+  /** Enable/disable all client utilities */
+  enabled?: boolean;
+  /** app/graphql/index.ts - Main exports file */
+  index?: FileGenerationConfig;
+  /** app/graphql/{serviceName}/ofetch.ts - ofetch client wrapper */
+  ofetch?: FileGenerationConfig;
+}
+/**
+ * SDK files configuration
+ * Control auto-generation of GraphQL SDK files
+ */
+interface SdkConfig {
+  /** Enable/disable all SDK files */
+  enabled?: boolean;
+  /** app/graphql/default/sdk.ts - Main service SDK */
+  main?: FileGenerationConfig;
+  /** app/graphql/{serviceName}/sdk.ts - External service SDKs */
+  external?: FileGenerationConfig;
+}
+/**
+ * Type files configuration
+ * Control auto-generation of TypeScript type definition files
+ */
+interface TypesConfig {
+  /** Enable/disable all type files */
+  enabled?: boolean;
+  /** .nitro/types/nitro-graphql-server.d.ts - Server-side types */
+  server?: FileGenerationConfig;
+  /** .nitro/types/nitro-graphql-client.d.ts - Client-side types */
+  client?: FileGenerationConfig;
+  /** .nitro/types/nitro-graphql-client-{serviceName}.d.ts - External service types */
+  external?: FileGenerationConfig;
+}
+/**
+ * Global path overrides
+ * Set base directories for file generation
+ */
+interface PathsConfig {
+  /** Server GraphQL directory (default: 'server/graphql') */
+  serverGraphql?: string;
+  /** Client GraphQL directory (default: 'app/graphql' for Nuxt, 'graphql' for Nitro) */
+  clientGraphql?: string;
+  /** Build directory (default: '.nitro' or '.nuxt') */
+  buildDir?: string;
+  /** Types directory (default: '{buildDir}/types') */
+  typesDir?: string;
+}
 interface NitroGraphQLOptions {
   framework: 'graphql-yoga' | 'apollo-server';
   endpoint?: {
@@ -123,6 +216,31 @@ interface NitroGraphQLOptions {
   layerDirectories?: string[];
   layerServerDirs?: string[];
   layerAppDirs?: string[];
+  /**
+   * Scaffold files configuration
+   * Set to false to disable all scaffold file generation (library mode)
+   */
+  scaffold?: false | ScaffoldConfig;
+  /**
+   * Client utilities configuration
+   * Set to false to disable all client utility generation
+   */
+  clientUtils?: false | ClientUtilsConfig;
+  /**
+   * SDK files configuration
+   * Set to false to disable all SDK generation
+   */
+  sdk?: false | SdkConfig;
+  /**
+   * Type files configuration
+   * Set to false to disable all type generation
+   */
+  types?: false | TypesConfig;
+  /**
+   * Global path overrides
+   * Customize base directories for file generation
+   */
+  paths?: PathsConfig;
 }
 //#endregion
-export { CodegenClientConfig, CodegenServerConfig, ExternalGraphQLService, FederationConfig, GenImport, GenericSdkConfig, NitroGraphQLOptions };
+export { ClientUtilsConfig, CodegenClientConfig, CodegenServerConfig, ExternalGraphQLService, ExternalServicePaths, FederationConfig, FileGenerationConfig, GenImport, GenericSdkConfig, NitroGraphQLOptions, PathsConfig, ScaffoldConfig, SdkConfig, TypesConfig };

package/dist/utils/file-generator.d.ts

@@ -0,0 +1,37 @@
+import { Nitro } from "nitropack/types";
+
+//#region src/utils/file-generator.d.ts
+
+/**
+ * Safely write a file to disk, creating parent directories if needed
+ */
+declare function writeFile(filePath: string, content: string, description?: string): void;
+/**
+ * Write a file only if it doesn't already exist
+ * Returns true if file was created, false if it already existed
+ */
+declare function writeFileIfNotExists(filePath: string, content: string, description?: string): boolean;
+/**
+ * Write a file and always overwrite (used for generated files like SDK)
+ * This is for files that are auto-generated and should be updated on every build
+ */
+declare function writeGeneratedFile(filePath: string, content: string, description?: string): void;
+/**
+ * Check if a path is configured and should be generated
+ * Returns the resolved path if should generate, null otherwise
+ */
+declare function getGenerationPath(resolvedPath: string | null, description?: string): string | null;
+/**
+ * Log skipped file generation (helpful for debugging library mode)
+ */
+declare function logSkipped(fileName: string, reason?: string): void;
+/**
+ * Log generated file path
+ */
+declare function logGenerated(fileName: string, path: string): void;
+/**
+ * Validate that a Nitro instance has the required GraphQL configuration
+ */
+declare function validateGraphQLConfig(nitro: Nitro): boolean;
+//#endregion
+export { getGenerationPath, logGenerated, logSkipped, validateGraphQLConfig, writeFile, writeFileIfNotExists, writeGeneratedFile };

package/dist/utils/file-generator.js

@@ -0,0 +1,72 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import consola from "consola";
+import { dirname } from "pathe";
+
+//#region src/utils/file-generator.ts
+/**
+* Safely write a file to disk, creating parent directories if needed
+*/
+function writeFile(filePath, content, description) {
+	try {
+		const dir = dirname(filePath);
+		if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+		writeFileSync(filePath, content, "utf-8");
+		if (description) consola.success(`[nitro-graphql] Generated: ${description}`);
+	} catch (error) {
+		consola.error(`[nitro-graphql] Failed to write file: ${filePath}`, error);
+		throw error;
+	}
+}
+/**
+* Write a file only if it doesn't already exist
+* Returns true if file was created, false if it already existed
+*/
+function writeFileIfNotExists(filePath, content, description) {
+	if (existsSync(filePath)) return false;
+	writeFile(filePath, content, description);
+	return true;
+}
+/**
+* Write a file and always overwrite (used for generated files like SDK)
+* This is for files that are auto-generated and should be updated on every build
+*/
+function writeGeneratedFile(filePath, content, description) {
+	writeFile(filePath, content, description);
+}
+/**
+* Check if a path is configured and should be generated
+* Returns the resolved path if should generate, null otherwise
+*/
+function getGenerationPath(resolvedPath, description) {
+	if (!resolvedPath) {
+		if (description) consola.debug(`[nitro-graphql] Skipping generation: ${description} (disabled in config)`);
+		return null;
+	}
+	return resolvedPath;
+}
+/**
+* Log skipped file generation (helpful for debugging library mode)
+*/
+function logSkipped(fileName, reason) {
+	const message = reason ? `Skipped ${fileName}: ${reason}` : `Skipped ${fileName}`;
+	consola.debug(`[nitro-graphql] ${message}`);
+}
+/**
+* Log generated file path
+*/
+function logGenerated(fileName, path) {
+	consola.info(`[nitro-graphql] Generated ${fileName} at: ${path}`);
+}
+/**
+* Validate that a Nitro instance has the required GraphQL configuration
+*/
+function validateGraphQLConfig(nitro) {
+	if (!nitro.options.graphql?.framework) {
+		consola.warn("[nitro-graphql] No GraphQL framework specified. Some features may not work correctly.");
+		return false;
+	}
+	return true;
+}
+
+//#endregion
+export { getGenerationPath, logGenerated, logSkipped, validateGraphQLConfig, writeFile, writeFileIfNotExists, writeGeneratedFile };

package/dist/utils/path-resolver.d.ts

@@ -0,0 +1,70 @@
+import { ClientUtilsConfig, FileGenerationConfig, ScaffoldConfig, SdkConfig, TypesConfig } from "../types/index.js";
+import { Nitro } from "nitropack/types";
+
+//#region src/utils/path-resolver.d.ts
+
+/**
+ * Placeholder values for path resolution
+ */
+interface PathPlaceholders {
+  serviceName?: string;
+  buildDir: string;
+  rootDir: string;
+  framework: 'nuxt' | 'nitro';
+  typesDir: string;
+  serverGraphql: string;
+  clientGraphql: string;
+}
+/**
+ * Replace placeholders in a path string
+ * Supports: {serviceName}, {buildDir}, {rootDir}, {framework}, {typesDir}, {serverGraphql}, {clientGraphql}
+ */
+declare function replacePlaceholders(path: string, placeholders: PathPlaceholders): string;
+/**
+ * Get default paths based on framework and user configuration
+ */
+declare function getDefaultPaths(nitro: Nitro): Required<PathPlaceholders>;
+/**
+ * Check if a file should be generated based on config
+ * Returns: true if should generate, false if should skip
+ */
+declare function shouldGenerateFile(config: FileGenerationConfig | undefined, categoryEnabled: boolean | undefined, topLevelEnabled: boolean): boolean;
+/**
+ * Resolve the file path based on configuration
+ * Returns: resolved absolute path or null if file should not be generated
+ */
+declare function resolveFilePath(config: FileGenerationConfig | undefined, categoryEnabled: boolean | undefined, topLevelEnabled: boolean, defaultPath: string, placeholders: PathPlaceholders): string | null;
+/**
+ * Check if scaffold files should be generated (category-level check)
+ */
+declare function shouldGenerateScaffold(nitro: Nitro): boolean;
+/**
+ * Get scaffold configuration (handles false case)
+ */
+declare function getScaffoldConfig(nitro: Nitro): ScaffoldConfig;
+/**
+ * Check if client utilities should be generated (category-level check)
+ */
+declare function shouldGenerateClientUtils(nitro: Nitro): boolean;
+/**
+ * Get client utilities configuration (handles false case)
+ */
+declare function getClientUtilsConfig(nitro: Nitro): ClientUtilsConfig;
+/**
+ * Check if SDK files should be generated (category-level check)
+ */
+declare function shouldGenerateSDK(nitro: Nitro): boolean;
+/**
+ * Get SDK configuration (handles false case)
+ */
+declare function getSdkConfig(nitro: Nitro): SdkConfig;
+/**
+ * Check if type files should be generated (category-level check)
+ */
+declare function shouldGenerateTypes(nitro: Nitro): boolean;
+/**
+ * Get types configuration (handles false case)
+ */
+declare function getTypesConfig(nitro: Nitro): TypesConfig;
+//#endregion
+export { PathPlaceholders, getClientUtilsConfig, getDefaultPaths, getScaffoldConfig, getSdkConfig, getTypesConfig, replacePlaceholders, resolveFilePath, shouldGenerateClientUtils, shouldGenerateFile, shouldGenerateSDK, shouldGenerateScaffold, shouldGenerateTypes };

package/dist/utils/path-resolver.js

@@ -0,0 +1,127 @@
+import { resolve } from "pathe";
+
+//#region src/utils/path-resolver.ts
+/**
+* Replace placeholders in a path string
+* Supports: {serviceName}, {buildDir}, {rootDir}, {framework}, {typesDir}, {serverGraphql}, {clientGraphql}
+*/
+function replacePlaceholders(path, placeholders) {
+	return path.replace(/\{serviceName\}/g, placeholders.serviceName || "default").replace(/\{buildDir\}/g, placeholders.buildDir).replace(/\{rootDir\}/g, placeholders.rootDir).replace(/\{framework\}/g, placeholders.framework).replace(/\{typesDir\}/g, placeholders.typesDir).replace(/\{serverGraphql\}/g, placeholders.serverGraphql).replace(/\{clientGraphql\}/g, placeholders.clientGraphql);
+}
+/**
+* Get default paths based on framework and user configuration
+*/
+function getDefaultPaths(nitro) {
+	const isNuxt = nitro.options.framework?.name === "nuxt";
+	const rootDir = nitro.options.rootDir;
+	const buildDir = nitro.options.buildDir;
+	const pathsConfig = nitro.options.graphql?.paths || {};
+	const defaultServerGraphql = pathsConfig.serverGraphql || resolve(rootDir, "server", "graphql");
+	const defaultClientGraphql = pathsConfig.clientGraphql || resolve(rootDir, isNuxt ? "app/graphql" : "graphql");
+	const defaultBuildDir = pathsConfig.buildDir || buildDir;
+	const defaultTypesDir = pathsConfig.typesDir || resolve(defaultBuildDir, "types");
+	return {
+		serviceName: "default",
+		buildDir: defaultBuildDir,
+		rootDir,
+		framework: isNuxt ? "nuxt" : "nitro",
+		typesDir: defaultTypesDir,
+		serverGraphql: defaultServerGraphql,
+		clientGraphql: defaultClientGraphql
+	};
+}
+/**
+* Check if a file should be generated based on config
+* Returns: true if should generate, false if should skip
+*/
+function shouldGenerateFile(config, categoryEnabled, topLevelEnabled) {
+	if (config === false) return false;
+	if (config === true || typeof config === "string") return true;
+	if (categoryEnabled === false) return false;
+	if (categoryEnabled === true) return true;
+	return topLevelEnabled;
+}
+/**
+* Resolve the file path based on configuration
+* Returns: resolved absolute path or null if file should not be generated
+*/
+function resolveFilePath(config, categoryEnabled, topLevelEnabled, defaultPath, placeholders) {
+	if (!shouldGenerateFile(config, categoryEnabled, topLevelEnabled)) return null;
+	if (typeof config === "string") {
+		const customPath = replacePlaceholders(config, placeholders);
+		return resolve(placeholders.rootDir, customPath);
+	}
+	const resolvedDefault = replacePlaceholders(defaultPath, placeholders);
+	return resolve(placeholders.rootDir, resolvedDefault);
+}
+/**
+* Check if scaffold files should be generated (category-level check)
+*/
+function shouldGenerateScaffold(nitro) {
+	const scaffoldConfig = nitro.options.graphql?.scaffold;
+	if (scaffoldConfig === false) return false;
+	if (scaffoldConfig && scaffoldConfig.enabled === false) return false;
+	return true;
+}
+/**
+* Get scaffold configuration (handles false case)
+*/
+function getScaffoldConfig(nitro) {
+	const scaffoldConfig = nitro.options.graphql?.scaffold;
+	if (scaffoldConfig === false) return { enabled: false };
+	return scaffoldConfig || {};
+}
+/**
+* Check if client utilities should be generated (category-level check)
+*/
+function shouldGenerateClientUtils(nitro) {
+	const clientUtilsConfig = nitro.options.graphql?.clientUtils;
+	if (clientUtilsConfig === false) return false;
+	if (clientUtilsConfig && clientUtilsConfig.enabled === false) return false;
+	return nitro.options.framework?.name === "nuxt";
+}
+/**
+* Get client utilities configuration (handles false case)
+*/
+function getClientUtilsConfig(nitro) {
+	const clientUtilsConfig = nitro.options.graphql?.clientUtils;
+	if (clientUtilsConfig === false) return { enabled: false };
+	return clientUtilsConfig || {};
+}
+/**
+* Check if SDK files should be generated (category-level check)
+*/
+function shouldGenerateSDK(nitro) {
+	const sdkConfig = nitro.options.graphql?.sdk;
+	if (sdkConfig === false) return false;
+	if (sdkConfig && sdkConfig.enabled === false) return false;
+	return true;
+}
+/**
+* Get SDK configuration (handles false case)
+*/
+function getSdkConfig(nitro) {
+	const sdkConfig = nitro.options.graphql?.sdk;
+	if (sdkConfig === false) return { enabled: false };
+	return sdkConfig || {};
+}
+/**
+* Check if type files should be generated (category-level check)
+*/
+function shouldGenerateTypes(nitro) {
+	const typesConfig = nitro.options.graphql?.types;
+	if (typesConfig === false) return false;
+	if (typesConfig && typesConfig.enabled === false) return false;
+	return true;
+}
+/**
+* Get types configuration (handles false case)
+*/
+function getTypesConfig(nitro) {
+	const typesConfig = nitro.options.graphql?.types;
+	if (typesConfig === false) return { enabled: false };
+	return typesConfig || {};
+}
+
+//#endregion
+export { getClientUtilsConfig, getDefaultPaths, getScaffoldConfig, getSdkConfig, getTypesConfig, replacePlaceholders, resolveFilePath, shouldGenerateClientUtils, shouldGenerateFile, shouldGenerateSDK, shouldGenerateScaffold, shouldGenerateTypes };

package/dist/utils/type-generation.js

@@ -1,4 +1,6 @@
 import { downloadAndSaveSchema, generateClientTypes, generateExternalClientTypes, loadExternalSchema, loadGraphQLDocuments } from "./client-codegen.js";
+import { writeFileIfNotExists } from "./file-generator.js";
+import { getClientUtilsConfig, getDefaultPaths, getSdkConfig, getTypesConfig, resolveFilePath, shouldGenerateClientUtils, shouldGenerateTypes } from "./path-resolver.js";
 import { generateTypes } from "./server-codegen.js";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import consola from "consola";
@@ -10,12 +12,16 @@ import { mergeTypeDefs } from "@graphql-tools/merge";
 import { printSchemaWithDirectives } from "@graphql-tools/utils";
 
 //#region src/utils/type-generation.ts
-function generateGraphQLIndexFile(clientDir, externalServices = []) {
-	const indexPath = resolve(clientDir, "index.ts");
+function generateGraphQLIndexFile(nitro, clientDir, externalServices = []) {
+	if (!shouldGenerateClientUtils(nitro)) return;
+	const placeholders = getDefaultPaths(nitro);
+	const clientUtilsConfig = getClientUtilsConfig(nitro);
+	const indexPath = resolveFilePath(clientUtilsConfig.index, clientUtilsConfig.enabled, true, "{clientGraphql}/index.ts", placeholders);
+	if (!indexPath) return;
 	if (!existsSync(indexPath)) {
 		let indexContent = `// This file is auto-generated once by nitro-graphql for quick start
 // You can modify this file according to your needs
-// 
+//
 // Export your main GraphQL service (auto-generated)
 export * from './default/ofetch'
 
@@ -24,14 +30,21 @@ export * from './default/ofetch'
 // export * from './yourServiceName/ofetch'
 `;
 		for (const service of externalServices) indexContent += `export * from './${service.name}/ofetch'\n`;
-		writeFileSync(indexPath, indexContent, "utf-8");
+		writeFileIfNotExists(indexPath, indexContent, "client index.ts");
 	}
 }
-function generateNuxtOfetchClient(clientDir, serviceName = "default") {
-	const serviceDir = resolve(clientDir, serviceName);
-	const ofetchPath = resolve(serviceDir, "ofetch.ts");
+function generateNuxtOfetchClient(nitro, clientDir, serviceName = "default") {
+	if (!shouldGenerateClientUtils(nitro)) return;
+	const placeholders = {
+		...getDefaultPaths(nitro),
+		serviceName
+	};
+	const clientUtilsConfig = getClientUtilsConfig(nitro);
+	const ofetchPath = resolveFilePath(clientUtilsConfig.ofetch, clientUtilsConfig.enabled, true, "{clientGraphql}/{serviceName}/ofetch.ts", placeholders);
+	if (!ofetchPath) return;
+	const serviceDir = dirname(ofetchPath);
 	if (!existsSync(serviceDir)) mkdirSync(serviceDir, { recursive: true });
-	if (!existsSync(ofetchPath)) writeFileSync(ofetchPath, `// This file is auto-generated once by nitro-graphql for quick start
+	if (!existsSync(ofetchPath)) writeFileIfNotExists(ofetchPath, `// This file is auto-generated once by nitro-graphql for quick start
 // You can modify this file according to your needs
 import type { Requester } from './sdk'
 import { getSdk } from './sdk'
@@ -53,15 +66,23 @@ export function createGraphQLClient(endpoint: string): Requester {
   }
 }
 
-export const $sdk = getSdk(createGraphQLClient('/api/graphql'))`, "utf-8");
+export const $sdk = getSdk(createGraphQLClient('/api/graphql'))`, `${serviceName} ofetch.ts`);
 }
-function generateExternalOfetchClient(clientDir, serviceName, endpoint) {
-	const serviceDir = resolve(clientDir, serviceName);
-	const ofetchPath = resolve(serviceDir, "ofetch.ts");
+function generateExternalOfetchClient(nitro, service, endpoint) {
+	if (!shouldGenerateClientUtils(nitro)) return;
+	const serviceName = service.name;
+	const placeholders = {
+		...getDefaultPaths(nitro),
+		serviceName
+	};
+	const clientUtilsConfig = getClientUtilsConfig(nitro);
+	const ofetchPath = resolveFilePath(service.paths?.ofetch ?? clientUtilsConfig.ofetch, clientUtilsConfig.enabled, true, "{clientGraphql}/{serviceName}/ofetch.ts", placeholders);
+	if (!ofetchPath) return;
+	const serviceDir = dirname(ofetchPath);
 	if (!existsSync(serviceDir)) mkdirSync(serviceDir, { recursive: true });
 	if (!existsSync(ofetchPath)) {
 		const capitalizedServiceName = serviceName.charAt(0).toUpperCase() + serviceName.slice(1);
-		writeFileSync(ofetchPath, `// This file is auto-generated once by nitro-graphql for quick start
+		writeFileIfNotExists(ofetchPath, `// This file is auto-generated once by nitro-graphql for quick start
 // You can modify this file according to your needs
 import type { Sdk, Requester } from './sdk'
 import { getSdk } from './sdk'
@@ -83,7 +104,7 @@ export function create${capitalizedServiceName}GraphQLClient(endpoint: string =
   }
 }
 
-export const $${serviceName}Sdk: Sdk = getSdk(create${capitalizedServiceName}GraphQLClient())`, "utf-8");
+export const $${serviceName}Sdk: Sdk = getSdk(create${capitalizedServiceName}GraphQLClient())`, `${serviceName} external ofetch.ts`);
 	}
 }
 /**
@@ -178,6 +199,10 @@ function validateNoDuplicateTypes(schemas, schemaStrings) {
 }
 async function serverTypeGeneration(app) {
 	try {
+		if (!shouldGenerateTypes(app)) {
+			consola.debug("[nitro-graphql] Server type generation is disabled");
+			return;
+		}
 		const schemas = app.scanSchemas || [];
 		if (!schemas.length) {
 			consola.info("No GraphQL definitions found for server type generation.");
@@ -197,9 +222,14 @@ async function serverTypeGeneration(app) {
 		const schemaPath = resolve(app.graphql.buildDir, "schema.graphql");
 		mkdirSync(dirname(schemaPath), { recursive: true });
 		writeFileSync(schemaPath, printSchema, "utf-8");
-		const serverTypesPath = resolve(app.options.buildDir, "types", "nitro-graphql-server.d.ts");
-		mkdirSync(dirname(serverTypesPath), { recursive: true });
-		writeFileSync(serverTypesPath, data, "utf-8");
+		const placeholders = getDefaultPaths(app);
+		const typesConfig = getTypesConfig(app);
+		const serverTypesPath = resolveFilePath(typesConfig.server, typesConfig.enabled, true, "{typesDir}/nitro-graphql-server.d.ts", placeholders);
+		if (serverTypesPath) {
+			mkdirSync(dirname(serverTypesPath), { recursive: true });
+			writeFileSync(serverTypesPath, data, "utf-8");
+			consola.success(`[nitro-graphql] Generated server types at: ${serverTypesPath}`);
+		}
 	} catch (error) {
 		consola.error("Server schema generation error:", error);
 	}
@@ -252,17 +282,25 @@ async function generateMainClientTypes(nitro) {
 	const graphqlString = readFileSync(schemaFilePath, "utf-8");
 	const types = await generateClientTypes(nitro.options.graphql?.federation?.enabled === true ? buildSubgraphSchema([{ typeDefs: parse(graphqlString) }]) : buildSchema(graphqlString), loadDocs, nitro.options.graphql?.codegen?.client ?? {}, nitro.options.graphql?.codegen?.clientSDK ?? {});
 	if (types === false) return;
-	const clientTypesPath = resolve(nitro.options.buildDir, "types", "nitro-graphql-client.d.ts");
-	const defaultServiceDir = resolve(nitro.graphql.clientDir, "default");
-	const sdkTypesPath = resolve(defaultServiceDir, "sdk.ts");
-	mkdirSync(dirname(clientTypesPath), { recursive: true });
-	writeFileSync(clientTypesPath, types.types, "utf-8");
-	mkdirSync(defaultServiceDir, { recursive: true });
-	writeFileSync(sdkTypesPath, types.sdk, "utf-8");
+	const placeholders = getDefaultPaths(nitro);
+	const typesConfig = getTypesConfig(nitro);
+	const sdkConfig = getSdkConfig(nitro);
+	const clientTypesPath = resolveFilePath(typesConfig.client, typesConfig.enabled, true, "{typesDir}/nitro-graphql-client.d.ts", placeholders);
+	if (clientTypesPath) {
+		mkdirSync(dirname(clientTypesPath), { recursive: true });
+		writeFileSync(clientTypesPath, types.types, "utf-8");
+		consola.success(`[nitro-graphql] Generated client types at: ${clientTypesPath}`);
+	}
+	const sdkPath = resolveFilePath(sdkConfig.main, sdkConfig.enabled, true, "{clientGraphql}/default/sdk.ts", placeholders);
+	if (sdkPath) {
+		mkdirSync(dirname(sdkPath), { recursive: true });
+		writeFileSync(sdkPath, types.sdk, "utf-8");
+		consola.success(`[nitro-graphql] Generated SDK at: ${sdkPath}`);
+	}
 	if (nitro.options.framework?.name === "nuxt") {
-		generateNuxtOfetchClient(nitro.graphql.clientDir, "default");
+		generateNuxtOfetchClient(nitro, nitro.graphql.clientDir, "default");
 		const externalServices = nitro.options.graphql?.externalServices || [];
-		generateGraphQLIndexFile(nitro.graphql.clientDir, externalServices);
+		generateGraphQLIndexFile(nitro, nitro.graphql.clientDir, externalServices);
 	}
 }
 async function generateExternalServicesTypes(nitro) {
@@ -292,14 +330,25 @@ async function generateExternalServicesTypes(nitro) {
 			consola.warn(`[graphql:${service.name}] Type generation failed`);
 			continue;
 		}
-		const serviceTypesPath = resolve(nitro.options.buildDir, "types", `nitro-graphql-client-${service.name}.d.ts`);
-		const serviceDir = resolve(nitro.graphql.clientDir, service.name);
-		const serviceSdkPath = resolve(serviceDir, "sdk.ts");
-		mkdirSync(dirname(serviceTypesPath), { recursive: true });
-		writeFileSync(serviceTypesPath, types.types, "utf-8");
-		mkdirSync(serviceDir, { recursive: true });
-		writeFileSync(serviceSdkPath, types.sdk, "utf-8");
-		if (nitro.options.framework?.name === "nuxt") generateExternalOfetchClient(nitro.graphql.clientDir, service.name, service.endpoint);
+		const placeholders = {
+			...getDefaultPaths(nitro),
+			serviceName: service.name
+		};
+		const typesConfig = getTypesConfig(nitro);
+		const sdkConfig = getSdkConfig(nitro);
+		const serviceTypesPath = resolveFilePath(service.paths?.types ?? typesConfig.external, typesConfig.enabled, true, "{typesDir}/nitro-graphql-client-{serviceName}.d.ts", placeholders);
+		if (serviceTypesPath) {
+			mkdirSync(dirname(serviceTypesPath), { recursive: true });
+			writeFileSync(serviceTypesPath, types.types, "utf-8");
+			consola.success(`[graphql:${service.name}] Generated types at: ${serviceTypesPath}`);
+		}
+		const serviceSdkPath = resolveFilePath(service.paths?.sdk ?? sdkConfig.external, sdkConfig.enabled, true, "{clientGraphql}/{serviceName}/sdk.ts", placeholders);
+		if (serviceSdkPath) {
+			mkdirSync(dirname(serviceSdkPath), { recursive: true });
+			writeFileSync(serviceSdkPath, types.sdk, "utf-8");
+			consola.success(`[graphql:${service.name}] Generated SDK at: ${serviceSdkPath}`);
+		}
+		if (nitro.options.framework?.name === "nuxt") generateExternalOfetchClient(nitro, service, service.endpoint);
 		consola.success(`[graphql:${service.name}] External service types generated successfully`);
 	} catch (error) {
 		consola.error(`[graphql:${service.name}] External service generation failed:`, error);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "nitro-graphql",
   "type": "module",
-  "version": "1.5.0",
+  "version": "1.5.1",
   "description": "GraphQL integration for Nitro",
   "license": "MIT",
   "sideEffects": false,