GraphQL fragments should be used to avoid repeating fields in queries, improve maintainability, and enable modular code. 1. Define reusable field selections like fragment UserFields on User { id name email avatar } to eliminate duplication. 2. Use ...UserFields in any query returning User to centralize updates—adding a field requires only one change. 3. Colocate fragments with components, such as defining UserCardFragment in React to declare precise data needs. 4. Build complex queries hierarchically by nesting fragments, like PostFields including UserFields. 5. Follow best practices: use clear names, keep fragments focused, leverage tooling for validation, and avoid excessive nesting. 6. In real-world apps, compose parent queries from component fragments, enabling automatic updates when fragments change. Fragments reduce errors, enhance scalability, and are resolved at query time with no runtime cost, making them essential for efficient GraphQL development.

GraphQL fragments are one of the most underrated yet powerful features of GraphQL. They let you define reusable pieces of queries, making your code cleaner, more maintainable, and less error-prone. Instead of repeating the same fields across multiple queries or components, you can define them once and reuse them wherever needed.

Here’s how fragments make a real difference in day-to-day development.

What Are GraphQL Fragments?

A fragment is a named selection of fields that can be shared across queries, mutations, or other fragments. You define it once and then spread it into your operations using the ... syntax.

For example:

fragment UserFields on User {
  id
  name
  email
  avatar
}

Now you can use this in any query that returns a User:

query GetCurrentUser {
  currentUser {
    ...UserFields
  }
}

query GetUser($id: ID!) {
  user(id: $id) {
    ...UserFields
  }
}

This avoids repeating the same four fields every time you fetch a user.

Why Use Fragments? Key Benefits

1. Avoid Repetition, Improve Maintainability

When you need to add a new field—say, phone—to every place a user is fetched, you only update the fragment. No need to hunt down every query.

Without fragments, you’d manually update multiple queries. With fragments, it’s a one-line change.

2. Colocate Data Requirements with Components

In frontend frameworks like React with Apollo Client, it’s common to define a fragment inside the component that uses it.

const UserCardFragment = gql`
  fragment UserCardFields on User {
    id
    name
    avatar
    role
  }
`;

Then, any parent query that renders UserCard can include ...UserCardFields. This follows the principle of data co-location—the component declares exactly what data it needs.

3. Enable Modular and Scalable Code

As your app grows, so does query complexity. Fragments let you build queries like LEGO blocks.

For example:

fragment PostFields on Post {
  id
  title
  content
  author {
    ...UserFields
  }
  createdAt
}

Now PostFields reuses UserFields. This nesting keeps things DRY and hierarchical.

Best Practices for Using Fragments

• Name them clearly: Use descriptive names like UserProfileFields or CommentListItem so it’s obvious where they’re used.
• Keep them focused: A fragment should reflect a logical unit of data, ideally tied to a UI component or domain object.
• Use in combination with tooling: Apollo Client, Relay, and other clients can validate that your fragments are compatible with the actual schema and warn if fields are missing.
• Avoid over-nesting: While nesting fragments is powerful, too many layers can make queries hard to follow. Use judgment.

Fragments in Real-World Workflows

In a component-based app, each component exports its fragment. Higher-level queries compose these fragments together.

Example structure:

// UserAvatar.js
export const UserAvatarFragment = gql`
  fragment UserAvatarFragment on User {
    avatar
    name
  }
`;

// UserBio.js
export const UserBioFragment = gql`
  fragment UserBioFragment on User {
    name
    bio
    website
  }
`;

// UserProfile.js
const UserProfileQuery = gql`
  query UserProfile($id: ID!) {
    user(id: $id) {
      ...UserAvatarFragment
      ...UserBioFragment
    }
  }
`;

This way, when UserBio needs a new field, you update just that fragment and the query automatically includes it.

Fragments don’t add runtime overhead—they’re resolved at compile/query time. They’re purely a developer experience win.

Basically, if you’re writing the same fields more than once, you should be using a fragment. It’s not magic, but it makes a big difference over time.

The above is the detailed content of The Power of GraphQL Fragments for Reusable Queries. For more information, please follow other related articles on the PHP Chinese website!