fragment.graphql

GraphQL fragment files contain reusable field selections that can be shared across multiple queries.

File Location

Shared Fragments

src/graphql/fragments/{name}.fragment.graphql
src/graphql/fragments/{name}.fragment.cms.graphql

Shared fragments are located in the central src/graphql/fragments/ directory.

Examples:

src/graphql/fragments/imageProps.fragment.graphql
src/graphql/fragments/editorialAssemblyListItem.fragment.graphql
src/graphql/fragments/editorialAssemblyDetail.fragment.graphql
src/graphql/fragments/poiListItem.fragment.graphql

Component-Specific Fragments

In rare cases, component-specific fragments can be colocated:

src/components/{feature}/graphql/{name}.fragment.graphql

Fragment Naming Pattern

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

Examples:

fragment ImageProperties on Image { }
fragment EditorialAssemblyListItem on EditorialAssembly { }
fragment EditorialAssemblyDetail on EditorialAssemblyExtended { }
fragment PoiListItem on Poi { }

Naming Convention

Use singular entity names: EditorialAssemblyListItem not EditorialAssemblyListItems

Typical Structure

Simple Fragment

src/graphql/fragments/imageProps.fragment.graphql

fragment ImageProperties on Image {
  url
  width
  height
  description  # Used as alt text
  title
}

Complex Fragment with Nested Fragments

src/graphql/fragments/editorialAssemblyListItem.fragment.graphql

#import "#graphql/fragments/imageProps.fragment.graphql"

fragment EditorialAssemblyListItem on EditorialAssembly {
  esid
  title
  slug
  publishedDate
  excerpt
  readTime

  featuredImage {
    ...ImageProperties
  }

  authors {
    firstName
    lastName
    slug
    image {
      ...ImageProperties
    }
  }
}

Fragment with Inline Fragments

src/graphql/fragments/contentBlock.fragment.graphql

fragment ContentBlock on ContentBlockUnion {
  __typename

  ... on ContentText {
    text
    format
  }

  ... on ContentImage {
    image {
      ...ImageProperties
    }
    caption
  }

  ... on ContentVideo {
    videoUrl
    thumbnail {
      ...ImageProperties
    }
  }
}

Fragment Imports

Use path aliases for fragment imports:

#import "#graphql/fragments/imageProps.fragment.graphql"
#import "#graphql/fragments/authorBio.fragment.graphql"

fragment ArticleDetail on Article {
  title
  featuredImage {
    ...ImageProperties
  }
  author {
    ...AuthorBio
  }
}

Fragment Usage in Queries

List Page (Rakiura)

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

#import "#graphql/fragments/editorialAssemblyListItem.fragment.graphql"

query ArticlesPage {
  editorialAssemblies(page: { size: 20 }) {
    items {
      ...EditorialAssemblyListItem
    }
  }
}

Detail Page (Rakiura)

src/pages/articles/[slug]/_graphql/page.query.api.graphql

#import "#graphql/fragments/editorialAssemblyDetail.fragment.graphql"

query ArticlePage($slug: String!) {
  editorialAssembly(slug: $slug) {
    ...EditorialAssemblyDetail
  }
}

When NOT to use a fragment

Some queries intentionally fetch a minimal subset of fields for performance (sitemaps, RSS feeds, count queries). These should not use the full list item fragment.

Common Fragment Patterns

Image Fragment

fragment ImageProperties on Image {
  url
  width
  height
  description  # alt text
  title
  contentType
}

Link/CTA Fragment

fragment CTAProperties on CTA {
  text
  url
  variant  # primary, secondary, text
  external
  openInNewTab
}

Author Fragment

#import "#graphql/fragments/imageProps.fragment.graphql"

fragment AuthorBio on Author {
  firstName
  lastName
  slug
  bio
  image {
    ...ImageProperties
  }
  socialMedia {
    twitter
    instagram
  }
}

Editorial Assembly Fragments (Rakiura)

src/graphql/fragments/editorialAssemblyListItem.fragment.graphql

#import "#graphql/fragments/imageProps.fragment.graphql"

fragment EditorialAssemblyListItem on EditorialAssembly {
  title
  slug
  excerpt
  date
  featuredImage {
    ...ImageProperties
  }
  authors {
    firstName
    lastName
    slug
  }
  tags {
    slug
    title
  }
}

src/graphql/fragments/editorialAssemblyDetail.fragment.graphql

#import "#graphql/fragments/imageProps.fragment.graphql"

fragment EditorialAssemblyDetail on EditorialAssemblyExtended {
  title
  slug
  excerpt
  date
  featuredImage {
    ...ImageProperties
  }
  authors {
    firstName
    lastName
    slug
    bio
    image {
      ...ImageProperties
    }
  }
  content
  readTime
  tags {
    slug
    title
  }
  meta {
    type {
      slug
      title
    }
  }
}

Card/List Item Fragments

#import "#graphql/fragments/imageProps.fragment.graphql"

fragment PlaceCard on Place {
  name
  slug
  description
  location {
    city
    country
  }
  image {
    ...ImageProperties
  }
  rating
}

Type Generation

Fragments generate TypeScript types:

fragment EditorialAssemblyListItem on EditorialAssembly {
  title
  slug
  excerpt
  date
}

Generates:

// Generated type
export type EditorialAssemblyListItemFragment = {
  __typename?: 'EditorialAssembly';
  title: string;
  slug: string;
  excerpt: string | null;
  date: string;
};

// Usage in code
import type { EditorialAssemblyListItemFragment } from "#graphql/generated/rakiura/schema";

// Adapter pattern: map Rakiura types to existing UI component interfaces
function mapEditorialAssemblyToArticle(
  assembly: EditorialAssemblyListItemFragment
): Article {
  return {
    title: assembly.title,
    slug: assembly.slug,
    excerpt: assembly.excerpt ?? "",
    date: assembly.publishedDate,
  };
}

When NOT to Use Fragments

Not every query needs a shared fragment. Skip fragments for:

• Sitemaps — need only slug and lastModified
• RSS feeds — have unique field requirements
• Count queries — use total without item fields
• One-off queries — inline fields when the selection is unique to that query

Related

• GraphQL Naming - Fragment naming conventions
• page.query.graphql - Using fragments in queries
• File Organization - Where to place fragments
• GraphQL Query Patterns - Fragment composition and best practices