Quick Start: Nitro

Get a GraphQL API running in your Nitro project in 5 minutes.

Prerequisites

• Node.js 18 or higher
• pnpm, npm, or yarn
• Basic knowledge of TypeScript and GraphQL

Step 1: Install Dependencies

pnpm

pnpm add nitro-graphql graphql-yoga graphql

npm

npm install nitro-graphql graphql-yoga graphql

yarn

yarn add nitro-graphql graphql-yoga graphql

Why GraphQL Yoga?

GraphQL Yoga is the recommended framework for its smaller bundle size, better performance, and simpler setup. You can also use Apollo Server if you need federation support.

Step 2: Configure Nitro

Add nitro-graphql to your Nitro modules:

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

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

Configuration Options

The graphql configuration object supports many options. We're using the minimal setup here. Learn more in the Configuration Reference.

Step 3: Create Your Schema

Create a GraphQL schema file in your server directory:

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

type Mutation {
  _empty: String
}

File Location

Schema files must be placed in server/graphql/ or subdirectories. The module automatically discovers all .graphql files in this directory.

Step 4: Add Resolvers

Create a resolver file to implement your queries:

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

Important: Named Exports

You MUST use named exports for resolvers. Default exports will not work:

// ✅ Correct
export const helloResolver = defineResolver({...})

// ❌ Wrong - will not be discovered
export default defineResolver({...})

Step 5: Start Development Server

pnpm dev

Your GraphQL server is now running! You should see output like:

✔ Nitro built in X ms
  ➜ Local:    http://localhost:3000/

Step 6: Test Your API

Open your browser to:

• GraphQL Playground: http://localhost:3000/api/graphql
• Health Check: http://localhost:3000/api/graphql/health

Try Your First Query

In the GraphQL playground, run:

query {
  hello
}

Response:

{
  "data": {
    "hello": "Hello from GraphQL!"
  }
}

Query with Arguments

query {
  greeting(name: "World")
}

Response:

{
  "data": {
    "greeting": "Hello, World!"
  }
}

What Just Happened?

Behind the scenes, Nitro GraphQL:

1. Scanned your server/graphql/ directory
2. Discovered your schema.graphql and hello.resolver.ts files
3. Merged your schemas into a unified GraphQL schema
4. Loaded your resolvers
5. Generated TypeScript types (check .nitro/types/nitro-graphql-server.d.ts)
6. Created a GraphQL endpoint at /api/graphql
7. Set up hot reload for development

File Structure

Your project should now look like this:

your-project/
├── server/
│   └── graphql/
│       ├── schema.graphql          # Your schema
│       └── hello.resolver.ts       # Your resolvers
├── .nitro/
│   └── types/
│       └── nitro-graphql-server.d.ts  # Auto-generated types
├── graphql.config.ts               # Auto-generated GraphQL config
├── nitro.config.ts                 # Your Nitro config
└── package.json

Auto-Generated Files

The following files are auto-generated and should not be edited:

• graphql.config.ts - GraphQL IDE configuration
• .nitro/types/nitro-graphql-server.d.ts - TypeScript type definitions
• server/graphql/schema.ts - Schema export (if it doesn't exist)
• server/graphql/context.ts - H3 context types (if it doesn't exist)
• server/graphql/config.ts - GraphQL Yoga config (if it doesn't exist)

Next Steps

Now that you have a working GraphQL API, you can:

📝 Build Your First Feature

Learn how to create queries and mutations

Your First Query →

🎯 Use TypeScript Types

Leverage auto-generated types for type safety

Type Generation →

🗂️ Organize Your Code

Learn best practices for file organization

File Organization →

🔧 Add Context

Access H3 event context in your resolvers

Working with Context →

Common Issues

GraphQL endpoint returns 404

Solution: Make sure nitro-graphql is listed in your modules array and you've set the graphql.framework option.

defineResolver is not defined

Solution: Restart your dev server. The auto-imports need to be regenerated.

Types not generating

Solution:

1. Check that your schema files end with .graphql
2. Check that your resolver files end with .resolver.ts
3. Restart the dev server
4. Look for the generated file at .nitro/types/nitro-graphql-server.d.ts

Vite parse errors on .graphql files

Solution: If you're using Vite with Nitro, add the GraphQL plugin:

import { graphql } from 'nitro-graphql/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    graphql(), // ← Must be before nitro()
    nitro(),
  ]
})

Learn More

• Create Your First Query
• Understanding Schemas
• Working with Resolvers
• Type Generation