nitro-graphql 1.1.3 → 1.2.0

package/README.md

@@ -31,8 +31,22 @@
 - 📦 **Optimized Bundling**: Smart chunking and dynamic imports for production
 - 🌐 **Nuxt Integration**: First-class Nuxt.js support with dedicated module
 - 🎭 **Custom Directives**: Create reusable GraphQL directives with automatic schema generation
+- 🔗 **Multi-Service Support**: Connect to multiple external GraphQL APIs alongside your main server
 
-## 🚀 Quick Start
+## 🎯 Used Projects
+
+Projects using Nitro GraphQL in production:
+
+- [**Nitroping**](https://github.com/productdevbook/nitroping) - Open-source, self-hosted push notification service
+
+## 🎥 Video Tutorials
+
+Learn how to use Nitro GraphQL with these video tutorials:
+
+- [**Nuxt 4 Usage**](https://x.com/productdevbook/status/1947314569531076633) - How to integrate Nitro GraphQL with Nuxt 4
+- [**Nitro Usage**](https://x.com/productdevbook/status/1945759751393976348) - How to use Nitro GraphQL with standalone Nitro
+
+## 🎯 Quick Start
 
 ### Step 1: Installation
 
@@ -1260,6 +1274,249 @@ Help us improve nitro-graphql! Pick any item and contribute:
 > [!NOTE]
 > Have other ideas? Open an issue to discuss!
 
+## 🔗 Multi-Service GraphQL Support
+
+Connect to multiple external GraphQL APIs alongside your main GraphQL server. Perfect for integrating with services like GitHub API, Shopify API, or any GraphQL endpoint.
+
+### Configuration
+
+```typescript
+// nuxt.config.ts (for Nuxt projects)
+export default defineNuxtConfig({
+  nitro: {
+    graphql: {
+      framework: 'graphql-yoga',
+      externalServices: [
+        {
+          name: 'countries',
+          schema: 'https://countries.trevorblades.com',
+          endpoint: 'https://countries.trevorblades.com',
+          documents: ['app/graphql/external/countries/**/*.graphql'],
+          headers: {
+            // Optional: Add custom headers
+            'Authorization': 'Bearer your-token'
+          }
+        },
+        {
+          name: 'github',
+          schema: 'https://api.github.com/graphql',
+          endpoint: 'https://api.github.com/graphql',
+          documents: ['app/graphql/external/github/**/*.graphql'],
+          headers: () => ({
+            // Dynamic headers with function
+            'Authorization': `Bearer ${process.env.GITHUB_TOKEN}`
+          })
+        }
+      ]
+    }
+  }
+})
+```
+
+### Schema Download & Caching (Optional)
+
+For better performance and offline development, you can download and cache external schemas locally:
+
+```typescript
+// nuxt.config.ts
+export default defineNuxtConfig({
+  nitro: {
+    graphql: {
+      framework: 'graphql-yoga',
+      externalServices: [
+        {
+          name: 'github',
+          schema: 'https://docs.github.com/public/schema.docs.graphql',
+          endpoint: 'https://api.github.com/graphql',
+          downloadSchema: 'once', // Download mode (see options below)
+          downloadPath: './schemas/github.graphql', // Optional: custom download path
+          headers: () => ({
+            'Authorization': `Bearer ${process.env.GITHUB_TOKEN}`
+          })
+        }
+      ]
+    }
+  }
+})
+```
+
+**Download Modes:**
+
+| Mode | Behavior | Use Case |
+|------|----------|----------|
+| `true` or `'once'` | Download only if file doesn't exist | **Offline-friendly development** |
+| `'always'` | Check for updates on every build | **Always stay up-to-date** |
+| `'manual'` | Never download automatically | **Full manual control** |
+| `false` | Disable schema downloading | **Always use remote** |
+
+**Benefits:**
+- **Offline Development**: Work without internet connection after initial download
+- **Faster Builds**: No remote fetching on each build when using 'once' mode
+- **Version Control**: Commit downloaded schemas to track API changes
+- **Network Reliability**: Fallback to cached schema if remote is unavailable
+
+**How it works:**
+- **'once' mode (recommended)**: Downloads schema only if file doesn't exist, then uses cached version
+- **'always' mode**: Checks for schema changes on every build using hash comparison
+- **'manual' mode**: User manages schema files manually, no automatic downloading
+
+**File locations:**
+- Default: `.nitro/graphql/schemas/[serviceName].graphql`
+- Custom: Use `downloadPath` option to specify your preferred location
+
+### Usage
+
+#### 1. Create External Service Queries
+
+```graphql
+<!-- app/graphql/external/countries/countries.graphql -->
+query GetCountries {
+  countries {
+    code
+    name
+    emoji
+    continent {
+      name
+    }
+  }
+}
+
+query GetCountry($code: ID!) {
+  country(code: $code) {
+    code
+    name
+    capital
+    currency
+  }
+}
+```
+
+#### 2. Use Generated SDKs
+
+```typescript
+// Import from centralized index
+import { $sdk, $countriesSdk, $githubSdk } from '~/app/graphql'
+
+// Or import directly from service folders
+import { $countriesSdk } from '~/app/graphql/countries/ofetch'
+
+// Use in components
+const countries = await $countriesSdk.GetCountries()
+const country = await $countriesSdk.GetCountry({ code: 'US' })
+
+// Your main service still works
+const users = await $sdk.GetUsers()
+```
+
+#### 3. Folder Structure
+
+After configuration, your project structure becomes:
+
+```
+app/graphql/
+├── index.ts                    # Centralized exports (auto-generated)
+├── default/                    # Your main GraphQL service
+│   ├── ofetch.ts              # Main service client
+│   └── sdk.ts                 # Main service SDK
+├── countries/                  # External countries service
+│   ├── ofetch.ts              # Countries service client  
+│   └── sdk.ts                 # Countries service SDK
+├── github/                     # External GitHub service
+│   ├── ofetch.ts              # GitHub service client
+│   └── sdk.ts                 # GitHub service SDK
+└── external/                   # Your external service queries
+    ├── countries/
+    │   └── countries.graphql
+    └── github/
+        └── repositories.graphql
+```
+
+#### 4. TypeScript Support
+
+Each service gets its own type definitions:
+
+```typescript
+// Types are automatically generated and available
+import type { GetCountriesQuery } from '#graphql/client/countries'
+import type { GetUsersQuery } from '#graphql/client'
+
+const handleCountries = (countries: GetCountriesQuery) => {
+  // Fully typed countries data
+}
+```
+
+### Service Configuration Options
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `name` | `string` | ✅ | Unique service name (used for folder/file names) |
+| `schema` | `string` \| `string[]` | ✅ | GraphQL schema URL or file path |
+| `endpoint` | `string` | ✅ | GraphQL endpoint URL for queries |
+| `documents` | `string[]` | ❌ | Glob patterns for GraphQL query files |
+| `headers` | `Record<string, string>` \| `() => Record<string, string>` | ❌ | Custom headers for schema introspection and queries |
+| `codegen.client` | `CodegenClientConfig` | ❌ | Custom codegen configuration for client types |
+| `codegen.clientSDK` | `GenericSdkConfig` | ❌ | Custom codegen configuration for SDK generation |
+
+## 🛠️ GraphQL Config (Optional but Recommended)
+
+To enable GraphQL language features in your IDE (autocompletion, validation, go-to definition), create a `graphql.config.ts` file in your project root:
+
+### For Single Service (Main GraphQL Server Only)
+
+```typescript
+// graphql.config.ts
+import type { IGraphQLConfig } from 'graphql-config'
+
+export default <IGraphQLConfig> {
+  schema: ['./.nuxt/graphql/schema.graphql'],
+  documents: ['./app/graphql/**/*.{graphql,js,ts,jsx,tsx}'],
+  exclude: ['./app/graphql/external/**/*'] // Exclude external service documents
+}
+```
+
+### For Multi-Service Setup
+
+```typescript
+// graphql.config.ts
+import type { IGraphQLConfig } from 'graphql-config'
+
+export default <IGraphQLConfig> {
+  projects: {
+    // Main GraphQL server
+    default: {
+      schema: ['./.nuxt/graphql/schema.graphql'],
+      documents: ['./app/graphql/default/**/*.{graphql,js,ts,jsx,tsx}']
+    },
+    // External services
+    github: {
+      schema: [
+        // Use downloaded schema if available, otherwise use remote
+        './.nuxt/graphql/schemas/github.graphql',
+        // Fallback to remote if local doesn't exist
+        'https://docs.github.com/public/schema.docs.graphql'
+      ],
+      documents: ['./app/graphql/external/github/**/*.graphql']
+    },
+    countries: {
+      schema: ['./.nuxt/graphql/schemas/countries.graphql'],
+      documents: ['./app/graphql/external/countries/**/*.graphql']
+    }
+  }
+}
+```
+
+### Schema Paths for Different Download Modes
+
+- **Downloaded schemas**: `./.nuxt/graphql/schemas/[serviceName].graphql`
+- **Custom download path**: Use your `downloadPath` configuration
+- **Remote fallback**: Include remote URL as second option
+
+This configuration enables:
+- 🎯 **Service-specific validation**: Each GraphQL service gets its own validation rules
+- 🚀 **IDE autocompletion**: Full IntelliSense for queries and mutations
+- ✅ **Real-time validation**: Catch GraphQL errors while typing
+- 🔍 **Go-to definition**: Navigate to type definitions across services
+
 ## 🛠️ VS Code Extensions
 
 For the best development experience with GraphQL, install these recommended VS Code extensions:

package/dist/ecosystem/nuxt.d.ts

@@ -1,7 +1,7 @@
-import * as _nuxt_schema0 from "@nuxt/schema";
+import * as _nuxt_schema3 from "@nuxt/schema";
 
 //#region src/ecosystem/nuxt.d.ts
 interface ModuleOptions {}
-declare const _default: _nuxt_schema0.NuxtModule<ModuleOptions, ModuleOptions, false>;
+declare const _default: _nuxt_schema3.NuxtModule<ModuleOptions, ModuleOptions, false>;
 //#endregion
 export { ModuleOptions, _default as default };

package/dist/ecosystem/nuxt.js

@@ -15,11 +15,19 @@ var nuxt_default = defineNuxtModule({
 			options.tsConfig.compilerOptions ??= {};
 			options.tsConfig.compilerOptions.paths ??= {};
 			options.tsConfig.compilerOptions.paths["#graphql/client"] = ["./types/nitro-graphql-client.d.ts"];
+			const externalServices$1 = nuxt.options.nitro?.graphql?.externalServices || [];
+			for (const service of externalServices$1) {
+				options.references.push({ path: `types/nitro-graphql-client-${service.name}.d.ts` });
+				options.tsConfig.compilerOptions.paths[`#graphql/client/${service.name}`] = [`./types/nitro-graphql-client-${service.name}.d.ts`];
+			}
 			options.tsConfig.include = options.tsConfig.include || [];
 			options.tsConfig.include.push("./types/nitro-graphql-client.d.ts");
+			for (const service of externalServices$1) options.tsConfig.include.push(`./types/nitro-graphql-client-${service.name}.d.ts`);
 		});
 		nuxt.options.alias = nuxt.options.alias || {};
 		nuxt.options.alias["#graphql/client"] = join(nuxt.options.buildDir, "types/nitro-graphql-client.d.ts");
+		const externalServices = nuxt.options.nitro?.graphql?.externalServices || [];
+		for (const service of externalServices) nuxt.options.alias[`#graphql/client/${service.name}`] = join(nuxt.options.buildDir, `types/nitro-graphql-client-${service.name}.d.ts`);
 		nuxt.hook("imports:dirs", (dirs) => {
 			dirs.push(resolve(nuxt.options.srcDir, "graphql"));
 		});

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 import { StandardSchemaV1 } from "./types/standard-schema.js";
-import { CodegenClientConfig, CodegenServerConfig, GenImport, GenericSdkConfig, NitroGraphQLOptions } from "./types/index.js";
-import * as nitropack1 from "nitropack";
+import { CodegenClientConfig, CodegenServerConfig, ExternalGraphQLService, GenImport, GenericSdkConfig, NitroGraphQLOptions } from "./types/index.js";
+import * as nitropack2 from "nitropack";
 
 //#region src/index.d.ts
-declare const _default: nitropack1.NitroModule;
+declare const _default: nitropack2.NitroModule;
 //#endregion
-export { CodegenClientConfig, CodegenServerConfig, GenImport, GenericSdkConfig, NitroGraphQLOptions, StandardSchemaV1, _default as default };
+export { CodegenClientConfig, CodegenServerConfig, ExternalGraphQLService, GenImport, GenericSdkConfig, NitroGraphQLOptions, StandardSchemaV1, _default as default };

package/dist/index.js

@@ -1,5 +1,5 @@
 import { generateDirectiveSchemas } from "./utils/directive-parser.js";
-import { relativeWithDot, scanDirectives, scanDocs, scanResolvers, scanSchemas } from "./utils/index.js";
+import { relativeWithDot, scanDirectives, scanDocs, scanResolvers, scanSchemas, validateExternalServices } from "./utils/index.js";
 import { clientTypeGeneration, serverTypeGeneration } from "./utils/type-generation.js";
 import { rollupConfig } from "./rollup.js";
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
@@ -15,6 +15,15 @@ var src_default = defineNitroModule({
 	name: "nitro-graphql",
 	async setup(nitro) {
 		if (!nitro.options.graphql?.framework) consola.warn("No GraphQL framework specified. Please set graphql.framework to \"graphql-yoga\" or \"apollo-server\".");
+		if (nitro.options.graphql?.externalServices?.length) {
+			const validationErrors = validateExternalServices(nitro.options.graphql.externalServices);
+			if (validationErrors.length > 0) {
+				consola.error("External services configuration errors:");
+				for (const error of validationErrors) consola.error(`  - ${error}`);
+				throw new Error("Invalid external services configuration");
+			}
+			consola.info(`Configured ${nitro.options.graphql.externalServices.length} external GraphQL services`);
+		}
 		nitro.graphql ||= {
 			buildDir: "",
 			watchDirs: [],
@@ -60,6 +69,13 @@ var src_default = defineNitroModule({
 				break;
 			default:
 		}
+		if (nitro.options.graphql?.externalServices?.length) {
+			for (const service of nitro.options.graphql.externalServices) if (service.documents?.length) for (const pattern of service.documents) {
+				const baseDir = pattern.split("**")[0].replace(/\/$/, "") || ".";
+				const resolvedDir = resolve(nitro.options.rootDir, baseDir);
+				if (!watchDirs.includes(resolvedDir)) watchDirs.push(resolvedDir);
+			}
+		}
 		const watcher = watch(watchDirs, {
 			persistent: true,
 			ignoreInitial: true,
@@ -160,8 +176,14 @@ var src_default = defineNitroModule({
 			types.tsConfig.compilerOptions.paths["#graphql/server"] = [relativeWithDot(tsconfigDir, join(typesDir, "nitro-graphql-server.d.ts"))];
 			types.tsConfig.compilerOptions.paths["#graphql/client"] = [relativeWithDot(tsconfigDir, join(typesDir, "nitro-graphql-client.d.ts"))];
 			types.tsConfig.compilerOptions.paths["#graphql/schema"] = [relativeWithDot(tsconfigDir, join(nitro.graphql.serverDir, "schema.ts"))];
+			if (nitro.options.graphql?.externalServices?.length) for (const service of nitro.options.graphql.externalServices) types.tsConfig.compilerOptions.paths[`#graphql/client/${service.name}`] = [relativeWithDot(tsconfigDir, join(typesDir, `nitro-graphql-client-${service.name}.d.ts`))];
 			types.tsConfig.include = types.tsConfig.include || [];
 			types.tsConfig.include.push(relativeWithDot(tsconfigDir, join(typesDir, "nitro-graphql-server.d.ts")), relativeWithDot(tsconfigDir, join(typesDir, "nitro-graphql-client.d.ts")), relativeWithDot(tsconfigDir, join(typesDir, "graphql.d.ts")));
+			if (nitro.options.graphql?.externalServices?.length) for (const service of nitro.options.graphql.externalServices) types.tsConfig.include.push(relativeWithDot(tsconfigDir, join(typesDir, `nitro-graphql-client-${service.name}.d.ts`)));
+		});
+		if (nitro.options.framework?.name === "nuxt" && nitro.options.graphql?.externalServices?.length) nitro.hooks.hook("build:before", () => {
+			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"));

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

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

package/dist/routes/graphql-yoga.d.ts

@@ -1,6 +1,6 @@
-import * as h36 from "h3";
+import * as h30 from "h3";
 
 //#region src/routes/graphql-yoga.d.ts
-declare const _default: h36.EventHandler<h36.EventHandlerRequest, Promise<Response>>;
+declare const _default: h30.EventHandler<h30.EventHandlerRequest, Promise<Response>>;
 //#endregion
 export { _default as default };

package/dist/routes/health.d.ts

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

package/dist/types/index.d.ts

@@ -57,6 +57,33 @@ declare module 'nitropack' {
     graphql?: NitroGraphQLOptions;
   }
 }
+interface ExternalGraphQLService {
+  /** Unique name for this service (used for file naming and type generation) */
+  name: string;
+  /** Schema source - can be URL(s) for remote schemas or file path(s) for local schemas */
+  schema: string | string[];
+  /** GraphQL endpoint for this service */
+  endpoint: string;
+  /** Optional headers for schema introspection and client requests */
+  headers?: Record<string, string> | (() => Record<string, string>);
+  /** Optional: specific document patterns for this service */
+  documents?: string[];
+  /**
+   * Optional: Download and cache schema locally for offline usage
+   * - true or 'once': Download if file doesn't exist, then use cached version (offline-friendly)
+   * - 'always': Check for updates on every build (current behavior)
+   * - 'manual': Never download automatically, user manages schema files manually
+   * - false: Disable schema downloading
+   */
+  downloadSchema?: boolean | 'once' | 'always' | 'manual';
+  /** Optional: Custom path to save downloaded schema (default: .nitro/graphql/schemas/[serviceName].graphql) */
+  downloadPath?: string;
+  /** Optional: service-specific codegen configuration */
+  codegen?: {
+    client?: CodegenClientConfig;
+    clientSDK?: GenericSdkConfig;
+  };
+}
 interface NitroGraphQLOptions {
   framework: 'graphql-yoga' | 'apollo-server';
   endpoint?: {
@@ -76,6 +103,8 @@ interface NitroGraphQLOptions {
     client?: CodegenClientConfig;
     clientSDK?: GenericSdkConfig;
   };
+  /** External GraphQL services to generate types and SDKs for */
+  externalServices?: ExternalGraphQLService[];
 }
 //#endregion
-export { CodegenClientConfig, CodegenServerConfig, GenImport, GenericSdkConfig, NitroGraphQLOptions };
+export { CodegenClientConfig, CodegenServerConfig, ExternalGraphQLService, GenImport, GenericSdkConfig, NitroGraphQLOptions };

package/dist/utils/client-codegen.d.ts

@@ -1,4 +1,4 @@
-import { CodegenClientConfig, GenericSdkConfig } from "../types/index.js";
+import { CodegenClientConfig, ExternalGraphQLService, GenericSdkConfig } from "../types/index.js";
 import { GraphQLSchema } from "graphql";
 import { Source } from "@graphql-tools/utils";
 import { LoadSchemaOptions, UnnormalizedTypeDefPointer } from "@graphql-tools/load";
@@ -14,10 +14,25 @@ type GraphQLTypeDefPointer = UnnormalizedTypeDefPointer | UnnormalizedTypeDefPoi
  */
 type GraphQLLoadSchemaOptions = Partial<LoadSchemaOptions>;
 declare function graphQLLoadSchemaSync(schemaPointers: GraphQLTypeDefPointer, data?: GraphQLLoadSchemaOptions): Promise<GraphQLSchema | undefined>;
+/**
+ * Load schema from external GraphQL service
+ */
+declare function loadExternalSchema(service: ExternalGraphQLService, buildDir?: string): Promise<GraphQLSchema | undefined>;
+/**
+ * Download and save schema from external service
+ */
+declare function downloadAndSaveSchema(service: ExternalGraphQLService, buildDir: string): Promise<string | undefined>;
 declare function loadGraphQLDocuments(patterns: string | string[]): Promise<Source[]>;
-declare function generateClientTypes(schema: GraphQLSchema, docs: Source[], config?: CodegenClientConfig, sdkConfig?: GenericSdkConfig, outputPath?: string): Promise<false | {
+declare function generateClientTypes(schema: GraphQLSchema, docs: Source[], config?: CodegenClientConfig, sdkConfig?: GenericSdkConfig, outputPath?: string, serviceName?: string): Promise<false | {
   types: string;
   sdk: string;
 }>;
+/**
+ * Generate client types for external GraphQL service
+ */
+declare function generateExternalClientTypes(service: ExternalGraphQLService, schema: GraphQLSchema, docs: Source[]): Promise<{
+  types: string;
+  sdk: string;
+} | false>;
 //#endregion
-export { GraphQLLoadSchemaOptions, GraphQLTypeDefPointer, generateClientTypes, graphQLLoadSchemaSync, loadGraphQLDocuments };
+export { GraphQLLoadSchemaOptions, GraphQLTypeDefPointer, downloadAndSaveSchema, generateClientTypes, generateExternalClientTypes, graphQLLoadSchemaSync, loadExternalSchema, loadGraphQLDocuments };

package/dist/utils/client-codegen.js

@@ -1,14 +1,18 @@
 import { preset } from "../node_modules/.pnpm/@graphql-codegen_import-types-preset@3.0.1_graphql@16.11.0/node_modules/@graphql-codegen/import-types-preset/esm/index.js";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { consola as consola$1 } from "consola";
 import { defu as defu$1 } from "defu";
+import { dirname, resolve } from "pathe";
 import { parse } from "graphql";
 import { printSchemaWithDirectives } from "@graphql-tools/utils";
+import { createHash } from "node:crypto";
 import { codegen } from "@graphql-codegen/core";
 import { plugin } from "@graphql-codegen/typescript";
 import { plugin as plugin$1 } from "@graphql-codegen/typescript-generic-sdk";
 import { plugin as plugin$2 } from "@graphql-codegen/typescript-operations";
 import { GraphQLFileLoader } from "@graphql-tools/graphql-file-loader";
 import { loadDocuments, loadSchemaSync } from "@graphql-tools/load";
+import { UrlLoader } from "@graphql-tools/url-loader";
 import { CurrencyResolver, DateTimeISOResolver, DateTimeResolver, JSONObjectResolver, JSONResolver, NonEmptyStringResolver, UUIDResolver } from "graphql-scalars";
 
 //#region src/utils/client-codegen.ts
@@ -31,7 +35,11 @@ async function graphQLLoadSchemaSync(schemaPointers, data = {}) {
 	try {
 		result = loadSchemaSync(filteredPointers, {
 			...data,
-			loaders: [new GraphQLFileLoader(), ...data.loaders || []]
+			loaders: [
+				new GraphQLFileLoader(),
+				new UrlLoader(),
+				...data.loaders || []
+			]
 		});
 	} catch (e) {
 		if ((e.message || "").includes("Unable to find any GraphQL type definitions for the following pointers:")) consola$1.info("No server GraphQL files found. If you need server-side GraphQL, add .graphql files to your server directory.");
@@ -39,6 +47,92 @@ async function graphQLLoadSchemaSync(schemaPointers, data = {}) {
 	}
 	return result;
 }
+/**
+* Load schema from external GraphQL service
+*/
+async function loadExternalSchema(service, buildDir) {
+	try {
+		const headers = typeof service.headers === "function" ? service.headers() : service.headers || {};
+		const schemas = Array.isArray(service.schema) ? service.schema : [service.schema];
+		if (service.downloadSchema && buildDir) {
+			const defaultPath = resolve(buildDir, "graphql", "schemas", `${service.name}.graphql`);
+			const schemaFilePath = service.downloadPath ? resolve(service.downloadPath) : defaultPath;
+			if (existsSync(schemaFilePath)) {
+				consola$1.info(`[graphql:${service.name}] Loading schema from local file: ${schemaFilePath}`);
+				try {
+					const result$1 = loadSchemaSync([schemaFilePath], { loaders: [new GraphQLFileLoader()] });
+					consola$1.info(`[graphql:${service.name}] External schema loaded successfully from local file`);
+					return result$1;
+				} catch (localError) {
+					consola$1.warn(`[graphql:${service.name}] Failed to load local schema, falling back to remote:`, localError);
+				}
+			}
+		}
+		consola$1.info(`[graphql:${service.name}] Loading external schema from: ${schemas.join(", ")}`);
+		const result = loadSchemaSync(schemas, {
+			loaders: [new GraphQLFileLoader(), new UrlLoader()],
+			...Object.keys(headers).length > 0 && { headers }
+		});
+		consola$1.info(`[graphql:${service.name}] External schema loaded successfully`);
+		return result;
+	} catch (error) {
+		consola$1.error(`[graphql:${service.name}] Failed to load external schema:`, error);
+		return void 0;
+	}
+}
+/**
+* Download and save schema from external service
+*/
+async function downloadAndSaveSchema(service, buildDir) {
+	const downloadMode = service.downloadSchema;
+	if (!downloadMode || downloadMode === "manual") return void 0;
+	const defaultPath = resolve(buildDir, "graphql", "schemas", `${service.name}.graphql`);
+	const schemaFilePath = service.downloadPath ? resolve(service.downloadPath) : defaultPath;
+	try {
+		const headers = typeof service.headers === "function" ? service.headers() : service.headers || {};
+		const schemas = Array.isArray(service.schema) ? service.schema : [service.schema];
+		let shouldDownload = false;
+		const fileExists = existsSync(schemaFilePath);
+		if (downloadMode === "always") {
+			shouldDownload = true;
+			if (fileExists) try {
+				const remoteSchema = loadSchemaSync(schemas, {
+					loaders: [new UrlLoader()],
+					...Object.keys(headers).length > 0 && { headers }
+				});
+				const remoteSchemaString = printSchemaWithDirectives(remoteSchema);
+				const remoteHash = createHash("md5").update(remoteSchemaString).digest("hex");
+				const localSchemaString = readFileSync(schemaFilePath, "utf-8");
+				const localHash = createHash("md5").update(localSchemaString).digest("hex");
+				if (remoteHash === localHash) {
+					shouldDownload = false;
+					consola$1.info(`[graphql:${service.name}] Schema is up-to-date, using cached version`);
+				}
+			} catch {
+				consola$1.warn(`[graphql:${service.name}] Unable to compare with remote schema, updating local cache`);
+				shouldDownload = true;
+			}
+		} else if (downloadMode === true || downloadMode === "once") {
+			shouldDownload = !fileExists;
+			if (fileExists) consola$1.info(`[graphql:${service.name}] Using cached schema from: ${schemaFilePath}`);
+		}
+		if (shouldDownload) {
+			consola$1.info(`[graphql:${service.name}] Downloading schema to: ${schemaFilePath}`);
+			const schema = loadSchemaSync(schemas, {
+				loaders: [new UrlLoader()],
+				...Object.keys(headers).length > 0 && { headers }
+			});
+			const schemaString = printSchemaWithDirectives(schema);
+			mkdirSync(dirname(schemaFilePath), { recursive: true });
+			writeFileSync(schemaFilePath, schemaString, "utf-8");
+			consola$1.success(`[graphql:${service.name}] Schema downloaded and saved successfully`);
+		}
+		return schemaFilePath;
+	} catch (error) {
+		consola$1.error(`[graphql:${service.name}] Failed to download schema:`, error);
+		return void 0;
+	}
+}
 async function loadGraphQLDocuments(patterns) {
 	try {
 		const result = await loadDocuments(patterns, { loaders: [new GraphQLFileLoader()] });
@@ -48,12 +142,14 @@ async function loadGraphQLDocuments(patterns) {
 		else throw e;
 	}
 }
-async function generateClientTypes(schema, docs, config = {}, sdkConfig = {}, outputPath) {
+async function generateClientTypes(schema, docs, config = {}, sdkConfig = {}, outputPath, serviceName) {
 	if (docs.length === 0) {
-		consola$1.info("[graphql] No client GraphQL files found. Skipping client type generation.");
+		const serviceLabel$1 = serviceName ? `:${serviceName}` : "";
+		consola$1.info(`[graphql${serviceLabel$1}] No client GraphQL files found. Skipping client type generation.`);
 		return false;
 	}
-	consola$1.info(`[graphql] Found ${docs.length} client GraphQL documents`);
+	const serviceLabel = serviceName ? `:${serviceName}` : "";
+	consola$1.info(`[graphql${serviceLabel}] Found ${docs.length} client GraphQL documents`);
 	const defaultConfig = {
 		emitLegacyCommonJSImports: false,
 		useTypeImports: true,
@@ -98,12 +194,13 @@ async function generateClientTypes(schema, docs, config = {}, sdkConfig = {}, ou
 				typescriptOperations: { plugin: plugin$2 }
 			}
 		});
+		const typesPath = serviceName ? `#graphql/client/${serviceName}` : "#graphql/client";
 		const sdkOutput = await preset.buildGeneratesSection({
 			baseOutputDir: outputPath || "client-types.generated.ts",
 			schema: parse(printSchemaWithDirectives(schema)),
 			documents: [...docs],
 			config: mergedSdkConfig,
-			presetConfig: { typesPath: "#graphql/client" },
+			presetConfig: { typesPath },
 			plugins: [{ pluginContent: {} }, { typescriptGenericSdk: {} }],
 			pluginMap: {
 				pluginContent: { plugin: pluginContent },
@@ -116,15 +213,24 @@ async function generateClientTypes(schema, docs, config = {}, sdkConfig = {}, ou
 				content: await codegen(config$1)
 			};
 		}));
+		const sdkContent = results[0]?.content || "";
 		return {
 			types: output,
-			sdk: results[0]?.content || ""
+			sdk: sdkContent
 		};
 	} catch (error) {
-		consola$1.warn("[graphql] Client type generation failed:", error);
+		consola$1.warn(`[graphql${serviceLabel}] Client type generation failed:`, error);
 		return false;
 	}
 }
+/**
+* Generate client types for external GraphQL service
+*/
+async function generateExternalClientTypes(service, schema, docs) {
+	const config = service.codegen?.client || {};
+	const sdkConfig = service.codegen?.clientSDK || {};
+	return generateClientTypes(schema, docs, config, sdkConfig, void 0, service.name);
+}
 
 //#endregion
-export { generateClientTypes, graphQLLoadSchemaSync, loadGraphQLDocuments };
+export { downloadAndSaveSchema, generateClientTypes, generateExternalClientTypes, graphQLLoadSchemaSync, loadExternalSchema, loadGraphQLDocuments };

package/dist/utils/directive-parser.js

@@ -149,10 +149,11 @@ var DirectiveParser = class {
 		for (const prop of node.properties || []) {
 			if (prop.type !== "Property" || prop.key?.type !== "Identifier") continue;
 			switch (prop.key.name) {
-				case "type":
+				case "type": {
 					const typeValue = this.extractStringLiteral(prop.value);
 					if (typeValue) type = typeValue;
 					break;
+				}
 				case "defaultValue":
 					defaultValue = this.extractLiteralValue(prop.value);
 					break;
@@ -198,9 +199,10 @@ async function generateDirectiveSchemas(nitro, directives) {
 	const { resolve } = await import("pathe");
 	const directiveSchemas = [];
 	const seenDirectives = /* @__PURE__ */ new Set();
+	const parser = new DirectiveParser();
 	for (const dir of directives) for (const _imp of dir.imports) {
 		const fileContent = await readFile(dir.specifier, "utf-8");
-		const directiveDefs = await directiveParser.parseDirectives(fileContent, dir.specifier);
+		const directiveDefs = await parser.parseDirectives(fileContent, dir.specifier);
 		for (const def of directiveDefs) {
 			if (seenDirectives.has(def.name)) continue;
 			seenDirectives.add(def.name);

package/dist/utils/index.d.ts

@@ -12,5 +12,13 @@ declare function scanDirectives(nitro: Nitro): Promise<GenImport[]>;
 declare function scanTypeDefs(nitro: Nitro): Promise<string[]>;
 declare function scanSchemas(nitro: Nitro): Promise<string[]>;
 declare function scanDocs(nitro: Nitro): Promise<string[]>;
+/**
+ * Scan documents for a specific external service
+ */
+declare function scanExternalServiceDocs(nitro: Nitro, serviceName: string, patterns: string[]): Promise<string[]>;
+/**
+ * Validate external GraphQL service configuration
+ */
+declare function validateExternalServices(services: any[]): string[];
 //#endregion
-export { GLOB_SCAN_PATTERN, directiveParser, generateDirectiveSchema, generateDirectiveSchemas, getImportId, relativeWithDot, scanDirectives, scanDocs, scanGraphql, scanResolvers, scanSchemas, scanTypeDefs };
+export { GLOB_SCAN_PATTERN, directiveParser, generateDirectiveSchema, generateDirectiveSchemas, getImportId, relativeWithDot, scanDirectives, scanDocs, scanExternalServiceDocs, scanGraphql, scanResolvers, scanSchemas, scanTypeDefs, validateExternalServices };

package/dist/utils/index.js

@@ -104,7 +104,48 @@ async function scanSchemas(nitro) {
 }
 async function scanDocs(nitro) {
 	const files = await scanDir(nitro, nitro.options.rootDir, nitro.graphql.dir.client, "**/*.graphql");
-	return files.map((f) => f.fullPath);
+	return files.filter((f) => !f.path.startsWith("external/")).map((f) => f.fullPath);
+}
+/**
+* Scan documents for a specific external service
+*/
+async function scanExternalServiceDocs(nitro, serviceName, patterns) {
+	if (!patterns.length) return [];
+	const files = [];
+	for (const pattern of patterns) try {
+		const serviceFiles = await glob(pattern, {
+			cwd: nitro.options.rootDir,
+			dot: true,
+			ignore: nitro.options.ignore,
+			absolute: true
+		});
+		files.push(...serviceFiles);
+	} catch (error) {
+		nitro.logger.warn(`[graphql:${serviceName}] Error scanning documents with pattern "${pattern}":`, error);
+	}
+	return files.filter((file, index, self) => self.indexOf(file) === index);
+}
+/**
+* Validate external GraphQL service configuration
+*/
+function validateExternalServices(services) {
+	const errors = [];
+	const serviceNames = /* @__PURE__ */ new Set();
+	for (const [index, service] of services.entries()) {
+		const prefix = `externalServices[${index}]`;
+		if (!service.name || typeof service.name !== "string") errors.push(`${prefix}.name is required and must be a string`);
+		else if (serviceNames.has(service.name)) errors.push(`${prefix}.name "${service.name}" must be unique`);
+		else serviceNames.add(service.name);
+		if (!service.schema) errors.push(`${prefix}.schema is required`);
+		if (!service.endpoint || typeof service.endpoint !== "string") errors.push(`${prefix}.endpoint is required and must be a string`);
+		else try {
+			const url = new URL(service.endpoint);
+		} catch {
+			errors.push(`${prefix}.endpoint "${service.endpoint}" must be a valid URL`);
+		}
+		if (service.name && !/^[a-z]\w*$/i.test(service.name)) errors.push(`${prefix}.name "${service.name}" must be a valid identifier (letters, numbers, underscore, starting with letter)`);
+	}
+	return errors;
 }
 async function scanFiles(nitro, name, globPattern = GLOB_SCAN_PATTERN) {
 	const files = await Promise.all(nitro.options.scanDirs.map((dir) => scanDir(nitro, dir, name, globPattern))).then((r) => r.flat());
@@ -132,4 +173,4 @@ async function scanDir(nitro, dir, name, globPattern = GLOB_SCAN_PATTERN) {
 }
 
 //#endregion
-export { GLOB_SCAN_PATTERN, directiveParser, generateDirectiveSchema, generateDirectiveSchemas, getImportId, relativeWithDot, scanDirectives, scanDocs, scanGraphql, scanResolvers, scanSchemas, scanTypeDefs };
+export { GLOB_SCAN_PATTERN, directiveParser, generateDirectiveSchema, generateDirectiveSchemas, getImportId, relativeWithDot, scanDirectives, scanDocs, scanExternalServiceDocs, scanGraphql, scanResolvers, scanSchemas, scanTypeDefs, validateExternalServices };

package/dist/utils/type-generation.js

@@ -1,4 +1,4 @@
-import { generateClientTypes, loadGraphQLDocuments } from "./client-codegen.js";
+import { downloadAndSaveSchema, generateClientTypes, generateExternalClientTypes, loadExternalSchema, loadGraphQLDocuments } from "./client-codegen.js";
 import { generateTypes } from "./server-codegen.js";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import consola from "consola";
@@ -9,8 +9,27 @@ import { mergeTypeDefs } from "@graphql-tools/merge";
 import { printSchemaWithDirectives } from "@graphql-tools/utils";
 
 //#region src/utils/type-generation.ts
-function generateNuxtOfetchClient(clientDir) {
-	const ofetchPath = resolve(clientDir, "ofetch.ts");
+function generateGraphQLIndexFile(clientDir, externalServices = []) {
+	const indexPath = resolve(clientDir, "index.ts");
+	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'
+
+// Export external GraphQL services (auto-generated for existing services)
+// When you add new external services, don't forget to add their exports here:
+// export * from './yourServiceName/ofetch'
+`;
+		for (const service of externalServices) indexContent += `export * from './${service.name}/ofetch'\n`;
+		writeFileSync(indexPath, indexContent, "utf-8");
+	}
+}
+function generateNuxtOfetchClient(clientDir, serviceName = "default") {
+	const serviceDir = resolve(clientDir, serviceName);
+	const ofetchPath = resolve(serviceDir, "ofetch.ts");
+	if (!existsSync(serviceDir)) mkdirSync(serviceDir, { recursive: true });
 	if (!existsSync(ofetchPath)) {
 		const ofetchContent = `// This file is auto-generated once by nitro-graphql for quick start
 // You can modify this file according to your needs
@@ -38,6 +57,38 @@ export const $sdk = getSdk(createGraphQLClient('/api/graphql'))`;
 		writeFileSync(ofetchPath, ofetchContent, "utf-8");
 	}
 }
+function generateExternalOfetchClient(clientDir, serviceName, endpoint) {
+	const serviceDir = resolve(clientDir, serviceName);
+	const ofetchPath = resolve(serviceDir, "ofetch.ts");
+	if (!existsSync(serviceDir)) mkdirSync(serviceDir, { recursive: true });
+	if (!existsSync(ofetchPath)) {
+		const capitalizedServiceName = serviceName.charAt(0).toUpperCase() + serviceName.slice(1);
+		const ofetchContent = `// 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'
+
+export function create${capitalizedServiceName}GraphQLClient(endpoint: string = '${endpoint}'): Requester {
+  return async <R>(doc: string, vars?: any): Promise<R> => {
+    const headers = import.meta.server ? useRequestHeaders() : undefined
+
+    const result = await $fetch(endpoint, {
+      method: 'POST',
+      body: { query: doc, variables: vars },
+      headers: {
+        'Content-Type': 'application/json',
+        ...headers,
+      },
+    })
+
+    return result as R
+  }
+}
+
+export const $${serviceName}Sdk: Sdk = getSdk(create${capitalizedServiceName}GraphQLClient())`;
+		writeFileSync(ofetchPath, ofetchContent, "utf-8");
+	}
+}
 async function serverTypeGeneration(app) {
 	try {
 		const schemas = app.scanSchemas || [];
@@ -65,28 +116,101 @@ async function serverTypeGeneration(app) {
 }
 async function clientTypeGeneration(nitro) {
 	try {
-		const docs = nitro.scanDocuments;
-		const loadDocs = await loadGraphQLDocuments(docs);
-		const schemaFilePath = join(nitro.graphql.buildDir, "schema.graphql");
-		if (!existsSync(schemaFilePath)) {
-			consola.info("Schema file not ready yet for client type generation. Server types need to be generated first.");
-			return;
-		}
-		const graphqlString = readFileSync(schemaFilePath, "utf-8");
-		const schema = buildSchema(graphqlString);
-		const types = await generateClientTypes(schema, 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 sdkTypesPath = resolve(nitro.graphql.clientDir, "sdk.ts");
-		mkdirSync(dirname(clientTypesPath), { recursive: true });
-		writeFileSync(clientTypesPath, types.types, "utf-8");
-		mkdirSync(dirname(sdkTypesPath), { recursive: true });
-		writeFileSync(sdkTypesPath, types.sdk, "utf-8");
-		if (nitro.options.framework?.name === "nuxt") generateNuxtOfetchClient(nitro.graphql.clientDir);
+		await generateMainClientTypes(nitro);
+		if (nitro.options.graphql?.externalServices?.length) await generateExternalServicesTypes(nitro);
 	} catch (error) {
 		consola.error("Client schema generation error:", error);
 	}
 }
+/**
+* Check for old structure files and warn user about manual migration
+*/
+function checkOldStructure(clientDir) {
+	const oldOfetchPath = resolve(clientDir, "ofetch.ts");
+	const oldSdkPath = resolve(clientDir, "sdk.ts");
+	if (existsSync(oldOfetchPath) || existsSync(oldSdkPath)) {
+		const foundFiles = [];
+		if (existsSync(oldOfetchPath)) foundFiles.push("app/graphql/ofetch.ts");
+		if (existsSync(oldSdkPath)) foundFiles.push("app/graphql/sdk.ts");
+		consola.error(`⚠️  OLD GRAPHQL STRUCTURE DETECTED!
+
+📁 Found old files in app/graphql/ directory that need to be moved:
+   • ${foundFiles.join("\n   • ")}
+
+🔄 Please manually move these files to the new structure:
+   • app/graphql/ofetch.ts → app/graphql/default/ofetch.ts
+   • app/graphql/sdk.ts → app/graphql/default/sdk.ts
+
+📝 Also update your app/graphql/index.ts to include:
+   export * from './default/ofetch'
+
+💡 After moving, update your imports to use:
+   import { $sdk } from "#graphql/client"
+
+🚫 The old files will cause import conflicts until moved!`);
+	}
+}
+async function generateMainClientTypes(nitro) {
+	checkOldStructure(nitro.graphql.clientDir);
+	const docs = nitro.scanDocuments;
+	const loadDocs = await loadGraphQLDocuments(docs);
+	const schemaFilePath = join(nitro.graphql.buildDir, "schema.graphql");
+	if (!existsSync(schemaFilePath)) {
+		consola.info("Schema file not ready yet for client type generation. Server types need to be generated first.");
+		return;
+	}
+	const graphqlString = readFileSync(schemaFilePath, "utf-8");
+	const schema = buildSchema(graphqlString);
+	const types = await generateClientTypes(schema, 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");
+	if (nitro.options.framework?.name === "nuxt") {
+		generateNuxtOfetchClient(nitro.graphql.clientDir, "default");
+		const externalServices = nitro.options.graphql?.externalServices || [];
+		generateGraphQLIndexFile(nitro.graphql.clientDir, externalServices);
+	}
+}
+async function generateExternalServicesTypes(nitro) {
+	const externalServices = nitro.options.graphql?.externalServices || [];
+	for (const service of externalServices) try {
+		consola.info(`[graphql:${service.name}] Processing external service`);
+		await downloadAndSaveSchema(service, nitro.options.buildDir);
+		const schema = await loadExternalSchema(service, nitro.options.buildDir);
+		if (!schema) {
+			consola.warn(`[graphql:${service.name}] Failed to load schema, skipping`);
+			continue;
+		}
+		const documentPatterns = service.documents || [];
+		let loadDocs = [];
+		if (documentPatterns.length > 0) try {
+			loadDocs = await loadGraphQLDocuments(documentPatterns);
+		} catch (error) {
+			consola.warn(`[graphql:${service.name}] No documents found:`, error);
+		}
+		const types = await generateExternalClientTypes(service, schema, loadDocs);
+		if (types === false) {
+			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);
+		consola.success(`[graphql:${service.name}] External service types generated successfully`);
+	} catch (error) {
+		consola.error(`[graphql:${service.name}] External service generation failed:`, error);
+	}
+}
 
 //#endregion
 export { clientTypeGeneration, serverTypeGeneration };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "nitro-graphql",
   "type": "module",
-  "version": "1.1.3",
+  "version": "1.2.0",
   "description": "GraphQL integration for Nitro",
   "license": "MIT",
   "sideEffects": false,
@@ -72,6 +72,7 @@
     "@graphql-tools/load-files": "^7.0.1",
     "@graphql-tools/merge": "^9.1.0",
     "@graphql-tools/schema": "^10.0.24",
+    "@graphql-tools/url-loader": "^8.0.33",
     "@graphql-tools/utils": "^10.9.0",
     "chokidar": "^4.0.3",
     "consola": "^3.4.2",
@@ -88,8 +89,8 @@
     "@antfu/eslint-config": "^4.17.0",
     "@apollo/server": "^5.0.0",
     "@graphql-codegen/import-types-preset": "^3.0.1",
-    "@nuxt/kit": "4.0.0-rc.0",
-    "@nuxt/schema": "4.0.0-rc.0",
+    "@nuxt/kit": "^4.0.3",
+    "@nuxt/schema": "^4.0.3",
     "@types/node": "^20.19.9",
     "bumpp": "^10.2.0",
     "changelogen": "^0.6.2",