GraphQL Naming Reference

This reference documents the GraphQL naming patterns used throughout the codebase, including file names, operation names, and code generation patterns.

GraphQL File Naming

GraphQL files follow a consistent naming pattern that indicates their purpose and which code generation tool processes them.

Pattern

{directory|fragment}.{type}.{codegen}.graphql

Where:

• {directory|fragment} - The feature, fragment name, or purpose (e.g., page, validate, imageProps)
• {type} - The operation type: query, mutation, or fragment
• {codegen} - The code generation tool: api (Rakiura GraphQL), cms (Contentful), shop (Shopify), or omitted

Examples

File Name	Description
page.query.graphql	Main page query (generic)
page.query.cms.graphql	Page query processed by Contentful codegen
validate.query.api.graphql	Validation query for Rakiura GraphQL
product.query.shop.graphql	Product query for Shopify
imageProps.fragment.graphql	Image properties fragment
submit.mutation.graphql	Form submission mutation
articleListItem.fragment.cms.graphql	Article fragment for Contentful

File Name Components

Directory/Fragment Component

The first part of the filename indicates the purpose or what it represents:

page.query.graphql           # Main page content query
validate.query.graphql       # Validation or existence check
related.query.graphql        # Related content query
sidebar.query.graphql        # Sidebar content query
imageProps.fragment.graphql  # Image properties fragment
metadata.fragment.graphql    # Metadata fragment

Type Component

The second part indicates the GraphQL operation type:

Type	Description	Usage
query	Data retrieval	*.query.graphql
mutation	Data modification	*.mutation.graphql
fragment	Reusable selection set	*.fragment.graphql

Codegen Component

The optional third part indicates which service codegen should pull the schema from:

Codegen	Description	Extension
cms	Contentful GraphQL (via GraphQL Codegen)	*.cms.graphql
api	Rakiura GraphQL (via GraphQL Codegen)	*.api.graphql
shop	Shopify GraphQL (via GraphQL Codegen)	*.shop.graphql
(omitted)	Generic query (no codegen)	*.query.graphql

Operation Naming

The GraphQL operation name (inside the file) follows different conventions.

Why Operation Names Matter

The operation name serves two important purposes:

1. Logging - Shows up in GraphQL logs and error messages for debugging
2. Type Generation - Used to generate TypeScript types (e.g., query ArticlesPage generates ArticlesPageQuery and ArticlesPageQueryVariables)

Query Operations

query {RouteName}{Purpose} {
  # fields
}

Examples

src/pages/articles/_graphql/page.query.graphql

query ArticlesPage {
  articles {
    items {
      title
      slug
    }
  }
}

# src/pages/articles/[slug]/_graphql/page.query.graphql
query ArticlePage {
  article(slug: $slug) {
    title
    content
  }
}

# src/pages/places/_graphql/validate.query.graphql
query ValidatePlacePage {
  place(slug: $slug) {
    exists
  }
}

Mutation Operations

mutation {Action}{Entity} {
  # fields
}

Examples

src/components/newsletterForm/graphql/submit.mutation.graphql

mutation SubmitNewsletter {
  newsletter {
    subscribe(email: $email) {
      success
    }
  }
}

# src/components/contactForm/graphql/send.mutation.graphql
mutation SendContactForm {
  contact {
    send(data: $data) {
      id
      status
    }
  }
}

Fragment Naming

fragment {EntityName}{Purpose} on {Type} {
  # fields
}

Examples

src/graphql/fragments/imageProps.fragment.graphql

fragment ImageProperties on Image {
  url
  width
  height
  alt
}

# src/graphql/fragments/articleListItem.fragment.graphql
fragment ArticleListItem on Article {
  title
  slug
  excerpt
  featuredImage {
    ...ImageProperties
  }
}

# src/graphql/fragments/authorBio.fragment.graphql
fragment AuthorBio on Author {
  firstName
  lastName
  bio
  image {
    ...ImageProperties
  }
}

Location-Based Patterns

