---
title: "GraphQL — Schema Generation"
aliases: [graphql-schema, generate-graphql-schema, payload-graphql]
tags: [payloadcms, graphql, codegen, typescript]
sources: [raw/graphql__graphql-schema.md]
created: 2026-05-15
updated: 2026-05-15
---

## Overview

Payload auto-generates a GraphQL schema from your Collections and Globals. The `@payloadcms/graphql` package exposes a CLI command to dump the full schema to a file.

## Schema Generation

Install as a dev dependency:

```bash
pnpm add @payloadcms/graphql -D
```

Run the generator:

```bash
pnpm payload-graphql generate:schema
```

- Default output: `./schema.graphql` (current working directory)
- If `graphQL.schemaOutputFile` is set in `buildConfig`, output goes there (e.g. `./graphql/schema.graphql`)

## Config Path Detection

Payload auto-detects your config, but fails if it lives in a non-standard location (e.g. `src/`). Fix with an npm script using `PAYLOAD_CONFIG_PATH`:

```json
// package.json
{
  "scripts": {
    "generate:graphQLSchema": "cross-env PAYLOAD_CONFIG_PATH=src/payload.config.ts payload-graphql generate:schema"
  }
}
```

## Custom Field Interfaces (`interfaceName`)

For `array`, `block`, `group`, and named `tab` fields, set `interfaceName` to produce a **top-level reusable GraphQL type** instead of an inline type:

```ts
{
  type: 'group',
  name: 'meta',
  interfaceName: 'SharedMeta',
  fields: [
    { name: 'title', type: 'text' },
    { name: 'description', type: 'text' },
  ],
}
```

Generated schema:

```graphql
# Reusable top-level type
type SharedMeta {
  title: String
  description: String
}

# Referenced in the collection
type Collection1 {
  meta: SharedMeta
}
```

This mirrors how `interfaceName` works for [[wiki/payloadcms/typescript|TypeScript type generation]] — same field config option, two outputs.

## Key Takeaways

- `pnpm payload-graphql generate:schema` dumps the full schema to `schema.graphql`
- Set `PAYLOAD_CONFIG_PATH` env var when config is not at the project root
- `interfaceName` on group/array/block/tab fields creates reusable top-level GraphQL types (avoids inline duplication)
- Schema generation is a dev-time step — add it to CI alongside `generate:types` for drift detection
- Related: [[wiki/payloadcms/graphql-extending|GraphQL — Custom Queries and Mutations]] for adding custom ops on top of the generated schema

## Sources

- `raw/graphql__graphql-schema.md`
- https://payloadcms.com/docs/graphql/graphql-schema
