Nitro GraphQL

The easiest way to add GraphQL to any Nitro application

🚀 Auto-discovery • 📝 Type Generation • 🎮 Apollo Sandbox • 🔧 Zero Config

Quick Start • Examples • Documentation • Community

---

🎥 Watch & Learn

• Nuxt 4 Integration - Step-by-step Nuxt setup
• Standalone Nitro - Basic Nitro integration

✨ Why Nitro GraphQL?

• ⚡ 5-minute setup - From zero to GraphQL in minutes
• 🔍 Auto-discovery - Scans your files, builds your schema
• 📝 Type-safe - Full TypeScript support with auto-generated types
• 🎯 Universal - Works with Nuxt, Nitro, and any Nitro-based framework
• 🎮 Developer-friendly - Built-in Apollo Sandbox for testing
• 🔧 Zero config - Sensible defaults, customize when needed

🚀 Quick Start

1. Install

GraphQL Yoga (recommended):

pnpm add nitro-graphql graphql-yoga graphql

Apollo Server:

pnpm add nitro-graphql @apollo/server @apollo/utils.withrequired @as-integrations/h3 graphql

2. Configure

🔧 Nitro Project

// nitro.config.ts
import { defineNitroConfig } from 'nitropack/config'

export default defineNitroConfig({
  modules: ['nitro-graphql'],
  graphql: {
    framework: 'graphql-yoga', // or 'apollo-server'
  },
})

🟢 Nuxt Project

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['nitro-graphql/nuxt'],
  nitro: {
    graphql: {
      framework: 'graphql-yoga',
    },
  },
})

3. Create Your Schema

# server/graphql/schema.graphql
type Query {
  hello: String!
  greeting(name: String!): String!
}

type Mutation {
  _empty: String
}

4. Add Resolvers

// server/graphql/hello.resolver.ts
export const helloResolver = defineResolver({
  Query: {
    hello: () => 'Hello from GraphQL!',
    greeting: (_, { name }) => `Hello, ${name}!`,
  },
})

5. Start Development

pnpm dev

🎉 That's it! Your GraphQL server is ready at:

• Endpoint: http://localhost:3000/api/graphql
• Playground: http://localhost:3000/api/graphql (browser)
• Health: http://localhost:3000/api/graphql/health

🎮 Examples

Try these working examples:

Example	Description	Demo
Nitro Basic	Standalone Nitro with GraphQL	pnpm playground:nitro
Nuxt Integration	Full Nuxt app with client types	pnpm playground:nuxt
Apollo Federation	Federated GraphQL services	pnpm playground:federation

🏗️ Building Your First Feature

Let's create a complete user management system:

1. Define Schema

# server/graphql/users/user.graphql
type User {
  id: ID!
  name: String!
  email: String!
  createdAt: DateTime!
}

input CreateUserInput {
  name: String!
  email: String!
}

extend type Query {
  users: [User!]!
  user(id: ID!): User
}

extend type Mutation {
  createUser(input: CreateUserInput!): User!
}

2. Create Resolvers

// server/graphql/users/user.resolver.ts
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)
  }
})

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

3. Test in Apollo Sandbox

mutation {
  createUser(input: {
    name: "John Doe"
    email: "[email protected]"
  }) {
    id
    name
    email
    createdAt
  }
}

query {
  users {
    id
    name
    email
  }
}

🚀 Advanced Features

🎭 Custom Directives

Create reusable GraphQL directives:

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

Use in schema:

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

🌐 External GraphQL Services

Connect to multiple GraphQL APIs:

// nuxt.config.ts
export default defineNuxtConfig({
  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}`
          })
        }
      ]
    }
  }
})

🔄 Apollo Federation

Build federated GraphQL services:

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

📖 Documentation

Core Utilities

All utilities are auto-imported in resolver files:

Function	Purpose	Example
defineResolver	Complete resolvers	defineResolver({ Query: {...}, Mutation: {...} })
defineQuery	Query-only resolvers	defineQuery({ users: () => [...] })
defineMutation	Mutation-only resolvers	defineMutation({ createUser: (...) => {...} })
defineType	Custom type resolvers	defineType({ User: { posts: (parent) => [...] } })
defineDirective	Custom directives	defineDirective({ name: 'auth', ... })

Type Generation

Automatic TypeScript types are generated:

• Server types: #graphql/server - Use in resolvers and server code
• Client types: #graphql/client - Use in frontend components

// Server-side
import type { User, CreateUserInput } from '#graphql/server'

// Client-side  
import type { GetUsersQuery, CreateUserMutation } from '#graphql/client'

Project Structure

server/
├── graphql/
│   ├── schema.graphql              # Main schema
│   ├── hello.resolver.ts           # Basic resolvers
│   ├── users/
│   │   ├── user.graphql           # User schema
│   │   └── user.resolver.ts       # User resolvers
│   ├── directives/                # Custom directives
│   └── config.ts                  # Optional GraphQL config

⚠️ Important: Use named exports for all resolvers:

// ✅ Correct
export const userQueries = defineQuery({...})

// ❌ Deprecated
export default defineQuery({...})

🚨 Troubleshooting

Common Issues

GraphQL endpoint returns 404

• ✅ Check nitro-graphql is in modules
• ✅ Set graphql.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

🌟 Production Usage

This package powers production applications:

• Nitroping - Self-hosted push notification service

🛠️ Development

# Install dependencies
pnpm install

# Build module
pnpm build

# Watch mode
pnpm dev

# Run playgrounds
pnpm playground:nitro
pnpm playground:nuxt
pnpm playground:federation

# Lint
pnpm lint

💬 Community

Tip

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

Ways to Contribute

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

Help Wanted

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

Sponsors

License

MIT License © 2023 productdevbook