feat: Multi-Service GraphQL Support with Default Folder Organization & Schema Caching (#23)

* feat: add multi-service GraphQL support with folder-based organization

• Add support for multiple external GraphQL services
• Implement folder-based organization (default/, serviceName/)
• Generate service-specific SDKs and type definitions
• Add validation for external service configurations
• Update Nuxt module to support TypeScript path mappings for external services
• Create centralized index.ts for automatic exports
• Migrate context.d.ts to context.ts with warning system
• Add @graphql-tools/url-loader for remote schema loading

* docs: update README with multi-service support and remove external README

• Add multi-service support feature to main README features list
• Remove redundant external/README.md file
• Keep documentation centralized in main README

* fix: resolve ESLint no-new error in URL validation

- Assign new URL() result to variable instead of using for side effects
- Add void operator to explicitly indicate validation-only usage

* feat: add multi-service GraphQL support and update pnpm workspace dependencies

* feat: add check for old GraphQL structure and provide migration instructions

* fix: improve formatting in checkOldStructure function for better readability

* feat: add schema download modes and optimize build performance

- Add flexible download modes: 'once', 'always', 'manual', boolean
- 'once' mode: Download only if file doesn't exist (offline-friendly)
- 'always' mode: Check for updates on every build (previous behavior)
- 'manual' mode: User manages schema files manually
- Rename schemaPath to downloadPath for clarity
- Store downloaded schemas in .nitro/graphql/schemas/ directory
- Improve build performance by avoiding unnecessary network requests
- Add comprehensive documentation with usage examples

This optimizes build performance while providing flexibility for different
development workflows and deployment scenarios.

* fix: improve documentation formatting for schema download options

* feat: add GraphQL queries and mutations for countries and users

* feat: add optional GraphQL configuration for IDE support and service-specific validation

* chore: implement GraphQL client and SDK with context definition

Author: productdevbook

README.md

@@ -30,6 +30,7 @@
 - 🔄 **Hot Reload**: Development mode with automatic schema and resolver updates
 - 📦 **Optimized Bundling**: Smart chunking and dynamic imports for production
 - 🌐 **Nuxt Integration**: First-class Nuxt.js support with dedicated module
+- 🔗 **Multi-Service Support**: Connect to multiple external GraphQL APIs alongside your main server
 
 ## 🎯 Used Projects
 
@@ -1115,6 +1116,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.json

@@ -83,6 +83,7 @@
     "@graphql-tools/load-files": "catalog:",
     "@graphql-tools/merge": "catalog:",
     "@graphql-tools/schema": "catalog:",
+    "@graphql-tools/url-loader": "catalog:",
     "@graphql-tools/utils": "catalog:",
     "chokidar": "catalog:",
     "consola": "catalog:",

playground-nuxt/app/graphql/countries/countries.graphql

@@ -0,0 +1,30 @@
+query GetCountries {
+  countries {
+    code
+    name
+    emoji
+    continent {
+      name
+    }
+  }
+}
+
+query GetCountry($code: ID!) {
+  country (code: $code) {
+    code
+    name
+    emoji
+    phone
+    capital
+    currency
+    native
+    continent {
+      name
+      code
+    }
+    languages {
+      name
+      code
+    }
+  }
+}

playground-nuxt/app/graphql/countries/ofetch.ts

@@ -0,0 +1,23 @@
+// This file is auto-generated once by nitro-graphql for quick start
+// You can modify this file according to your needs
+import type { Requester, Sdk } from './sdk'
+import { getSdk } from './sdk'
+
+export function createCountriesGraphQLClient(endpoint: string = 'https://countries.trevorblades.com'): 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 $countriesSdk: Sdk = getSdk(createCountriesGraphQLClient())

playground-nuxt/app/graphql/countries/sdk.ts

@@ -0,0 +1,54 @@
+// THIS FILE IS GENERATED, DO NOT EDIT!
+/* eslint-disable eslint-comments/no-unlimited-disable */
+/* tslint:disable */
+/* eslint-disable */
+/* prettier-ignore */
+import type * as Types from '#graphql/client/countries';
+
+import type { ExecutionResult } from 'graphql';
+
+export const GetCountriesDocument = /*#__PURE__*/ `
+    query GetCountries {
+  countries {
+    code
+    name
+    emoji
+    continent {
+      name
+    }
+  }
+}
+    `;
+export const GetCountryDocument = /*#__PURE__*/ `
+    query GetCountry($code: ID!) {
+  country(code: $code) {
+    code
+    name
+    emoji
+    phone
+    capital
+    currency
+    native
+    continent {
+      name
+      code
+    }
+    languages {
+      name
+      code
+    }
+  }
+}
+    `;
+export type Requester<C = {}, E = unknown> = <R, V>(doc: string, vars?: V, options?: C) => Promise<ExecutionResult<R, E>> | AsyncIterable<ExecutionResult<R, E>>
+export function getSdk<C, E>(requester: Requester<C, E>) {
+  return {
+    GetCountries(variables?: Types.GetCountriesQueryVariables, options?: C): Promise<ExecutionResult<Types.GetCountriesQuery, E>> {
+      return requester<Types.GetCountriesQuery, Types.GetCountriesQueryVariables>(GetCountriesDocument, variables, options) as Promise<ExecutionResult<Types.GetCountriesQuery, E>>;
+    },
+    GetCountry(variables: Types.GetCountryQueryVariables, options?: C): Promise<ExecutionResult<Types.GetCountryQuery, E>> {
+      return requester<Types.GetCountryQuery, Types.GetCountryQueryVariables>(GetCountryDocument, variables, options) as Promise<ExecutionResult<Types.GetCountryQuery, E>>;
+    }
+  };
+}
+export type Sdk = ReturnType<typeof getSdk>;

playground-nuxt/app/graphql/mutations.graphql renamed to playground-nuxt/app/graphql/default/mutations.graphql

@@ -0,0 +1,10 @@
+// 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'
+export * from './countries/ofetch'
+
+// 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'