nitro-graphql 1.4.3 → 1.5.0

package/README.md

@@ -357,6 +357,94 @@ server/
 - ✅ Use correct path: `nitro-graphql/utils/define`
 - ✅ Use named exports in resolvers
 
+**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 +453,469 @@ This package powers production applications:
 
 - [**Nitroping**](https://github.com/productdevbook/nitroping) - Self-hosted push notification service
 
+## 🤖 Using Claude Code
+
+Speed up development with [Claude Code](https://claude.ai/code) — AI-powered assistance for setting up and building with nitro-graphql.
+
+### Quick Setup Prompts
+
+Copy and paste these prompts into Claude Code to scaffold a complete GraphQL API.
+
+**💡 Tip**: After pasting, Claude Code will execute step-by-step and validate each action.
+
+<details>
+<summary>🟢 <strong>Nuxt Project</strong></summary>
+
+```
+## GOAL
+Set up nitro-graphql in this Nuxt project with a User management GraphQL API.
+
+## PREREQUISITES
+Check if this is a Nuxt project by looking for nuxt.config.ts in the root.
+
+## STEP 1: INSTALL DEPENDENCIES
+Action: Run this command
+Command: pnpm add nitro-graphql graphql-yoga graphql
+Validation: Check package.json contains these packages
+
+## STEP 2: CONFIGURE NUXT
+File: nuxt.config.ts
+Action: EDIT (add to existing config, don't replace)
+Add these properties:
+
+export default defineNuxtConfig({
+  modules: ['nitro-graphql/nuxt'],  // Add this module
+  nitro: {
+    graphql: {
+      framework: 'graphql-yoga',
+    },
+  },
+})
+
+Validation: Check the file has modules array and nitro.graphql config
+
+## STEP 3: CREATE SCHEMA
+File: server/graphql/schema.graphql
+Action: CREATE NEW FILE (create server/graphql/ directory if needed)
+Content:
+
+type User {
+  id: ID!
+  name: String!
+  email: String!
+}
+
+type Query {
+  users: [User!]!
+  user(id: ID!): User
+}
+
+type Mutation {
+  _empty: String
+}
+
+Validation: File should be in server/graphql/ directory
+
+## STEP 4: CREATE CONTEXT (Optional but recommended)
+File: server/graphql/context.ts
+Action: CREATE NEW FILE (auto-generated on first run, but create manually for clarity)
+Content:
+
+// Extend H3 event context with custom properties
+declare module 'h3' {
+  interface H3EventContext {
+    // Add your custom context properties here
+    // Example:
+    // db?: Database
+    // auth?: { userId: string }
+  }
+}
+
+Note: This file lets you add custom properties to resolver context
+Validation: File exists in server/graphql/
+
+## STEP 5: CREATE CONFIG (Optional)
+File: server/graphql/config.ts
+Action: CREATE NEW FILE (auto-generated, customize if needed)
+Content:
+
+// Custom GraphQL Yoga configuration
+export default defineGraphQLConfig({
+  // Custom context enhancer, plugins, etc.
+  // See: https://the-guild.dev/graphql/yoga-server/docs
+})
+
+Note: Use this to customize GraphQL Yoga options
+Validation: File exists in server/graphql/
+
+## STEP 6: CREATE RESOLVERS
+File: server/graphql/users.resolver.ts
+Action: CREATE NEW FILE
+Content:
+
+// ⚠️ CRITICAL: Use NAMED EXPORTS (not default export)
+export const userQueries = defineQuery({
+  users: async (_, __, context) => {
+    // context is H3EventContext - access event, storage, etc.
+    return [
+      { id: '1', name: 'John Doe', email: 'john@example.com' },
+      { id: '2', name: 'Jane Smith', email: 'jane@example.com' }
+    ]
+  },
+  user: async (_, { id }, context) => {
+    // Third parameter is context (H3EventContext)
+    const users = [
+      { id: '1', name: 'John Doe', email: 'john@example.com' },
+      { id: '2', name: 'Jane Smith', email: 'jane@example.com' }
+    ]
+    return users.find(u => u.id === id) || null
+  }
+})
+
+Validation: File ends with .resolver.ts and uses named export
+
+## STEP 7: START DEV SERVER
+Command: pnpm dev
+Expected Output: Server starts on http://localhost:3000
+Wait for: "Nitro built in X ms" message
+Note: context.ts and config.ts will auto-generate if you skipped steps 4-5
+
+## VALIDATION CHECKLIST
+- [ ] Navigate to http://localhost:3000/api/graphql - should show GraphQL playground
+- [ ] Health check: http://localhost:3000/api/graphql/health - should return OK
+- [ ] Run this query in playground:
+  ```graphql
+  query {
+    users {
+      id
+      name
+      email
+    }
+  }
+  ```
+  Expected: Returns 2 users
+- [ ] Check .nuxt/types/nitro-graphql-server.d.ts exists (types auto-generated)
+
+## FILE STRUCTURE CREATED
+```
+server/
+  graphql/
+    schema.graphql          ← GraphQL type definitions
+    context.ts              ← H3 event context augmentation (optional)
+    config.ts               ← GraphQL Yoga config (optional)
+    users.resolver.ts       ← Query resolvers
+.nuxt/
+  types/
+    nitro-graphql-server.d.ts  ← Auto-generated types
+graphql.config.ts           ← Auto-generated (for IDE tooling)
+```
+
+## CRITICAL RULES (MUST FOLLOW)
+❌ DO NOT use default exports in resolvers
+   Wrong: export default defineQuery({...})
+   Right: export const userQueries = defineQuery({...})
+
+❌ DO NOT name files without .resolver.ts extension
+   Wrong: users.ts or user-resolver.ts
+   Right: users.resolver.ts or user.resolver.ts
+
+✅ DO use named exports for all resolvers
+✅ DO place files in server/graphql/ directory
+✅ DO restart dev server if types don't generate
+
+## TROUBLESHOOTING
+Issue: "GraphQL endpoint returns 404"
+Fix: Ensure 'nitro-graphql/nuxt' is in modules array (not just 'nitro-graphql')
+
+Issue: "defineQuery is not defined"
+Fix: Restart dev server - auto-imports need to regenerate
+
+Issue: "Types not generating"
+Fix: Check .nuxt/types/nitro-graphql-server.d.ts exists, if not restart dev server
+
+Issue: "Module not found: nitro-graphql"
+Fix: Run pnpm install again, check package.json has the package
+
+## NEXT STEPS (After Setup Works)
+1. Add mutations: "Add createUser and deleteUser mutations with H3 storage"
+2. Extend context: "Add database connection to context.ts and use it in resolvers"
+3. Use types: "Import and use TypeScript types from #graphql/server in resolvers"
+4. Add auth: "Add authentication middleware using context in resolvers"
+5. Custom config: "Configure GraphQL Yoga plugins in config.ts"
+
+Now implement this setup step-by-step.
+```
+
+</details>
+
+<details>
+<summary>⚡ <strong>Nitro Project</strong></summary>
+
+```
+Set up nitro-graphql in this Nitro project following these exact specifications:
+
+INSTALLATION:
+1. Run: pnpm add nitro-graphql graphql-yoga graphql
+
+CONFIGURATION (nitro.config.ts):
+import { defineNitroConfig } from 'nitro/config'
+
+export default defineNitroConfig({
+  modules: ['nitro-graphql'],
+  graphql: {
+    framework: 'graphql-yoga',
+  },
+})
+
+SCHEMA (server/graphql/schema.graphql):
+type Product {
+  id: ID!
+  name: String!
+  price: Float!
+}
+
+input CreateProductInput {
+  name: String!
+  price: Float!
+}
+
+type Query {
+  products: [Product!]!
+  product(id: ID!): Product
+}
+
+type Mutation {
+  createProduct(input: CreateProductInput!): Product!
+}
+
+RESOLVERS (server/graphql/products.resolver.ts):
+// Use NAMED EXPORTS only
+export const productQueries = defineQuery({
+  products: async (_, __, context) => {
+    // Access H3 event context
+    const products = await context.storage?.getItem('products') || []
+    return products
+  },
+  product: async (_, { id }, context) => {
+    const products = await context.storage?.getItem('products') || []
+    return products.find(p => p.id === id)
+  }
+})
+
+export const productMutations = defineMutation({
+  createProduct: async (_, { input }, context) => {
+    const products = await context.storage?.getItem('products') || []
+    const product = {
+      id: Date.now().toString(),
+      ...input
+    }
+    products.push(product)
+    await context.storage?.setItem('products', products)
+    return product
+  }
+})
+
+KEY RULES:
+- Files: *.graphql for schemas, *.resolver.ts for resolvers
+- MUST use named exports (not default export)
+- defineQuery and defineMutation are auto-imported
+- Context is the third parameter (access H3 event context)
+- Endpoint: http://localhost:3000/api/graphql
+
+Now implement this setup.
+```
+
+</details>
+
+<details>
+<summary>🎮 <strong>Apollo Server Setup</strong></summary>
+
+```
+Set up nitro-graphql with Apollo Server following these exact specifications:
+
+INSTALLATION:
+1. Run: pnpm add nitro-graphql @apollo/server @apollo/utils.withrequired @as-integrations/h3 graphql
+
+CONFIGURATION (nitro.config.ts):
+import { defineNitroConfig } from 'nitro/config'
+
+export default defineNitroConfig({
+  modules: ['nitro-graphql'],
+  graphql: {
+    framework: 'apollo-server',
+  },
+})
+
+SCHEMA (server/graphql/schema.graphql):
+type Book {
+  id: ID!
+  title: String!
+  author: String!
+}
+
+type Query {
+  books: [Book!]!
+  book(id: ID!): Book
+}
+
+type Mutation {
+  addBook(title: String!, author: String!): Book!
+}
+
+RESOLVERS (server/graphql/books.resolver.ts):
+// IMPORTANT: Use NAMED EXPORTS
+export const bookResolver = defineResolver({
+  Query: {
+    books: async () => {
+      return [
+        { id: '1', title: '1984', author: 'George Orwell' }
+      ]
+    },
+    book: async (_, { id }) => {
+      return { id, title: '1984', author: 'George Orwell' }
+    }
+  },
+  Mutation: {
+    addBook: async (_, { title, author }) => {
+      return {
+        id: Date.now().toString(),
+        title,
+        author
+      }
+    }
+  }
+})
+
+KEY RULES:
+- framework: 'apollo-server' in config
+- defineResolver for complete resolver maps
+- Named exports required (export const name = ...)
+- Apollo Sandbox: http://localhost:3000/api/graphql
+- Supports Apollo Federation with federation: { enabled: true }
+
+Now implement this setup.
+```
+
+</details>
+
+<details>
+<summary>🔄 <strong>Add Feature to Existing Setup</strong></summary>
+
+```
+Add a complete blog posts feature to my nitro-graphql API following these specifications:
+
+SCHEMA (server/graphql/posts/post.graphql):
+type Post {
+  id: ID!
+  title: String!
+  content: String!
+  authorId: ID!
+  createdAt: String!
+}
+
+input CreatePostInput {
+  title: String!
+  content: String!
+  authorId: ID!
+}
+
+input UpdatePostInput {
+  title: String
+  content: String
+}
+
+extend type Query {
+  posts(limit: Int = 10, offset: Int = 0): [Post!]!
+  post(id: ID!): Post
+}
+
+extend type Mutation {
+  createPost(input: CreatePostInput!): Post!
+  updatePost(id: ID!, input: UpdatePostInput!): Post
+  deletePost(id: ID!): Boolean!
+}
+
+RESOLVERS (server/graphql/posts/post.resolver.ts):
+// Use NAMED EXPORTS
+export const postQueries = defineQuery({
+  posts: async (_, { limit, offset }, context) => {
+    const posts = await context.storage?.getItem('posts') || []
+    return posts.slice(offset, offset + limit)
+  },
+  post: async (_, { id }, context) => {
+    const posts = await context.storage?.getItem('posts') || []
+    return posts.find(p => p.id === id) || null
+  }
+})
+
+export const postMutations = defineMutation({
+  createPost: async (_, { input }, context) => {
+    const posts = await context.storage?.getItem('posts') || []
+    const post = {
+      id: Date.now().toString(),
+      ...input,
+      createdAt: new Date().toISOString()
+    }
+    posts.push(post)
+    await context.storage?.setItem('posts', posts)
+    return post
+  },
+  updatePost: async (_, { id, input }, context) => {
+    const posts = await context.storage?.getItem('posts') || []
+    const index = posts.findIndex(p => p.id === id)
+    if (index === -1) return null
+    posts[index] = { ...posts[index], ...input }
+    await context.storage?.setItem('posts', posts)
+    return posts[index]
+  },
+  deletePost: async (_, { id }, context) => {
+    const posts = await context.storage?.getItem('posts') || []
+    const filtered = posts.filter(p => p.id !== id)
+    await context.storage?.setItem('posts', filtered)
+    return filtered.length < posts.length
+  }
+})
+
+TYPE USAGE:
+After dev server restarts, types are auto-generated in:
+- .nitro/types/nitro-graphql-server.d.ts (server types)
+- .nuxt/types/nitro-graphql-server.d.ts (for Nuxt)
+
+Import types:
+import type { Post, CreatePostInput } from '#graphql/server'
+
+KEY RULES:
+- Use "extend type" to add to existing Query/Mutation
+- Named exports required
+- Context has H3 event properties
+- Types auto-generate on file changes
+
+Now implement this feature.
+```
+
+</details>
+
+### 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

package/dist/ecosystem/nuxt.js

@@ -43,9 +43,7 @@ var nuxt_default = defineNuxtModule({
 			nitroConfig.graphql.layerDirectories = layerDirectories;
 			nitroConfig.graphql.layerServerDirs = layerServerDirs;
 			nitroConfig.graphql.layerAppDirs = layerAppDirs;
-			const appGraphqlDir = resolve(nuxt.options.rootDir, "app/graphql");
-			const hasAppGraphqlDir = existsSync(appGraphqlDir);
-			if (!hasAppGraphqlDir) {
+			if (!existsSync(resolve(nuxt.options.rootDir, "app/graphql"))) {
 				const defaultDir = join(clientDir, "default");
 				if (!existsSync(defaultDir)) mkdirSync(defaultDir, { recursive: true });
 				const sampleQueryFile = join(defaultDir, "queries.graphql");

package/dist/index.js

@@ -96,28 +96,62 @@ var src_default = defineNitroModule({
 		nitro.hooks.hook("close", () => {
 			watcher.close();
 		});
-		const tsConfigPath = resolve(nitro.options.buildDir, nitro.options.typescript.tsconfigPath);
-		const tsconfigDir = dirname(tsConfigPath);
+		const tsconfigDir = dirname(resolve(nitro.options.buildDir, nitro.options.typescript.tsconfigPath));
 		const typesDir = resolve(nitro.options.buildDir, "types");
-		const schemas = await scanSchemas(nitro);
-		nitro.scanSchemas = schemas;
-		const docs = await scanDocs(nitro);
-		nitro.scanDocuments = docs;
-		const resolvers = await scanResolvers(nitro);
-		nitro.scanResolvers = resolvers;
+		nitro.scanSchemas = await scanSchemas(nitro);
+		nitro.scanDocuments = await scanDocs(nitro);
+		nitro.scanResolvers = await scanResolvers(nitro);
 		const directives = await scanDirectives(nitro);
 		nitro.scanDirectives = directives;
 		await generateDirectiveSchemas(nitro, directives);
 		nitro.hooks.hook("dev:start", async () => {
-			const schemas$1 = await scanSchemas(nitro);
-			nitro.scanSchemas = schemas$1;
-			const resolvers$1 = await scanResolvers(nitro);
-			nitro.scanResolvers = resolvers$1;
+			const schemas = await scanSchemas(nitro);
+			nitro.scanSchemas = schemas;
+			const resolvers = await scanResolvers(nitro);
+			nitro.scanResolvers = resolvers;
 			const directives$1 = await scanDirectives(nitro);
 			nitro.scanDirectives = directives$1;
 			await generateDirectiveSchemas(nitro, directives$1);
-			const docs$1 = await scanDocs(nitro);
-			nitro.scanDocuments = docs$1;
+			const docs = await scanDocs(nitro);
+			nitro.scanDocuments = docs;
+			if (nitro.options.dev) {
+				consola.box({
+					title: "Nitro GraphQL",
+					message: [
+						`Framework: ${nitro.options.graphql?.framework || "Not configured"}`,
+						`Schemas: ${schemas.length}`,
+						`Resolvers: ${resolvers.length}`,
+						`Directives: ${directives$1.length}`,
+						`Documents: ${docs.length}`,
+						"",
+						"Debug Dashboard: /_nitro/graphql/debug"
+					].join("\n"),
+					style: {
+						borderColor: "cyan",
+						borderStyle: "rounded"
+					}
+				});
+				if (resolvers.length > 0) {
+					const totalExports = resolvers.reduce((sum, r) => sum + r.imports.length, 0);
+					const typeCount = {
+						query: 0,
+						mutation: 0,
+						resolver: 0,
+						type: 0,
+						subscription: 0,
+						directive: 0
+					};
+					for (const resolver of resolvers) for (const imp of resolver.imports) if (imp.type in typeCount) typeCount[imp.type]++;
+					const breakdown = [];
+					if (typeCount.query > 0) breakdown.push(`${typeCount.query} query`);
+					if (typeCount.mutation > 0) breakdown.push(`${typeCount.mutation} mutation`);
+					if (typeCount.resolver > 0) breakdown.push(`${typeCount.resolver} resolver`);
+					if (typeCount.type > 0) breakdown.push(`${typeCount.type} type`);
+					if (typeCount.subscription > 0) breakdown.push(`${typeCount.subscription} subscription`);
+					if (typeCount.directive > 0) breakdown.push(`${typeCount.directive} directive`);
+					if (breakdown.length > 0) consola.success(`[nitro-graphql] ${totalExports} resolver export(s): ${breakdown.join(", ")}`);
+				} else consola.warn("[nitro-graphql] No resolvers found. Check /_nitro/graphql/debug for details.");
+			}
 		});
 		await rollupConfig(nitro);
 		await serverTypeGeneration(nitro);
@@ -147,6 +181,14 @@ var src_default = defineNitroModule({
 			handler: join(runtime, "health"),
 			method: "get"
 		});
+		if (nitro.options.dev) {
+			nitro.options.handlers.push({
+				route: "/_nitro/graphql/debug",
+				handler: join(runtime, "debug"),
+				method: "get"
+			});
+			consola.info("[nitro-graphql] Debug dashboard available at: /_nitro/graphql/debug");
+		}
 		if (nitro.options.imports) {
 			nitro.options.imports.presets ??= [];
 			nitro.options.imports.presets.push({
@@ -170,7 +212,6 @@ var src_default = defineNitroModule({
 				if (id.endsWith(".graphql") || id.endsWith(".gql")) return "schemas";
 				if (id.endsWith(".resolver.ts")) return "resolvers";
 				if (typeof manualChunks === "function") return manualChunks(id, meta);
-				return void 0;
 			};
 			rollupConfig$1.output.chunkFileNames = (chunkInfo) => {
 				if (chunkInfo.moduleIds && chunkInfo.moduleIds.some((id) => id.endsWith(".graphql") || id.endsWith(".resolver.ts") || id.endsWith(".gql"))) return `chunks/graphql/[name].mjs`;