// vite.config.tsimport{defineConfig}from'vite'import{nitro}from'nitro/vite'import{graphql}from'nitro-graphql/vite'exportdefaultdefineConfig({plugins:[graphql(),// ⚠️ Must be before nitro()nitro(),],nitro:{modules:['nitro-graphql'],graphql:{framework:'graphql-yoga',},},})

⚠️ Important: Thegraphql() plugin must be placedbeforenitro() to prevent Vite from trying to parse GraphQL files as JavaScript.

Control which files are auto-generated and customize their output paths. Perfect for library development, monorepos, or custom project structures.

Disable all scaffold files for library/module development:

// nitro.config.tsexportdefaultdefineNitroConfig({graphql:{framework:'graphql-yoga',scaffold:false,// Disable all scaffold filesclientUtils:false,// Disable client utilities}})

Control each file individually:

exportdefaultdefineNitroConfig({graphql:{framework:'graphql-yoga',// Scaffold filesscaffold:{graphqlConfig:false,// Don't generate graphql.config.tsserverSchema:true,// Generate server/graphql/schema.tsserverConfig:true,// Generate server/graphql/config.tsserverContext:false,// Don't generate server/graphql/context.ts},// Client utilities (Nuxt only)clientUtils:{index:true,// Generate app/graphql/index.tsofetch:false,// Don't generate ofetch wrappers},// SDK filessdk:{main:true,// Generate default SDKexternal:true,// Generate external service SDKs},// Type filestypes:{server:true,// Generate server typesclient:true,// Generate client typesexternal:true,// Generate external service types}}})

Customize where files are generated:

exportdefaultdefineNitroConfig({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 pathsscaffold:{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',}}})

Use placeholders in custom paths:

Example:

sdk:{external:'{clientGraphql}/{serviceName}/sdk.ts'}// → app/graphql/github/sdk.ts// → app/graphql/stripe/sdk.ts

Customize paths for individual external services:

exportdefaultdefineNuxtConfig({nitro:{graphql:{framework:'graphql-yoga',// Global default for all external servicessdk:{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 pathspaths:{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}]}}})

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 orsdk.main
3. Global paths:paths.clientGraphql
4. Framework defaults: Nuxt vs Nitro defaults

Example:

// 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}]}

Monorepo structure:

paths:{serverGraphql:'packages/api/src/graphql',clientGraphql:'packages/web/src/graphql',typesDir:'packages/types/src/generated',}

Multiple external service organizations:

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):

{scaffold:false,clientUtils:false,sdk:{enabled:true},// Only generate SDKstypes:{enabled:true},// Only generate types}

Create reusable GraphQL directives:

// server/graphql/directives/auth.directive.tsexportconstauthDirective=defineDirective({name:'auth',locations:['FIELD_DEFINITION'],args:{requires:{type:'String',defaultValue:'USER'}},transformer:(schema)=>{// Add authentication logic}})

Use in schema:

typeQuery {users: [User!]!@auth(requires:"ADMIN")profile:User!@auth}

Connect to multiple GraphQL APIs:

// nuxt.config.tsexportdefaultdefineNuxtConfig({nitro:{graphql:{framework:'graphql-yoga',externalServices:[{name:'github',schema:'https://api.github.com/graphql',endpoint:'https://api.github.com/graphql',headers:()=>({Authorization:`Bearer${process.env.GITHUB_TOKEN}`})}]}}})

Build federated GraphQL services:

// nitro.config.tsexportdefaultdefineNitroConfig({graphql:{framework:'apollo-server',federation:{enabled:true,serviceName:'users-service'}}})

GraphQL endpoint returns 404

• ✅ Checknitro-graphql is in modules
• ✅ Setgraphql.framework option
• ✅ Create at least one.graphql file

Types not generating

• ✅ Restart dev server
• ✅ Check file naming:*.graphql,*.resolver.ts
• ✅ Verify exports are named exports

Import errors

• ✅ Use correct path:nitro-graphql/utils/define
• ✅ Use named exports in resolvers

Vite: "Parse failure: Expected ';', '}' or " on GraphQL files

• ✅ Addgraphql() plugin fromnitro-graphql/vite
• ✅ Ensuregraphql() is placedbeforenitro() in plugins array
• ✅ Example:

  import{graphql}from'nitro-graphql/vite'exportdefaultdefineConfig({plugins:[graphql(),// ← Must be firstnitro(),]})

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 ❌

   // ❌ WRONG - Will not be detectedexportdefaultdefineQuery({users:()=>[...]})

   // ✅ CORRECT - Use named exportexportconstuserQueries=defineQuery({users:()=>[...]})

2. Not using a define function ❌

   // ❌ WRONG - Plain object won't be detectedexportconstresolvers={Query:{users:()=>[...]}}

   // ✅ CORRECT - Use defineResolver, defineQuery, etc.exportconstuserResolver=defineResolver({Query:{users:()=>[...]}})

3. File naming doesn't match export ❌

   // ❌ File: uploadFile.resolver.ts but export is named differentlyexportconstfileUploader=defineMutation({...})

   // ✅ CORRECT - Export name can be anything, as long as it uses a define functionexportconstuploadFile=defineMutation({...})exportconstfileUploader=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 usesoxc-parser to scan.resolver.ts files
• It looks fornamed 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)

## GOALSet up nitro-graphql in this Nuxt project with a User management GraphQL API.## PREREQUISITESCheck if this is a Nuxt project by looking for nuxt.config.ts in the root.## STEP 1: INSTALL DEPENDENCIESAction: Run this commandCommand: pnpm add nitro-graphql graphql-yoga graphqlValidation: Check package.json contains these packages## STEP 2: CONFIGURE NUXTFile: nuxt.config.tsAction: 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 SCHEMAFile: server/graphql/schema.graphqlAction: 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.tsAction: CREATE NEW FILE (auto-generated on first run, but create manually for clarity)Content:// Extend H3 event context with custom propertiesdeclare 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 contextValidation: File exists in server/graphql/## STEP 5: CREATE CONFIG (Optional)File: server/graphql/config.tsAction: CREATE NEW FILE (auto-generated, customize if needed)Content:// Custom GraphQL Yoga configurationexport default defineGraphQLConfig({  // Custom context enhancer, plugins, etc.  // See: https://the-guild.dev/graphql/yoga-server/docs})Note: Use this to customize GraphQL Yoga optionsValidation: File exists in server/graphql/## STEP 6: CREATE RESOLVERSFile: server/graphql/users.resolver.tsAction: CREATE NEW FILEContent:// ⚠️ 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 SERVERCommand: pnpm devExpected Output: Server starts on http://localhost:3000Wait for: "Nitro built in X ms" messageNote: 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)

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 typesgraphql.config.ts           ← Auto-generated (for IDE tooling)

❌ DO NOT use default exports in resolversWrong: export default defineQuery({...})Right: export const userQueries = defineQuery({...})

❌ DO NOT name files without .resolver.ts extensionWrong: users.ts or user-resolver.tsRight: 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

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

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 onlyexport const productQueries = defineQuery({products: async (, __, context) => {// Access H3 event contextconst 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 EXPORTSexport 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: Stringcontent: 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!): PostdeletePost(id: ID!): Boolean!}

RESOLVERS (server/graphql/posts/post.resolver.ts):// Use NAMED EXPORTSexport 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 nullposts[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 APIOnce 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# Install dependenciespnpm install# Build modulepnpm build# Watch modepnpm dev# Run playgroundspnpm playground:nitropnpm playground:nuxtpnpm playground:federation# Lintpnpm lint

[!TIP]Want to contribute? We believe you can play a role in the growth of this project!

• 💡Share ideas viaGitHub Issues
• 🐛Report bugs with detailed information
• 📖Improve docs - README, examples, guides
• 🔧Code contributions - Bug fixes and features
• 🌟Star the project to show support

• Performance benchmarks
• Video tutorials
• Database adapter guides
• VS Code extension

MIT License © 2023productdevbook