Extending queries using fragments

After defining the new fields exposed by the FastStore API Extension, the next step is to specify where these fields will be used within GraphQL fragments.

Fragments in GraphQL are reusable units that enhance query functionality. FastStore associates these fragments with the existing queries on its pages to incorporate the newly exposed fields.

To access the list of queries and their corresponding fragments, check the extendable queries section.

Follow the steps below to add custom fields to an existing query. We will use the ServerProduct query as an example to illustrate how to extend it.

Before you begin

Avoid over-fetching data on pages

Even though you can add information to the FastStore API schema, you must be careful not to over-fetch data on your pages. See the best practices for fetching data on your storefront.

Instructions

Step 1: Create a new file

In the src folder of your store code, create a fragments folder.


_10mkdir fragments

In the fragments folder, create a file named ServerProduct.ts.


_10touch ServerProduct.ts

The file name should match the name of the query you want to extend.

Step 2: Define the GraphQL fragment

In the ServerProduct.ts file, define the GraphQL fragment corresponding to the new fields you want to retrieve. In this example, the customData property represents the new field. Use the following syntax as a guideline:

src/fragments/ServerProduct.ts


_10
_10import { gql } from '@faststore/core/api'
_10
_10export const fragment = gql(`
_10  fragment ServerProduct on Query {
_10    product(locator: $locator) {
_10        customData
_10    }
_10  }
_10`)

Now, you can consume customData by following the Consuming FastStore API extension with custom components guide.

Extendable queries

Extendable queries in FastStore's GraphQL API are predefined queries that form the basis for fetching data from the API. These queries enable customization by allowing the addition or modification of fields to align data retrieval with your store-specific requirements.

`ClientProductGalleryQuery`

Fragment	Side	Query operation	Page	Usage	Return	Parameters
`ClientProductGallery`	`Client`	`search`	PLP	In the hook `useProductGalleryQuery()` from the `ProductListingPage` (`PLP`) and `Search` Pages.	Products totalCount from StorePageInfo, and facets (StoreFacet) from StoreSearchResult.	Frontend data from the `useSearch()` and `useLocalizedVariables()` hooks, the latter uses `useSession()`.

Consuming the query

Use the usePage() hook when you have a single section that is used in more than one type of page.


_10import { usePage } from "@faststore/core"
_10
_10const context = usePage()

This hook returns one of the following types as context: PDPContext, PLPContext, or SearchPageContext, and you can decide how to handle it depending on the page that will use this hook by passing the types as generics.


_10import { usePage } from "@faststore/core"
_10
_10const context = usePage<PLPContext | SearchPageContext>()

`ServerCollectionPageQuery`

Fragment	Side	Query operation	Page	Usage	Return	Parameters
`ServerCollectionPage`	`Server`	`collection`	PLP	In the function `getStaticProps()` from `PLP`.	`seo`, `breadcrumbList` and `metaData` from the collection (StoreCollection).	Collection `slug` that comes from URL.

Consuming the query

Use the usePLP() hook when integrating your section with a Product Listing Page (PLP).


_10import { usePLP } from "@faststore/core"
_10
_10const context = usePLP()

`ServerProductQuery`

Fragment	Side	Query operation	Page	Usage	Return	Parameters
`ServerProduct`	`Server`	`product`	PDP	In the function `getStaticProps()` from `PDP`.	General product data from StoreProduct.	The `locator` with `slug` key/value.

Consuming the query

usePDP(): Use this hook when integrating your section with a Product Detail Page (PDP).


_10import { usePDP } from "@faststore/core"
_10
_10const context = usePDP()

`ClientProductQuery`

Fragment	Side	Query operation	Page	Usage	Return	Parameters
`ClientProduct`	`Client`	`product`	PDP	In the hook `useProductQuery()` from `PDP`.	General product data from StoreProduct to update product data inside `PDP` (product coming from `ServerProductQuery` as fallback).	Frontend data from the `useSession()` hook in the locator array with `id`, `channel`, `locale` as key/values.

Consuming the query

usePDP(): Use this hook when integrating your section with a Product Detail Page (PDP).


_10import { usePDP } from "@faststore/core"
_10
_10const context = usePDP()

When using both ServerProductQuery and ClientProductQuery on the PDP, remember that ServerProductQuery fetches the initial product data from the server, while ClientProductQuery updates that data based on user actions. Make sure to manage how these queries interact to ensure data accuracy. When developing API extensions, prioritize keeping the data consistent and using both queries appropriately to provide users with the most up-to-date information.

`ClientManyProductsQuery`

Fragment	Side	Query operation	Page	Usage	Return	Parameters
`ClientManyProducts`	`Client`	`search`	`PLP`, `Search Page`, and pages that use `ProductShelf`, and `ProductTiles` components.	In the hook `usePageProductsQuery()` from `PLP` and `Search Page`. In the hook `useProductsPrefetch()` to prefetch the previous (prev) and next (next) page from the current `PLP` or `Search Page`. In the hook `useProductsQuery()`, in `ProductShelf`, `ProductTiles` components, that can be used on multiple pages.	General products data (StoreProduct) with the `totalCount` from StorePageInfo.	Frontend data from the `useLocalizedVariables()` and `useSession()` hooks.

Consuming the query

Use the usePage() hook when you have a single section that is used in more than one type of page.


_10import { usePage } from "@faststore/core"
_10
_10const context = usePage()


_10import { usePage } from "@faststore/core"
_10
_10const context = usePage<PLPContext | SearchPageContext>()

`ClientShippingSimulationQuery`

Fragment	Side	Query operation	Page	Usage	Return	Parameters
`ClientShippingSimulation`	`Client`	`shipping`	PDP	In the `ShippingSimulation` component.	General shipping simulation data with the `address` and `logisticsInfo`.	Frontend `country`, and `postalCode` from `useSession()` hook, and the `items` Array of `IShippingItem` (`id`, `quantity`, and `seller`).

Consuming the query

You can use the experimental useShippingSimulation_unstable() hook, or the getShippingSimulation_unstable() function to retrieve shipping data in Overridable (custom) components.

`ClientSearchSuggestionsQuery`

Fragment	Side	Query operation	Page	Usage	Return	Parameters
`ClientSearchSuggestions`	`Client`	`search`	`SearchInput` component from `GlobalSection`.	In the `SearchInput` component.	General search data with the `suggestions` and `products`.	Frontend data from `useSession()` hook, and the `term` searched.

Consuming the query

You can use the experimental useSuggestions_unstable() hook to retrieve the search suggestions data in Overridable (custom) components.

`ClientTopSearchSuggestionsQuery`

Fragment	Side	Query operation	Page	Usage	Return	Parameters
`ClientTopSearchSuggestions`	`Client`	`search`	`SearchInput` component from `GlobalSection`.	In the `SearchInput` component.	The top searched suggestions.	Frontend data from `useSession()` hook.

Consuming the query

You can use the experimental useTopSearch_unstable() hook to retrieve the top search suggestions data in Overridable (custom) components.