Introduction

What is Nitro GraphQL?

Nitro GraphQL is a powerful GraphQL integration module for Nitro and Nuxt applications that provides:

• Auto-discovery of GraphQL schemas and resolvers
• Automatic TypeScript type generation for both server and client
• Zero-config setup with sensible defaults
• Support for both GraphQL Yoga and Apollo Server
• Apollo Federation for distributed architectures
• External GraphQL service integration

Why Nitro GraphQL?

Traditional GraphQL setup requires:

• Manual schema stitching and imports
• Boilerplate for server configuration
• Custom build scripts for type generation
• Complex tooling configuration

Nitro GraphQL eliminates all of this:

Traditional Approach

// Lots of manual setup...
import { makeExecutableSchema } from '@graphql-tools/schema'
import { createYoga } from 'graphql-yoga'
import { defineEventHandler } from 'h3'

import postResolvers from './resolvers/post'
// Import resolvers manually
import userResolvers from './resolvers/user'

import postSchema from './schemas/post'
// Import schemas manually
import userSchema from './schemas/user'

// Merge everything
const schema = makeExecutableSchema({
  typeDefs: [userSchema, postSchema],
  resolvers: [userResolvers, postResolvers]
})

// Configure server
const yoga = createYoga({ schema })

// Export handler
export default defineEventHandler(yoga)

Nitro GraphQL Approach

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

// That's it! Everything else is automatic.

Key Features

🔍 Auto-Discovery

Automatically scans your project and discovers:

• GraphQL schema files (*.graphql)
• Resolver files (*.resolver.ts)
• Custom directives
• Client queries and mutations

server/graphql/
  ├── schema.graphql          # ← Auto-discovered
  ├── users/
  │   ├── user.graphql        # ← Auto-discovered
  │   └── user.resolver.ts    # ← Auto-discovered
  └── posts/
      ├── post.graphql        # ← Auto-discovered
      └── post.resolver.ts    # ← Auto-discovered

📝 Type Generation

Generate TypeScript types automatically:

// Automatically generated types available via virtual imports
import type { Post, Query, User } from '#graphql/server'

export const userQueries = defineQuery({
  // ✅ Fully typed arguments and return values
  user: async (_, { id }: { id: string }): Promise<User | null> => {
    return await db.user.findUnique({ where: { id } })
  }
})

🎯 Framework Support

Works with:

• Nitro (standalone server)
• Nuxt 3/4 (full-stack framework)
• Any framework built on Nitro

🚀 GraphQL Yoga & Apollo Server

Choose the GraphQL server that fits your needs:

Feature	GraphQL Yoga	Apollo Server
Bundle Size	✓ Smaller	Larger
Performance	✓ Faster	Fast
Federation	Limited	✓ Full Support
Plugins	✓ Modern	✓ Extensive
Setup	✓ Simpler	More Config

Compare frameworks in detail →

🌐 External Services

Connect to external GraphQL APIs and generate types:

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

// Now use generated types
import type { Repository } from '#graphql/client/github'

How It Works

graph LR
    A[Your Code] --> B[Nitro GraphQL]
    B --> C[Schema Discovery]
    B --> D[Resolver Discovery]
    B --> E[Type Generation]
    C --> F[Merged Schema]
    D --> F
    F --> G[GraphQL Server]
    E --> H[TypeScript Types]
    G --> I[/api/graphql]
    H --> J[IntelliSense]

1. File Scanning: Automatically discovers .graphql and .resolver.ts files
2. Schema Merging: Combines all schemas into a unified GraphQL schema
3. Resolver Loading: Loads and registers all resolvers
4. Type Generation: Generates TypeScript types from your schema
5. Server Creation: Sets up GraphQL endpoint at /api/graphql
6. Hot Reload: Watches for changes during development

Comparison with Other Solutions

Feature	Nitro GraphQL	Apollo Server	GraphQL Yoga	Mercurius
Auto-Discovery	✓	✗	✗	✗
Type Generation	✓	⚠ Manual	⚠ Manual	⚠ Manual
Hot Reload	✓	✗	✗	✗
Nitro Integration	✓ Native	⚠ Manual	⚠ Manual	✓
Federation	✓	✓	⚠ Limited	✓

Use Cases

API Development

Build production-ready GraphQL APIs with minimal setup:

• REST API replacement
• BFF (Backend for Frontend) layer
• Microservices gateway

Full-Stack Applications

Perfect for Nuxt applications with:

• Server-side GraphQL API
• Type-safe client queries
• Shared types between frontend and backend

Federation & Microservices

Create distributed GraphQL architectures:

• Multiple subgraphs
• Shared types across services
• Apollo Federation support

External API Integration

Integrate third-party GraphQL services:

• GitHub API
• Shopify API
• Contentful
• Any GraphQL API

Next Steps

📦 Installation

Install and configure Nitro GraphQL in your project

Get Started →

⚡ Quick Start

Build your first GraphQL API in 5 minutes

Quick Start →

📖 Core Concepts

Learn about schemas, resolvers, and types

Learn More →

💡 Examples

See real-world implementations

Browse Examples →