nitro-graphql 2.0.0-beta.3 → 2.0.0-beta.30

package/README.md

@@ -1,20 +1,31 @@
-# Nitro GraphQL
-
 <div align="center">
 
+<img src="./.docs/public/logo.svg" alt="Nitro GraphQL Logo" width="120" height="120">
+
+# Nitro GraphQL
+
 [![npm version][npm-version-src]][npm-version-href]
+[![Beta Status][beta-src]][beta-href]
 [![npm downloads][npm-downloads-src]][npm-downloads-href]
 [![bundle][bundle-src]][bundle-href]
 [![License][license-src]][license-href]
+[![Documentation][docs-src]][docs-href]
 
 **The easiest way to add GraphQL to any Nitro application**
 
 🚀 **Auto-discovery** • 📝 **Type Generation** • 🎮 **Apollo Sandbox** • 🔧 **Zero Config**
 
-[Quick Start](#-quick-start) • [Examples](#-examples) • [Documentation](#-documentation) • [Community](#-community)
+[📚 Documentation](https://nitro-graphql.pages.dev) • [Quick Start](#-quick-start) • [Examples](#-examples) • [Community](#-community)
 
 </div>
 
+> [!IMPORTANT]
+> **v2.0 Beta (Current - Main Branch)**
+> This is the **v2.0** beta branch with Nitro v3 and H3 v2 support. Includes Rolldown optimization, improved chunking, and enhanced Vite integration.
+>
+> **Looking for v1.x?**
+> For the stable v1 version (Nitro v2), see the [`v1` branch](https://github.com/productdevbook/nitro-graphql/tree/v1).
+
 ---
 
 ## 🎥 Watch & Learn
@@ -31,18 +42,26 @@
 - 🎮 **Developer-friendly** - Built-in Apollo Sandbox for testing
 - 🔧 **Zero config** - Sensible defaults, customize when needed
 
+### 🆕 What's New in v2.0 Beta
+
+- 🚀 **Nitro v3 & H3 v2** - Full compatibility with the latest Nitro and H3
+- ⚙️ **Rolldown Support** - Optimized for both Rolldown (Vite 7+) and Rollup
+- 📦 **Smart Chunking** - GraphQL code split into separate chunks (~98% size reduction)
+- 🔍 **Debug Dashboard** - Built-in diagnostics at `/_nitro/graphql/debug` (dev only)
+- 🎨 **Enhanced Vite Integration** - Better custom path support and virtual module resolution
+
 ## 🚀 Quick Start
 
 ### 1. Install
 
 **GraphQL Yoga (recommended):**
 ```bash
-pnpm add nitro-graphql graphql-yoga graphql
+pnpm add nitro-graphql@beta graphql-yoga graphql graphql-config
 ```
 
 **Apollo Server:**
 ```bash
-pnpm add nitro-graphql @apollo/server @apollo/utils.withrequired @as-integrations/h3 graphql
+pnpm add nitro-graphql@beta @apollo/server graphql graphql-config
 ```
 
 ### 2. Configure
@@ -52,16 +71,47 @@ pnpm add nitro-graphql @apollo/server @apollo/utils.withrequired @as-integration
 
 ```ts
 // nitro.config.ts
+import graphql from 'nitro-graphql'
 import { defineNitroConfig } from 'nitro/config'
 
 export default defineNitroConfig({
-  modules: ['nitro-graphql'],
-  graphql: {
-    framework: 'graphql-yoga', // or 'apollo-server'
+  modules: [
+    graphql({
+      framework: 'graphql-yoga', // or 'apollo-server'
+    }),
+  ],
+})
+```
+
+</details>
+
+<details>
+<summary>⚡ <strong>Vite + Nitro Project</strong></summary>
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite'
+import { nitro } from 'nitro/vite'
+import graphql from 'nitro-graphql'
+import { graphql as graphqlVite } from 'nitro-graphql/vite'
+
+export default defineConfig({
+  plugins: [
+    graphqlVite(), // ⚠️ Must be before nitro()
+    nitro(),
+  ],
+  nitro: {
+    modules: [
+      graphql({
+        framework: 'graphql-yoga',
+      }),
+    ],
   },
 })
 ```
 
+> **⚠️ Important**: The `graphql()` plugin must be placed **before** `nitro()` to prevent Vite from trying to parse GraphQL files as JavaScript.
+
 </details>
 
 <details>
@@ -99,6 +149,8 @@ type Mutation {
 
 ```ts
 // server/graphql/hello.resolver.ts
+import { defineResolver } from 'nitro-graphql/define'
+
 export const helloResolver = defineResolver({
   Query: {
     hello: () => 'Hello from GraphQL!',
@@ -117,6 +169,7 @@ pnpm dev
 - **Endpoint**: `http://localhost:3000/api/graphql`
 - **Playground**: `http://localhost:3000/api/graphql` (browser)
 - **Health**: `http://localhost:3000/api/graphql/health`
+- **Debug Dashboard**: `http://localhost:3000/_nitro/graphql/debug` (dev mode only)
 
 ## 🎮 Examples
 
@@ -125,8 +178,17 @@ Try these working examples:
 | Example | Description | Demo |
 |---------|-------------|------|
 | [**Nitro Basic**](./playgrounds/nitro/) | Standalone Nitro with GraphQL | `pnpm playground:nitro` |
+| [**Vite + Nitro**](./playgrounds/vite/) | Vite with Nitro GraphQL integration | `cd playgrounds/vite && pnpm dev` |
 | [**Nuxt Integration**](./playgrounds/nuxt/) | Full Nuxt app with client types | `pnpm playground:nuxt` |
 | [**Apollo Federation**](./playgrounds/federation/) | Federated GraphQL services | `pnpm playground:federation` |
+| [**Drizzle ORM**](./examples/drizzle-orm/) | Drizzle ORM + Zod validation integration | `cd examples/drizzle-orm && pnpm dev` |
+
+### 🧪 Test Projects
+
+Real-world test projects using nitro-graphql v2:
+
+- [**Vite + Nitro + Rolldown**](https://github.com/productdevbook/vite-nitro-graphql/tree/rolldown) - Testing with Rolldown bundler (Vite 7+)
+- [**Vite + Nitro (Main)**](https://github.com/productdevbook/vite-nitro-graphql) - Standard Vite integration tests
 
 ## 🏗️ Building Your First Feature
 
@@ -160,6 +222,8 @@ extend type Mutation {
 ### 2. Create Resolvers
 ```ts
 // server/graphql/users/user.resolver.ts
+import { defineQuery, defineMutation } from 'nitro-graphql/define'
+
 export const userQueries = defineQuery({
   users: async (_, __, { storage }) => {
     return await storage.getItem('users') || []
@@ -210,6 +274,261 @@ query {
 
 ## 🚀 Advanced Features
 
+<details>
+<summary><strong>🎛️ Custom File Generation & Paths</strong></summary>
+
+Control which files are auto-generated and customize their output paths. Perfect for library development, monorepos, or custom project structures.
+
+### Library Mode
+
+Disable all scaffold files for library/module development:
+
+```ts
+// nitro.config.ts
+import graphql from 'nitro-graphql'
+import { defineNitroConfig } from 'nitro/config'
+
+export default defineNitroConfig({
+  modules: [
+    graphql({
+      framework: 'graphql-yoga',
+      scaffold: false,        // Disable all scaffold files
+      clientUtils: false,     // Disable client utilities
+    }),
+  ],
+})
+```
+
+### Fine-Grained Control
+
+Control each file individually:
+
+```ts
+import graphql from 'nitro-graphql'
+import { defineNitroConfig } from 'nitro/config'
+
+export default defineNitroConfig({
+  modules: [
+    graphql({
+      framework: 'graphql-yoga',
+
+      // Scaffold files
+      scaffold: {
+        graphqlConfig: false,     // Don't generate graphql.config.ts
+        serverSchema: true,       // Generate server/graphql/schema.ts
+        serverConfig: true,       // Generate server/graphql/config.ts
+        serverContext: false,     // Don't generate server/graphql/context.ts
+      },
+
+      // Client utilities (Nuxt only)
+      clientUtils: {
+        index: true,              // Generate app/graphql/index.ts
+        ofetch: false,            // Don't generate ofetch wrappers
+      },
+
+      // SDK files
+      sdk: {
+        main: true,               // Generate default SDK
+        external: true,           // Generate external service SDKs
+      },
+
+      // Type files
+      types: {
+        server: true,             // Generate server types
+        client: true,             // Generate client types
+        external: true,           // Generate external service types
+      },
+    }),
+  ],
+})
+```
+
+### Custom Paths
+
+Customize where files are generated:
+
+```ts
+import graphql from 'nitro-graphql'
+import { defineNitroConfig } from 'nitro/config'
+
+export default defineNitroConfig({
+  modules: [
+    graphql({
+      framework: 'graphql-yoga',
+
+      // Method 1: Global paths (affects all files)
+      paths: {
+        serverGraphql: 'src/server/graphql',
+        clientGraphql: 'src/client/graphql',
+        buildDir: '.build',
+        typesDir: '.build/types',
+      },
+
+      // Method 2: Specific file paths
+      scaffold: {
+        serverSchema: 'lib/graphql/schema.ts',
+        serverConfig: 'lib/graphql/config.ts',
+      },
+
+      sdk: {
+        main: 'app/graphql/organization/sdk.ts',
+        external: 'app/graphql/{serviceName}/client-sdk.ts',
+      },
+
+      types: {
+        server: 'types/graphql-server.d.ts',
+        client: 'types/graphql-client.d.ts',
+      },
+    }),
+  ],
+})
+```
+
+### Path Placeholders
+
+Use placeholders in custom paths:
+
+| Placeholder | Description | Example |
+|------------|-------------|---------|
+| `{serviceName}` | External service name | `github`, `stripe` |
+| `{buildDir}` | Build directory | `.nitro` or `.nuxt` |
+| `{rootDir}` | Root directory | `/Users/you/project` |
+| `{framework}` | Framework name | `nuxt` or `nitro` |
+| `{typesDir}` | Types directory | `.nitro/types` |
+| `{serverGraphql}` | Server GraphQL dir | `server/graphql` |
+| `{clientGraphql}` | Client GraphQL dir | `app/graphql` |
+
+Example:
+```ts
+sdk: {
+  external: '{clientGraphql}/{serviceName}/sdk.ts'
+}
+// → app/graphql/github/sdk.ts
+// → app/graphql/stripe/sdk.ts
+```
+
+### Service-Specific Paths
+
+Customize paths for individual external services:
+
+```ts
+export default defineNuxtConfig({
+  nitro: {
+    graphql: {
+      framework: 'graphql-yoga',
+
+      // Global default for all external services
+      sdk: {
+        external: 'app/graphql/{serviceName}/sdk.ts'
+      },
+
+      externalServices: [
+        {
+          name: 'github',
+          endpoint: 'https://api.github.com/graphql',
+          schema: 'https://api.github.com/graphql',
+
+          // GitHub-specific paths (override global config)
+          paths: {
+            sdk: 'app/graphql/organization/github-sdk.ts',
+            types: 'types/github.d.ts',
+            ofetch: 'app/graphql/organization/github-client.ts'
+          }
+        },
+        {
+          name: 'stripe',
+          endpoint: 'https://api.stripe.com/graphql',
+          schema: 'https://api.stripe.com/graphql',
+
+          // Stripe-specific paths
+          paths: {
+            sdk: 'app/graphql/payments/stripe-sdk.ts',
+            types: 'types/payments/stripe.d.ts',
+            // ofetch uses global config
+          }
+        },
+        {
+          name: 'shopify',
+          endpoint: 'https://api.shopify.com/graphql',
+          // No paths → uses global config
+          // → app/graphql/shopify/sdk.ts
+        }
+      ]
+    }
+  }
+})
+```
+
+### Path Resolution Priority
+
+When resolving file paths, the system follows this priority order:
+
+1. **Service-specific path** (for external services): `service.paths.sdk`
+2. **Category config**: `sdk.external` or `sdk.main`
+3. **Global paths**: `paths.clientGraphql`
+4. **Framework defaults**: Nuxt vs Nitro defaults
+
+Example:
+```ts
+// Given this config:
+{
+  paths: { clientGraphql: 'custom/graphql' },
+  sdk: { external: '{clientGraphql}/{serviceName}/sdk.ts' },
+  externalServices: [
+    {
+      name: 'github',
+      paths: { sdk: 'app/org/github-sdk.ts' }  // ← Wins (priority 1)
+    },
+    {
+      name: 'stripe',
+      // Uses sdk.external (priority 2)
+      // → custom/graphql/stripe/sdk.ts
+    }
+  ]
+}
+```
+
+### Use Cases
+
+**Monorepo structure:**
+```ts
+paths: {
+  serverGraphql: 'packages/api/src/graphql',
+  clientGraphql: 'packages/web/src/graphql',
+  typesDir: 'packages/types/src/generated',
+}
+```
+
+**Multiple external service organizations:**
+```ts
+externalServices: [
+  {
+    name: 'github',
+    paths: { sdk: 'app/graphql/vcs/github-sdk.ts' }
+  },
+  {
+    name: 'gitlab',
+    paths: { sdk: 'app/graphql/vcs/gitlab-sdk.ts' }
+  },
+  {
+    name: 'stripe',
+    paths: { sdk: 'app/graphql/billing/stripe-sdk.ts' }
+  }
+]
+```
+
+**Library development (no scaffolding):**
+```ts
+{
+  scaffold: false,
+  clientUtils: false,
+  sdk: { enabled: true },    // Only generate SDKs
+  types: { enabled: true },  // Only generate types
+}
+```
+
+</details>
+
 <details>
 <summary><strong>🎭 Custom Directives</strong></summary>
 
@@ -217,6 +536,8 @@ Create reusable GraphQL directives:
 
 ```ts
 // server/graphql/directives/auth.directive.ts
+import { defineDirective } from 'nitro-graphql/define'
+
 export const authDirective = defineDirective({
   name: 'auth',
   locations: ['FIELD_DEFINITION'],
@@ -274,14 +595,19 @@ Build federated GraphQL services:
 
 ```ts
 // nitro.config.ts
+import graphql from 'nitro-graphql'
+import { defineNitroConfig } from 'nitro/config'
+
 export default defineNitroConfig({
-  graphql: {
-    framework: 'apollo-server',
-    federation: {
-      enabled: true,
-      serviceName: 'users-service'
-    }
-  }
+  modules: [
+    graphql({
+      framework: 'apollo-server',
+      federation: {
+        enabled: true,
+        serviceName: 'users-service',
+      },
+    }),
+  ],
 })
 ```
 
@@ -291,7 +617,11 @@ export default defineNitroConfig({
 
 ### Core Utilities
 
-All utilities are auto-imported in resolver files:
+> **⚠️ Breaking Change**: Utilities are **NOT auto-imported**. You must explicitly import them from `nitro-graphql/define`:
+
+```typescript
+import { defineResolver, defineQuery, defineMutation, defineType, defineDirective } from 'nitro-graphql/define'
+```
 
 | Function | Purpose | Example |
 |----------|---------|---------|
@@ -300,6 +630,11 @@ All utilities are auto-imported in resolver files:
 | `defineMutation` | Mutation-only resolvers | `defineMutation({ createUser: (...) => {...} })` |
 | `defineType` | Custom type resolvers | `defineType({ User: { posts: (parent) => [...] } })` |
 | `defineDirective` | Custom directives | `defineDirective({ name: 'auth', ... })` |
+| `defineGraphQLConfig` | GraphQL server config | `defineGraphQLConfig({ maskedErrors: {...} })` |
+| `defineSchema` | Schema with Zod integration | `defineSchema({ Book: selectBookSchema })` |
+
+**Additional Utilities** from `nitro-graphql/utils`:
+- `createDefaultMaskError()` - Error handler for ZodError and HTTPError (use in `defineGraphQLConfig`)
 
 ### Type Generation
 
@@ -353,10 +688,107 @@ server/
 - ✅ Check file naming: `*.graphql`, `*.resolver.ts`
 - ✅ Verify exports are named exports
 
-**Import errors**
-- ✅ Use correct path: `nitro-graphql/utils/define`
+**Import errors / "defineQuery is not defined"**
+- ✅ **Requires explicit imports**: Add `import { defineQuery } from 'nitro-graphql/define'` to resolver files
+- ✅ Use correct import path: `nitro-graphql/define` (not `nitro-graphql`)
 - ✅ Use named exports in resolvers
 
+Example fix:
+```typescript
+// Add this to the top of your resolver file
+import { defineQuery, defineMutation } from 'nitro-graphql/define'
+
+export const myQueries = defineQuery({ ... })
+```
+
+**Vite: "Parse failure: Expected ';', '}' or <eof>" on GraphQL files**
+- ✅ Add `graphql()` plugin from `nitro-graphql/vite`
+- ✅ Ensure `graphql()` is placed **before** `nitro()` in plugins array
+- ✅ Example:
+  ```ts
+  import { graphql } from 'nitro-graphql/vite'
+
+  export default defineConfig({
+    plugins: [
+      graphql(), // ← Must be first
+      nitro(),
+    ]
+  })
+  ```
+
+**RollupError: "[exportName]" is not exported by "[file].resolver.ts"**
+
+This error occurs when the resolver scanner can't find the expected export in your resolver file. Common causes:
+
+1. **Using default export instead of named export** ❌
+   ```ts
+   // ❌ WRONG - Will not be detected
+   export default defineQuery({
+     users: () => [...]
+   })
+   ```
+
+   ```ts
+   // ✅ CORRECT - Use named export
+   export const userQueries = defineQuery({
+     users: () => [...]
+   })
+   ```
+
+2. **Not using a define function** ❌
+   ```ts
+   // ❌ WRONG - Plain object won't be detected
+   export const resolvers = {
+     Query: {
+       users: () => [...]
+     }
+   }
+   ```
+
+   ```ts
+   // ✅ CORRECT - Use defineResolver, defineQuery, etc.
+   export const userResolver = defineResolver({
+     Query: {
+       users: () => [...]
+     }
+   })
+   ```
+
+3. **File naming doesn't match export** ❌
+   ```ts
+   // ❌ File: uploadFile.resolver.ts but export is named differently
+   export const fileUploader = defineMutation({...})
+   ```
+
+   ```ts
+   // ✅ CORRECT - Export name can be anything, as long as it uses a define function
+   export const uploadFile = defineMutation({...})
+   export const fileUploader = defineMutation({...}) // Both work!
+   ```
+
+4. **Syntax errors preventing parsing**
+   - Check for TypeScript compilation errors in the file
+   - Ensure imports are valid
+   - Verify no missing brackets or syntax issues
+
+**How resolver scanning works:**
+- The module uses `oxc-parser` to scan `.resolver.ts` files
+- It looks for **named exports** using these functions:
+  - `defineResolver` - Complete resolver with Query, Mutation, etc.
+  - `defineQuery` - Query-only resolvers
+  - `defineMutation` - Mutation-only resolvers
+  - `defineType` - Custom type resolvers
+  - `defineSubscription` - Subscription resolvers
+  - `defineDirective` - Directive resolvers
+- Only exports using these functions are included in the virtual module
+
+**Debugging steps:**
+1. Check your resolver file uses named exports: `export const name = defineQuery({...})`
+2. Verify you're using one of the define functions listed above
+3. Look for TypeScript/syntax errors in the file
+4. Restart the dev server after fixing
+5. If issues persist, simplify the resolver to test (single query)
+
 </details>
 
 ## 🌟 Production Usage
@@ -365,6 +797,27 @@ This package powers production applications:
 
 - [**Nitroping**](https://github.com/productdevbook/nitroping) - Self-hosted push notification service
 
+### Working with Your GraphQL API
+
+Once set up, you can ask Claude Code for help with:
+
+```
+"Add authentication to my GraphQL resolvers"
+"Create a custom @auth directive for field-level permissions"
+"Set up type generation for client-side queries"
+"Add pagination to my users query"
+"Connect to an external GitHub GraphQL API"
+"Debug: my types aren't generating in .nitro/types/"
+"Optimize resolver performance using DataLoader"
+```
+
+### Tips for Better Results
+
+- **Start specific**: Include your framework (Nuxt/Nitro), version, and goal
+- **Reference docs**: Mention "following nitro-graphql conventions" to align with best practices
+- **Show errors**: Paste error messages for faster debugging
+- **Test iteratively**: Run `pnpm dev` after each change to verify
+
 ## 🛠️ Development
 
 ```bash
@@ -424,4 +877,8 @@ pnpm lint
 [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
+[license-href]: https://github.com/productdevbook/nitro-graphql/blob/main/LICENSE
+[docs-src]: https://img.shields.io/badge/docs-read-blue?style=flat&colorA=080f12&colorB=1fa669
+[docs-href]: https://nitro-graphql.pages.dev
+[beta-src]: https://img.shields.io/npm/v/nitro-graphql/beta?style=flat&logo=rocket&logoColor=white&label=beta&color=7c3aed&colorA=080f12
+[beta-href]: https://github.com/productdevbook/nitro-graphql/releases