Defining Fragments

What is a Fragment?

In the context of GraphQL, a fragment is a reusable piece of a GraphQL query. It allows you to define the shape of data that you want to work with. This is useful when you have multiple queries that need the same shape of data.

In the context of Pigeon, a fragment is defined with either the createRegistration or createDependency functions. It allows you to define the GraphQL fragment, zod schema and any dependencies it requires.

What is the difference between createRegistration and createDependency?

They are identical except for 1 difference. createRegistration requires your schema to include a __typename field.

What does a fragment need.

1. __typename - this is the GraphQL type name. GraphQL endpoints usually provide a explorer, which will show you the type name.
2. fragmentName - (optional) by default Fragment will be appended to the __typename. However, you can override this if required, a few examples of when it is needed will be listed below.
3. fragment - this is the GraphQL fragment, but only the “body” of the fragment. You don’t have to include the fragment on ... portion of the fragment.
4. schema - this is the zod schema that will be used to validate the incoming data. Here you can perform any transformations. Remember zod transforms can be async so if you needed to fetch anything based on validated data, you can do that here.
5. dependencies - (optional) this is an array of other pigeon fragments that your fragment depends on. We’ll use this to collect all the fragments required for a query, ensuring on what you need is included and de-duped.

Demo.

We’ll go through a simple example for defining a Hero Banner fragment. It’ll be made up of 3 things, a title, description and image.

Image Fragment.

We know that the image will be a consistent shape and something we’ll reuse across the application. So we’ll define a createDependency for the image fragment.

import { createDependency } from "@adrocodes/pigeon";
import { z } from "zod";

export const ImageFragment = createDependency({
  __typename: "Asset",
  fragmentName: "ImageFragment",
  fragment: `
    url
    alt
    size { width height }
  `,
  schema: z.object({
    url: z.string().url().min(1),
    alt: z.string().min(1),
    size: z.object({
      width: z.number().positive(),
      height: z.number().positive(),
    }),
  }).transform(({ ...value, size }) => ({
    ...value,
    ...size
  }))
})

Our fictional GraphQL endpoint only has 1 __typename for all asset data. So we’ve defined the __typename as Asset. We’ve also defined a fragmentName as ImageFragment as we might define another fragment for videos, not specifying a fragmentName would cause a conflict.

Important: If you define multiple fragments for 1 typename it is a good idea to define the fragmentName manually to avoid conflicts.

We are also using the transform method to merge the size object into the parent object. This is a simple example of how you can transform data.

Hero Banner Fragment.

import { createRegistration } from "@adrocodes/pigeon";
import { z } from "zod";
import { ImageFragment } from "@modules/image/image.pigeon";

export const HeroBannerFragment = createRegistration({
  __typename: "HeroBanner",
  fragment: `
    title
    description
    image {
      ...${ImageFragment.fragmentName}
    }
  `,
  schema: z.object({
    __typename: z.literal("HeroBanner"),
    title: z.string().min(1),
    description: z.string().nullish(),
    image: ImageFragment.schema,
  }),
  dependencies: [ImageFragment]
})

Here is an example of the createRegistration, when to use createRegistration and createDependency really just depends if you need to include a __typename in your schema. For example, if you are pulling in a list of components and need to render components based on the __typename you would use createRegistration.

We are also using the ImageFragment we defined earlier as a dependency.

• In the fragment we are using the ...${ImageFragment.fragmentName} syntax. In our case, this will turn into ...ImageFragment.
• In the schema we are using the ImageFragment.schema to validate & transform the image field data.
• In the dependencies we are including the ImageFragment so that when we collect all the fragments required for a query, we include the ImageFragment.

Very important to use fragmentName within the fragment field, using ImageFragment.fragment will inject the actual fragment into the query, and can cause a error about defining a fragment but not using it.

If your UI component required different props to what the schema defines, for example, key names are different. You can use the transform method to transform the data into what your UI component needs. This avoids needing to change the UI component and/or requiring the frontend to add transformation logic to components.