Page-Level Queries

src/pages/{routeName}/_graphql/
├── page.query.graphql           # Main page query
├── validate.query.graphql       # Validation query
├── api.ts                       # Exports {routeName}Api()
└── transform.ts                 # Data transformations

Naming: {routeName} from file path becomes the operation prefix

src/pages/articles/_graphql/page.query.graphql

query ArticlesPage { }

# src/pages/places/_graphql/page.query.graphql
query PlacesPage { }

Component-Level Queries

src/components/{feature}/graphql/
├── query.graphql                # Component query
├── api.ts                       # Exports get{Feature}()
└── transform.ts                 # Component transforms

Naming: Descriptive based on component purpose

src/components/relatedArticles/graphql/query.graphql

query RelatedArticles { }

# src/components/popularPlaces/graphql/query.graphql
query PopularPlaces { }

Shared Fragments

src/graphql/fragments/
├── imageProps.fragment.graphql
├── articleListItem.fragment.graphql
└── metadata.fragment.graphql

Naming: Descriptive of the data structure

# Singular for single entities
fragment ImageProperties on Image { }
fragment ArticleListItem on Article { }

# Plural for collections (rare)
fragment ArticleTags on ArticleTagsCollection { }

Codegen-Specific Patterns

Contentful Queries (.cms.graphql)

Files ending in .cms.graphql are processed by GraphQL Codegen with the Contentful schema:

src/pages/articles/_graphql/page.query.cms.graphql

query ArticlesPage {
  internalPageCollection(where: { slug: "articles" }) {
    items {
      title
      componentsCollection {
        items {
          __typename
        }
      }
    }
  }
}

Generated types: ArticlesPageQuery, ArticlesPageQueryVariables

Rakiura GraphQL Queries (.api.graphql)

Files ending in .api.graphql are for Rakiura GraphQL:

src/components/userProfile/graphql/saves.query.api.graphql

query UserSaves {
  saves(userId: $userId) {
    id
    sourceId
    sourceType
  }
}

Shopify Queries (.shop.graphql)

Files ending in .shop.graphql are for Shopify GraphQL:

src/components/productList/graphql/products.query.shop.graphql

query ShopProducts {
  products(first: $first) {
    edges {
      node {
        id
        title
        handle
      }
    }
  }
}

Generic Queries (no suffix)

Files without a codegen suffix are generic and may not have generated types:

src/components/search/graphql/query.graphql

query SearchResults {
  search(term: $term) {
    results {
      title
      url
    }
  }
}

Naming Rules

DO

✅ Use PascalCase for operation names
✅ Include context in operation names (e.g., ArticlesPage, not just Page)
✅ Match file names to purpose (page.query.graphql for page queries)
✅ Use descriptive fragment names (ImageProperties, not Image)
✅ Include codegen suffix when using code generation (.cms.graphql, .api.graphql, .shop.graphql)
✅ Use singular for entity names in fragments (ArticleListItem, not ArticleListItems)

DON’T

❌ Use generic operation names (Query, Data, GetData)
❌ Mix naming patterns in the same directory
❌ Omit the operation type suffix (always use .query, .mutation, .fragment)
❌ Use camelCase for operation names
❌ Include implementation details in operation names

Quick Reference

File Naming Pattern

{purpose}.{type}.{codegen?}.graphql

Component	Options	Example
Purpose	page, validate, related, {fragmentName}	page, validate
Type	query, mutation, fragment	query
Codegen	cms, api, shop, or omit	cms

Operation Naming Pattern

{operationType} {Context}{Purpose} { }

Operation	Pattern	Example
Query	query {Route}{Purpose}	query ArticlesPage
Mutation	mutation {Action}{Entity}	mutation SubmitNewsletter
Fragment	fragment {Entity}{Purpose} on {Type}	fragment ImageProperties on Image

Related

• Function Naming - API function naming conventions
• File Organization - Where to place GraphQL files
• GraphQL Query Patterns Guide - How to structure queries (guide)