nitro-graphql 0.0.23 → 0.1.0

package/README.md

@@ -1,60 +1,107 @@
-# Nitro GraphQL Yoga Module
+# Nitro GraphQL
+
+<div align="center">
+
+[![npm version][npm-version-src]][npm-version-href]
+[![npm downloads][npm-downloads-src]][npm-downloads-href]
+[![bundle][bundle-src]][bundle-href]
+[![License][license-src]][license-href]
+
+**A standalone Nitro module that integrates GraphQL servers into any Nitro application with automatic type generation, file watching, and seamless framework integration.**
+
+[🚀 Quick Start](#-quick-start) • [📖 Documentation](#-documentation) • [🎮 Playground](#-playground) • [💬 Community](#-community--contributing)
+
+</div>
+
+---
 
 > [!NOTE]
 > This project is actively under development. We're always open to new ideas, different perspectives, and feature suggestions! If you have a suggestion, please first [open an issue](https://github.com/productdevbook/nitro-graphql/issues) to discuss it, then you can contribute with a PR.
 
-A standalone Nitro module that integrates GraphQL Yoga server into any Nitro application with automatic type generation and file watching.
+## ✨ Features
+
+- 🚀 **Multi-Framework Support**: Works with GraphQL Yoga and Apollo Server
+- 🔧 **Auto-Discovery**: Automatically scans and loads GraphQL schema and resolver files
+- 📝 **Type Generation**: Automatic TypeScript type generation from GraphQL schemas (server & client)
+- 🎮 **Apollo Sandbox**: Built-in GraphQL playground for development
+- 🏥 **Health Check**: Built-in health check endpoint
+- 🔌 **Universal Compatibility**: Works with any Nitro-based application (Nuxt, standalone Nitro, etc.)
+- 🎯 **Zero Configuration**: Sensible defaults with optional customization
+- 📂 **File-Based Organization**: Domain-driven resolver and schema organization
+- 🔄 **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
 
-## Features
+## 🚀 Quick Start
 
-- 🚀 Easy GraphQL server setup with GraphQL Yoga
-- 🔧 Auto-discovery of GraphQL schema and resolver files
-- 📝 Automatic TypeScript type generation from GraphQL schemas
-- 🎮 Apollo Sandbox integration (instead of GraphiQL)
-- 🏥 Built-in health check endpoint
-- 💾 Configurable cache headers for better performance
-- 🔌 Works with any Nitro-based application
-- 🎯 Zero-config with sensible defaults
-- 📂 File-based resolver organization
-- 🔄 Hot reload in development mode
-- 📦 Optimized bundle size with dynamic imports
-- 🏷️ Minimal logging with consistent tagging
+### Step 1: Installation
 
-## Installation
+Choose your preferred package manager:
 
 ```bash
+# npm
 npm install nitro-graphql
-# or
+
+# pnpm (recommended)
 pnpm add nitro-graphql
-# or
+
+# yarn
 yarn add nitro-graphql
 ```
 
-## Usage
+### Step 2: Setup Your Project
 
-### 1. Add the module to your Nitro config
+<details>
+<summary>🔧 <strong>For Standalone Nitro Projects</strong></summary>
 
+1. **Update your `nitro.config.ts`:**
 ```ts
-// nitro.config.ts
 import { defineNitroConfig } from 'nitropack/config'
 
 export default defineNitroConfig({
   modules: ['nitro-graphql'],
+  graphql: {
+    framework: 'graphql-yoga', // or 'apollo-server'
+  },
+})
+```
 
-  // Optional configuration
-  graphqlYoga: {
-    endpoint: '/api/graphql', // default
-    playground: true, // default (Apollo Sandbox)
-    cors: false, // default
-  }
+2. **Create the GraphQL directory structure:**
+```bash
+mkdir -p server/graphql
+```
+
+</details>
+
+<details>
+<summary>🟢 <strong>For Nuxt.js Projects</strong></summary>
+
+1. **Update your `nuxt.config.ts`:**
+```ts
+export default defineNuxtConfig({
+  modules: [
+    'nitro-graphql/nuxt',
+  ],
+  nitro: {
+    modules: ['nitro-graphql'],
+    graphql: {
+      framework: 'graphql-yoga',
+    },
+  },
 })
 ```
 
-### 2. Create your GraphQL schema files
+2. **Create the GraphQL directory structure:**
+```bash
+mkdir -p server/graphql
+```
+
+</details>
+
+### Step 3: Create Your First Schema
 
-The module automatically scans for GraphQL files in your `graphql/` directory using a domain-driven structure:
+Create your main schema file:
 
-#### Main Schema File
 ```graphql
 # server/graphql/schema.graphql
 scalar DateTime
@@ -68,7 +115,79 @@ type Query {
 type Mutation
 ```
 
-#### Domain-specific Schema Files
+### Step 4: Create Your First Resolver
+
+Create a resolver for your queries:
+
+```ts
+// server/graphql/hello.resolver.ts
+import { defineResolver } from 'nitro-graphql/utils/define'
+
+export const helloResolver = defineResolver({
+  Query: {
+    hello: () => 'Hello from GraphQL!',
+    greeting: (_, { name }) => `Hello, ${name}!`,
+  },
+})
+
+// You can also export multiple resolvers from the same file
+export const additionalResolver = defineResolver({
+  Query: {
+    // Additional query resolvers
+  },
+})
+```
+
+### Step 5: Start Your Server
+
+```bash
+# For Nitro
+pnpm dev
+
+# For Nuxt
+pnpm dev
+```
+
+### Step 6: Test Your GraphQL API
+
+🎉 **That's it!** Your GraphQL server is now running at:
+
+- **GraphQL Endpoint**: `http://localhost:3000/api/graphql`
+- **Apollo Sandbox**: `http://localhost:3000/api/graphql` (in browser)
+- **Health Check**: `http://localhost:3000/api/graphql/health`
+
+## 📖 Documentation
+
+### Project Structure
+
+The module uses a domain-driven file structure under `server/graphql/`:
+
+```
+server/
+├── graphql/
+│   ├── schema.graphql              # Main schema with scalars and base types
+│   ├── hello.resolver.ts           # Global resolvers (use named exports)
+│   ├── users/
+│   │   ├── user.graphql           # User schema definitions
+│   │   ├── user-queries.resolver.ts # User query resolvers (use named exports)
+│   │   └── create-user.resolver.ts  # User mutation resolvers (use named exports)
+│   ├── posts/
+│   │   ├── post.graphql           # Post schema definitions
+│   │   ├── post-queries.resolver.ts # Post query resolvers (use named exports)
+│   │   └── create-post.resolver.ts  # Post mutation resolvers (use named exports)
+│   └── config.ts                   # Optional GraphQL configuration
+```
+
+> [!TIP]
+> **New Named Export Pattern**: The module now supports named exports for GraphQL resolvers, allowing you to export multiple resolvers from a single file. This provides better organization and flexibility in structuring your resolver code.
+
+### Building Your First Feature
+
+Let's create a complete user management feature:
+
+<details>
+<summary>👤 <strong>Step 1: Define User Schema</strong></summary>
+
 ```graphql
 # server/graphql/users/user.graphql
 type User {
@@ -93,267 +212,483 @@ extend type Mutation {
 }
 ```
 
-#### Domain-based Resolver Files
+</details>
+
+<details>
+<summary>🔍 <strong>Step 2: Create Query Resolvers</strong></summary>
+
 ```ts
-// server/graphql/users/user-queries.ts
-import { defineResolver } from 'nitro-graphql'
+// server/graphql/users/user-queries.resolver.ts
+import { defineQuery } from 'nitro-graphql/utils/define'
 
-export default defineResolver({
-  Query: {
-    users: async (_, __, { storage }) => {
-      return await storage.getItem('users') || []
-    },
-    user: async (_, { id }, { storage }) => {
-      const users = await storage.getItem('users') || []
-      return users.find(user => user.id === id)
-    }
+export const userQueries = defineQuery({
+  users: async (_, __, { storage }) => {
+    return await storage.getItem('users') || []
+  },
+  user: async (_, { id }, { storage }) => {
+    const users = await storage.getItem('users') || []
+    return users.find(user => user.id === id)
   }
 })
+
+// You can also split queries into separate named exports
+export const additionalUserQueries = defineQuery({
+  userCount: async (_, __, { storage }) => {
+    const users = await storage.getItem('users') || []
+    return users.length
+  },
+})
 ```
 
-```ts
-// server/graphql/users/create-user.ts
-import { defineResolver } from 'nitro-graphql'
+</details>
 
-export default defineResolver({
-  Mutation: {
-    createUser: async (_, { input }, { storage }) => {
-      const users = await storage.getItem('users') || []
-      const user = {
-        id: Date.now().toString(),
-        ...input,
-        createdAt: new Date()
-      }
-      users.push(user)
-      await storage.setItem('users', users)
-      return user
+<details>
+<summary>✏️ <strong>Step 3: Create Mutation Resolvers</strong></summary>
+
+```ts
+// server/graphql/users/create-user.resolver.ts
+import { defineMutation } from 'nitro-graphql/utils/define'
+
+export const createUserMutation = defineMutation({
+  createUser: async (_, { input }, { storage }) => {
+    const users = await storage.getItem('users') || []
+    const user = {
+      id: Date.now().toString(),
+      ...input,
+      createdAt: new Date()
     }
+    users.push(user)
+    await storage.setItem('users', users)
+    return user
+  }
+})
+
+// You can also export multiple mutations from the same file
+export const updateUserMutation = defineMutation({
+  updateUser: async (_, { id, input }, { storage }) => {
+    const users = await storage.getItem('users') || []
+    const userIndex = users.findIndex(user => user.id === id)
+    if (userIndex === -1)
+      throw new Error('User not found')
+
+    users[userIndex] = { ...users[userIndex], ...input }
+    await storage.setItem('users', users)
+    return users[userIndex]
   }
 })
 ```
 
-### 3. Using the utilities
+</details>
 
-The module provides utilities for better developer experience:
+<details>
+<summary>🧪 <strong>Step 4: Test Your Feature</strong></summary>
 
-```ts
-// server/graphql/hello.ts
-import { defineResolver } from 'nitro-graphql'
+Open Apollo Sandbox at `http://localhost:3000/api/graphql` and try:
 
-export default defineResolver({
-  Query: {
-    hello: () => 'Hello World!',
-    greeting: (_, { name }) => `Hello ${name}!`
+```graphql
+# Create a user
+mutation {
+  createUser(input: {
+    name: "John Doe"
+    email: "john@example.com"
+  }) {
+    id
+    name
+    email
+    createdAt
   }
-})
+}
+
+# Query users
+query {
+  users {
+    id
+    name
+    email
+  }
+}
 ```
 
-### 4. Type Generation
+</details>
 
-The module automatically generates TypeScript types from your GraphQL schema:
+### Type Generation
 
-- **Server types**: `.nitro/types/graphql-types.generated.ts`
-- **Type declarations**: `.nitro/types/graphql.d.ts`
+The module automatically generates TypeScript types for you:
 
-These types are automatically available in your resolvers:
+- **Server types**: `.nitro/types/nitro-graphql-server.d.ts`
+- **Client types**: `.nitro/types/nitro-graphql-client.d.ts`
+- **Auto-imports**: Available for `defineResolver` and other utilities
 
-```ts
-import type { QueryResolvers } from '#graphql/server'
-// server/graphql/users/user-queries.ts
-import { defineResolver } from 'nitro-graphql'
+Your IDE will automatically provide type safety and autocomplete!
 
-export default defineResolver({
-  Query: {
-    users: async (_, __, { storage }): Promise<User[]> => {
-      return await storage.getItem('users') || []
+> [!TIP]
+> **Nitro Auto-Imports**: Thanks to Nitro's auto-import feature, you don't need to manually import `defineResolver`, `defineQuery`, `defineMutation`, and other utilities in your resolver files. They're available globally! However, if you prefer explicit imports, you can use:
+> ```ts
+> import { defineResolver } from 'nitro-graphql/utils/define'
+> ```
+
+### Configuration
+
+<details>
+<summary>⚙️ <strong>Runtime Configuration</strong></summary>
+
+```ts
+// nitro.config.ts
+export default defineNitroConfig({
+  modules: ['nitro-graphql'],
+  graphql: {
+    framework: 'graphql-yoga', // or 'apollo-server'
+  },
+  runtimeConfig: {
+    graphql: {
+      endpoint: {
+        graphql: '/api/graphql', // GraphQL endpoint
+        healthCheck: '/api/graphql/health' // Health check endpoint
+      },
+      playground: true, // Enable Apollo Sandbox
     }
-  } satisfies QueryResolvers
+  }
 })
 ```
 
-## File Structure
+</details>
 
-The module follows a domain-driven file structure:
+<details>
+<summary>🔧 <strong>Advanced Configuration</strong></summary>
 
-```
-server/
-├── graphql/
-│   ├── schema.graphql           # Main schema file with scalars and base types
-│   ├── hello.ts                 # Global resolvers
-│   ├── users/
-│   │   ├── user.graphql         # User schema definitions
-│   │   ├── user-queries.ts      # User query resolvers
-│   │   └── create-user.ts       # User mutation resolvers
-│   ├── todos/
-│   │   ├── todo.graphql         # Todo schema definitions
-│   │   ├── todo-queries.ts      # Todo query resolvers
-│   │   └── todo-mutations.ts    # Todo mutation resolvers
-│   ├── posts/
-│   │   ├── post.graphql         # Post schema definitions
-│   │   ├── post-queries.ts      # Post query resolvers
-│   │   └── create-post.ts       # Post mutation resolvers
-│   └── comments/
-│       ├── comment.graphql      # Comment schema definitions
-│       ├── comment-queries.ts   # Comment query resolvers
-│       └── add-comment.ts       # Comment mutation resolvers
+```ts
+// server/graphql/config.ts
+import { defineGraphQLConfig } from 'nitro-graphql/utils/define'
+
+export default defineGraphQLConfig({
+  // Custom GraphQL Yoga or Apollo Server configuration
+  plugins: [
+    // Add custom plugins
+  ],
+  context: async ({ request }) => {
+    // Enhanced context with custom properties
+    return {
+      user: await authenticateUser(request),
+      db: await connectDatabase(),
+    }
+  },
+})
 ```
 
-## Context
+</details>
 
-The GraphQL context includes:
-- `event`: The H3 event object
-- `request`: The original request object
-- `storage`: Nitro storage instance
+## 🎮 Playground
+
+Try out the examples:
+
+- **Standalone Nitro**: [`playground/`](playground/)
+- **Nuxt.js Integration**: [`playground-nuxt/`](playground-nuxt/)
+
+Both examples include working GraphQL schemas, resolvers, and demonstrate the module's capabilities.
+
+## 🔧 API Reference
+
+### Core Utilities
+
+> [!NOTE]
+> **Auto-Import Available**: All utilities are automatically imported in your resolver files thanks to Nitro's auto-import feature. You can use them directly without import statements, or use explicit imports if you prefer:
+> ```ts
+> import { defineMutation, defineQuery, defineResolver } from 'nitro-graphql/utils/define'
+> ```
+
+> [!IMPORTANT]
+> **Named Exports Required**: All GraphQL resolvers must now use named exports instead of default exports. This allows you to export multiple resolvers from a single file, providing better organization and flexibility. For example:
+> ```ts
+> // ✅ Correct - Named exports
+> export const userQueries = defineQuery({ ... })
+> export const userMutations = defineMutation({ ... })
+> 
+> // ❌ Incorrect - Default exports (deprecated)
+> export default defineQuery({ ... })
+> ```
+
+<details>
+<summary><strong>defineResolver</strong> - Define complete resolvers</summary>
 
 ```ts
-// Example resolver with full context usage
-import { defineResolver } from 'nitro-graphql'
+import { defineResolver } from 'nitro-graphql/utils/define'
 
-export default defineResolver({
+export const mainResolver = defineResolver({
   Query: {
-    currentUser: async (_, __, { event, request, storage }) => {
-      const token = getCookie(event, 'auth-token')
-      const userAgent = getHeader(event, 'user-agent')
+    // Query resolvers
+  },
+  Mutation: {
+    // Mutation resolvers
+  },
+  // Custom type resolvers
+})
 
-      if (!token) {
-        throw new Error('Unauthorized')
-      }
+// You can also export multiple resolvers from the same file
+export const additionalResolver = defineResolver({
+  Query: {
+    // Additional query resolvers
+  },
+})
+```
 
-      const userId = await verifyToken(token)
-      return await storage.getItem(`user:${userId}`)
-    }
+</details>
+
+<details>
+<summary><strong>defineQuery</strong> - Define only Query resolvers</summary>
+
+```ts
+import { defineQuery } from 'nitro-graphql/utils/define'
+
+export const userQueries = defineQuery({
+  users: async (_, __, { storage }) => {
+    return await storage.getItem('users') || []
+  },
+  user: async (_, { id }, { storage }) => {
+    const users = await storage.getItem('users') || []
+    return users.find(user => user.id === id)
   }
 })
+
+// You can also split queries into separate named exports
+export const userStatsQueries = defineQuery({
+  userCount: async (_, __, { storage }) => {
+    const users = await storage.getItem('users') || []
+    return users.length
+  },
+})
 ```
 
-## Configuration Options
+</details>
+
+<details>
+<summary><strong>defineMutation</strong> - Define only Mutation resolvers</summary>
 
 ```ts
-interface NitroGraphQLYogaOptions {
-  // GraphQL endpoint path
-  endpoint?: string // default: '/api/graphql'
-
-  // Enable/disable Apollo Sandbox
-  playground?: boolean // default: true
-
-  // CORS configuration
-  cors?: boolean | {
-    origin?: string | string[] | boolean
-    credentials?: boolean
-    methods?: string[]
+import { defineMutation } from 'nitro-graphql/utils/define'
+
+export const userMutations = defineMutation({
+  createUser: async (_, { input }, { storage }) => {
+    const users = await storage.getItem('users') || []
+    const user = {
+      id: Date.now().toString(),
+      ...input,
+      createdAt: new Date()
+    }
+    users.push(user)
+    await storage.setItem('users', users)
+    return user
   }
+})
 
-  // Client type generation
-  client?: {
-    enabled?: boolean // default: false
-    outputPath?: string // default: buildDir/types/graphql-client.generated.ts
-    watchPatterns?: string[] // default: src/**/*.{graphql,gql} excluding server/graphql
-    config?: {
-      documentMode?: 'string' | 'graphQLTag'
-      emitLegacyCommonJSImports?: boolean
-      useTypeImports?: boolean
-      enumsAsTypes?: boolean
-    }
+// You can also export multiple mutations from the same file
+export const userUpdateMutations = defineMutation({
+  updateUser: async (_, { id, input }, { storage }) => {
+    const users = await storage.getItem('users') || []
+    const userIndex = users.findIndex(user => user.id === id)
+    if (userIndex === -1)
+      throw new Error('User not found')
+
+    users[userIndex] = { ...users[userIndex], ...input }
+    await storage.setItem('users', users)
+    return users[userIndex]
   }
-}
+})
 ```
 
-## Development Features
+</details>
 
-### Hot Reload
-The module watches for changes in your GraphQL files and automatically:
-- Regenerates TypeScript types
-- Reloads the GraphQL schema
-- Updates resolvers
+<details>
+<summary><strong>defineSubscription</strong> - Define Subscription resolvers</summary>
 
-### Bundle Optimization
-- Uses dynamic imports to prevent bundling large codegen dependencies
-- Optimized chunk organization for better caching
-- Minimal logging output with consistent `[graphql]` tagging
-
-### Health Check
-Access the health check endpoint at `/api/graphql/health` to verify your GraphQL server status.
+```ts
+import { defineSubscription } from 'nitro-graphql/utils/define'
 
-## Advanced Usage
+export const userSubscriptions = defineSubscription({
+  userAdded: {
+    subscribe: () => pubsub.asyncIterator('USER_ADDED'),
+  },
+  postUpdated: {
+    subscribe: withFilter(
+      () => pubsub.asyncIterator('POST_UPDATED'),
+      (payload, variables) => payload.postUpdated.id === variables.postId
+    ),
+  }
+})
 
-### Custom GraphQL Yoga Configuration
+// You can also export multiple subscriptions from the same file
+export const notificationSubscriptions = defineSubscription({
+  notificationAdded: {
+    subscribe: () => pubsub.asyncIterator('NOTIFICATION_ADDED'),
+  },
+})
+```
 
-You can create a custom GraphQL Yoga configuration file that will be automatically merged with the default configuration. The module will look for this file **only in the `server/graphql/` directory**:
+</details>
 
-- `server/graphql/yoga.config.ts`
+<details>
+<summary><strong>defineType</strong> - Define custom type resolvers</summary>
 
 ```ts
-import { useCORS } from '@graphql-yoga/plugin-cors'
-import { useResponseCache } from '@graphql-yoga/plugin-response-cache'
-// server/graphql/yoga.config.ts
-import { defineYogaConfig } from 'nitro-graphql'
-
-export default defineYogaConfig({
-  // Add custom plugins
-  plugins: [
-    useCORS({
-      origin: process.env.NODE_ENV === 'production' ? 'https://yourdomain.com' : '*',
-      credentials: true,
-    }),
-    useResponseCache({
-      session: () => null,
-      ttl: 60_000, // 1 minute
-    }),
-  ],
-
-  // Enhanced context with custom properties
-  context: async ({ request }) => {
-    const event = request.$$event
+import { defineType } from 'nitro-graphql/utils/define'
 
-    return {
-      event,
-      request,
-      storage: useStorage(),
-      // Add custom context properties
-      user: await authenticateUser(event),
-      db: await connectDatabase(),
-      startTime: Date.now(),
-    }
+export const userTypes = defineType({
+  User: {
+    posts: async (parent, _, { storage }) => {
+      const posts = await storage.getItem('posts') || []
+      return posts.filter(post => post.authorId === parent.id)
+    },
+    fullName: parent => `${parent.firstName} ${parent.lastName}`,
   },
+})
 
-  // Custom error handling
-  maskedErrors: {
-    maskError: (error, message, isDev) => {
-      if (error.message.startsWith('USER_')) {
-        return error // Don't mask user-facing errors
-      }
-      return isDev ? error : new Error('Internal server error')
+// You can also export multiple type resolvers from the same file
+export const postTypes = defineType({
+  Post: {
+    author: async (parent, _, { storage }) => {
+      const users = await storage.getItem('users') || []
+      return users.find(user => user.id === parent.authorId)
     },
   },
+})
+```
+
+</details>
 
-  // Additional yoga options
-  // See: https://the-guild.dev/graphql/yoga-server/docs
+<details>
+<summary><strong>defineSchema</strong> - Define custom schema with validation</summary>
+
+You can override schema types if needed. StandardSchema supported — Zod, Valibot, anything works:
+
+```ts
+import { defineSchema } from 'nitro-graphql/utils/define'
+import { z } from 'zod'
+
+export default defineSchema({
+  Todo: z.object({
+    id: z.string(),
+    title: z.string(),
+    completed: z.boolean(),
+    createdAt: z.date(),
+  }),
+  User: z.object({
+    id: z.string(),
+    name: z.string(),
+    email: z.string().email(),
+    age: z.number().min(0),
+  }),
 })
 ```
 
-**Configuration Merging**: Your custom config is merged with the default config, allowing you to override specific options while keeping defaults for others. The `schema` and `graphqlEndpoint` are always preserved from the module's configuration.
+**With Drizzle Schema:**
+```ts
+import { defineSchema } from 'nitro-graphql/utils/define'
+import { z } from 'zod'
+import { userSchema } from './drizzle/user'
+
+export default defineSchema({
+  Todo: z.object({
+    id: z.string(),
+    title: z.string(),
+  }),
+  User: userSchema, // Import from Drizzle schema
+})
+```
+
+</details>
+
+## 🚨 Troubleshooting
+
+<details>
+<summary><strong>Common Issues</strong></summary>
+
+### GraphQL endpoint returns 404
+
+**Solution**: Make sure you have:
+1. Added `nitro-graphql` to your modules
+2. Set the `graphql.framework` option
+3. Created at least one schema file
+
+### Types not generating
+
+**Solution**:
+1. Restart your dev server
+2. Check that your schema files end with `.graphql`
+3. Verify your resolver files end with `.resolver.ts`
+
+### Hot reload not working
+
+**Solution**:
+1. Make sure you're in development mode
+2. Check file naming conventions
+3. Restart the dev server
+
+### Import errors with utilities
+
+**Solution**:
+```ts
+// ❌ Incorrect import path
+import { defineResolver } from 'nitro-graphql'
+
+// ✅ Correct import path
+import { defineResolver } from 'nitro-graphql/utils/define'
+```
+
+### Export pattern errors
+
+**Solution**:
+```ts
+// ❌ Incorrect - Default exports (deprecated)
+export default defineResolver({ ... })
+
+// ✅ Correct - Named exports
+export const myResolver = defineResolver({ ... })
+export const anotherResolver = defineResolver({ ... })
+```
+
+</details>
 
-### Client Type Generation
+## 🌟 Framework Support
 
-Enable client type generation for your frontend queries:
+<details>
+<summary><strong>GraphQL Yoga</strong></summary>
 
 ```ts
 // nitro.config.ts
 export default defineNitroConfig({
-  graphqlYoga: {
-  }
+  graphql: {
+    framework: 'graphql-yoga',
+  },
 })
 ```
 
-### Custom Scalars
+</details>
+
+<details>
+<summary><strong>Apollo Server</strong></summary>
 
 ```ts
+// nitro.config.ts
+export default defineNitroConfig({
+  graphql: {
+    framework: 'apollo-server',
+  },
+})
+```
+
+</details>
+
+## 🔥 Advanced Features
+
+<details>
+<summary><strong>Custom Scalars</strong></summary>
+
+```ts
+// server/graphql/scalars/DateTime.resolver.ts
 import { GraphQLScalarType } from 'graphql'
 import { Kind } from 'graphql/language'
-// server/graphql/scalars/DateTime.ts
-import { defineResolver } from 'nitro-graphql'
+import { defineResolver } from 'nitro-graphql/utils/define'
 
-export default defineResolver({
+export const dateTimeScalar = defineResolver({
   DateTime: new GraphQLScalarType({
     name: 'DateTime',
     serialize: (value: Date) => value.toISOString(),
@@ -366,47 +701,282 @@ export default defineResolver({
     }
   })
 })
+
+// You can also export multiple scalars from the same file
+export const jsonScalar = defineResolver({
+  JSON: new GraphQLScalarType({
+    name: 'JSON',
+    serialize: value => value,
+    parseValue: value => value,
+    parseLiteral: (ast) => {
+      if (ast.kind === Kind.STRING) {
+        return JSON.parse(ast.value)
+      }
+      return null
+    }
+  })
+})
 ```
 
-### Error Handling
+</details>
 
-```ts
-// server/graphql/users/user-queries.ts
-import { defineResolver } from 'nitro-graphql'
+<details>
+<summary><strong>Error Handling</strong></summary>
 
-export default defineResolver({
-  Query: {
-    user: async (_, { id }, { storage }) => {
-      try {
-        const user = await storage.getItem(`user:${id}`)
-        if (!user) {
-          throw new Error(`User with id ${id} not found`)
-        }
-        return user
-      }
-      catch (error) {
-        console.error('[graphql] Error fetching user:', error)
-        throw error
+```ts
+// server/graphql/users/user-queries.resolver.ts
+import { defineQuery } from 'nitro-graphql/utils/define'
+
+export const userQueries = defineQuery({
+  user: async (_, { id }, { storage }) => {
+    try {
+      const user = await storage.getItem(`user:${id}`)
+      if (!user) {
+        throw new Error(`User with id ${id} not found`)
       }
+      return user
+    }
+    catch (error) {
+      console.error('Error fetching user:', error)
+      throw error
     }
   }
 })
+
+// You can also export additional error handling queries
+export const safeUserQueries = defineQuery({
+  userSafe: async (_, { id }, { storage }) => {
+    try {
+      const user = await storage.getItem(`user:${id}`)
+      return user || null // Return null instead of throwing
+    }
+    catch (error) {
+      console.error('Error fetching user:', error)
+      return null
+    }
+  }
+})
+```
+
+</details>
+
+<details>
+<summary><strong>Nuxt Integration</strong></summary>
+
+For Nuxt.js applications, the module provides enhanced integration:
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: [
+    'nitro-graphql/nuxt',
+  ],
+  nitro: {
+    modules: ['nitro-graphql'],
+    graphql: {
+      framework: 'graphql-yoga',
+    },
+  },
+})
+```
+
+Client-side GraphQL files are automatically detected in the `app/graphql/` directory.
+
+### Client-Side Usage
+
+The module automatically generates a GraphQL SDK and provides type-safe client access for frontend usage.
+
+<details>
+<summary>📁 <strong>GraphQL File Structure</strong></summary>
+
+Create your GraphQL queries and mutations in the `app/graphql/` directory:
+
+```
+app/
+├── graphql/
+│   ├── queries.graphql         # GraphQL queries
+│   ├── mutations.graphql       # GraphQL mutations
+│   └── subscriptions.graphql   # GraphQL subscriptions (optional)
+```
+
+</details>
+
+<details>
+<summary>🔥 <strong>Creating GraphQL Files</strong></summary>
+
+**Query File Example:**
+```graphql
+# app/graphql/queries.graphql
+query GetUsers {
+  users {
+    id
+    name
+    email
+    createdAt
+  }
+}
+
+query GetUser($id: ID!) {
+  user(id: $id) {
+    id
+    name
+    email
+    createdAt
+  }
+}
+```
+
+**Mutation File Example:**
+```graphql
+# app/graphql/mutations.graphql
+mutation CreateUser($input: CreateUserInput!) {
+  createUser(input: $input) {
+    id
+    name
+    email
+    createdAt
+  }
+}
+
+mutation UpdateUser($id: ID!, $input: UpdateUserInput!) {
+  updateUser(id: $id, input: $input) {
+    id
+    name
+    email
+    createdAt
+  }
+}
+```
+
+</details>
+
+<details>
+<summary>⚡ <strong>Using the Generated SDK</strong></summary>
+
+The module automatically generates a type-safe SDK based on your GraphQL files:
+
+```ts
+// The SDK is automatically generated and available as an import
+import { createGraphQLClient } from '#graphql/client'
+
+// Create a client instance
+const client = createGraphQLClient({
+  endpoint: '/api/graphql',
+  headers: {
+    'Authorization': 'Bearer your-token-here'
+  }
+})
+
+// Use the generated methods with full type safety
+const getUsersData = await client.GetUsers()
+console.log(getUsersData.users) // Fully typed response
+
+const newUser = await client.CreateUser({
+  input: {
+    name: 'John Doe',
+    email: 'john@example.com'
+  }
+})
+console.log(newUser.createUser) // Fully typed response
 ```
 
-## Performance
+</details>
+
+<details>
+<summary>🎯 <strong>Basic Usage Examples</strong></summary>
 
-### Bundle Size
-The module is optimized for minimal bundle size:
-- Development dependencies are excluded from production builds
-- Uses Function constructor for dynamic imports to prevent bundling
-- Efficient chunk organization
+**Fetching Data:**
+```ts
+// Import the generated client
+import { createGraphQLClient } from '#graphql/client'
 
-### Caching
-- Built-in cache headers for Apollo Sandbox (1 week)
-- Configurable cache settings
-- Lazy schema initialization
+const client = createGraphQLClient()
 
-## Community & Contributing
+// Query users
+const { users } = await client.GetUsers()
+console.log(users) // Array of User objects with full typing
+
+// Query specific user
+const { user } = await client.GetUser({ id: '123' })
+console.log(user) // User object or null
+```
+
+**Creating Data:**
+```ts
+// Create a new user
+const { createUser } = await client.CreateUser({
+  input: {
+    name: 'Jane Doe',
+    email: 'jane@example.com'
+  }
+})
+console.log(createUser) // Newly created user with full typing
+```
+
+**Error Handling:**
+```ts
+try {
+  const { users } = await client.GetUsers()
+  console.log(users)
+} catch (error) {
+  console.error('GraphQL Error:', error)
+  // Handle GraphQL errors appropriately
+}
+```
+
+</details>
+
+<details>
+<summary>🔧 <strong>Client Configuration</strong></summary>
+
+```ts
+import { createGraphQLClient } from '#graphql/client'
+
+// Basic configuration
+const client = createGraphQLClient({
+  endpoint: '/api/graphql',
+  headers: {
+    'Authorization': 'Bearer your-token',
+    'X-Client-Version': '1.0.0'
+  },
+  timeout: 10000
+})
+
+// Advanced configuration with dynamic headers
+const client = createGraphQLClient({
+  endpoint: '/api/graphql',
+  headers: async () => {
+    const token = await getAuthToken()
+    return {
+      'Authorization': token ? `Bearer ${token}` : '',
+      'X-Request-ID': crypto.randomUUID()
+    }
+  },
+  retry: 3,
+  timeout: 30000
+})
+```
+
+</details>
+
+</details>
+
+## 🛠️ Development
+
+### Scripts
+
+- `pnpm build` - Build the module
+- `pnpm dev` - Watch mode with automatic rebuilding
+- `pnpm lint` - ESLint with auto-fix
+- `pnpm playground` - Run the Nitro playground example
+- `pnpm release` - Build, version bump, and publish
+
+### Requirements
+
+- Node.js 20.x or later
+- pnpm (required package manager)
+
+## 💬 Community & Contributing
 
 > [!TIP]
 > **Want to contribute?** We believe you can play a role in the growth of this project!
@@ -442,6 +1012,26 @@ The module is optimized for minimal bundle size:
 
 Thank you for using and developing this project. Every contribution makes the GraphQL ecosystem stronger!
 
+## Sponsors
+
+<p align="center">
+  <a href="https://cdn.jsdelivr.net/gh/productdevbook/static/sponsors.svg">
+    <img src='https://cdn.jsdelivr.net/gh/productdevbook/static/sponsors.svg?t=1721043966'/>
+  </a>
+</p>
+
 ## License
 
-MIT
+[MIT](./LICENSE) License © 2023 [productdevbook](https://github.com/productdevbook)
+
+<!-- Badges -->
+
+[npm-version-src]: https://img.shields.io/npm/v/nitro-graphql?style=flat&colorA=080f12&colorB=1fa669
+[npm-version-href]: https://npmjs.com/package/nitro-graphql
+[npm-downloads-src]: https://img.shields.io/npm/dm/nitro-graphql?style=flat&colorA=080f12&colorB=1fa669
+[npm-downloads-href]: https://npmjs.com/package/nitro-graphql
+[bundle-src]: https://deno.bundlejs.com/badge?q=nitro-graphql@0.0.4
+[bundle-href]: https://deno.bundlejs.com/badge?q=nitro-graphql@0.0.4
+[license-src]: https://img.shields.io/github/license/productdevbook/nitro-graphql.svg?style=flat&colorA=080f12&colorB=1fa669
+[license-href]: https://github.com/productdevbook/nitro-graphql/blob/main/LICENSE
+[jsdocs-href]: https://www.jsdocs.io/package/nitro-graphql

package/dist/ecosystem/nuxt.d.ts

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

package/dist/index.d.ts

@@ -1,9 +1,9 @@
 import { StandardSchemaV1 } from "./types/standard-schema.js";
 import { CodegenClientConfig, CodegenServerConfig, GenImport, NitroGraphQLOptions } from "./types/index.js";
-import * as nitropack0 from "nitropack";
+import * as nitropack3 from "nitropack";
 
 //#region src/index.d.ts
 type GraphQLFramework = 'graphql-yoga';
-declare const _default: nitropack0.NitroModule;
+declare const _default: nitropack3.NitroModule;
 //#endregion
 export { CodegenClientConfig, CodegenServerConfig, GenImport, GraphQLFramework, NitroGraphQLOptions, StandardSchemaV1, _default as default };

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

@@ -1,6 +1,6 @@
-import * as h31 from "h3";
+import * as h36 from "h3";
 
 //#region src/routes/apollo-server.d.ts
-declare const _default: h31.EventHandler<h31.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 h34 from "h3";
+import * as h31 from "h3";
 
 //#region src/routes/graphql-yoga.d.ts
-declare const _default: h34.EventHandler<h34.EventHandlerRequest, Promise<Response>>;
+declare const _default: h31.EventHandler<h31.EventHandlerRequest, Promise<Response>>;
 //#endregion
 export { _default as default };

package/dist/routes/health.d.ts

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

package/package.json

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