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 utilized within GraphQL fragments.

Fragments (opens in a new tab) in GraphQL are reusable units that enhance query functionality. FastStore associates these fragments with the existing queries used on its pages to incorporate the newly exposed fields.

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.

Before you start

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 (opens in a new tab).

Step by step

Step 1: Create a new file

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

mkdir fragments

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

touch ServerProduct.ts

Step 2: Define the GraphQL fragment

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

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

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.

• Query: ClientProductGalleryQuery

  Fragment	Side	Query operation	Page	Where is used	Return	Parameters
  ClientProductGallery	Client	search	PLP	In the hook useProductGalleryQuery() from the ProductListingPage (PLP) and Search Pages.	Products totalCount from StorePageInfo (opens in a new tab), and facets (StoreFacet (opens in a new tab)) from StoreSearchResult (opens in a new tab).	Frontend data from the useSearch() and useLocalizedVariables() hooks, the latter uses useSession().

  
  

  How to consume it

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

  import { usePage } from "@faststore/core"
   
  const 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.

  import { usePage } from "@faststore/core"
   
  const context = usePage<PLPContext | SearchPageContext>()
• Query: ServerCollectionPageQuery

  Fragment	Side	Query operation	Page	Where is used	Return	Parameters
  ServerCollectionPage	Server	collection	PLP	In the function getStaticProps() from PLP.	seo, breadcrumbList and meta data from the collection (StoreCollection (opens in a new tab)).	Collection slug that comes from URL.

  
  

  How to consume it

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

  import { usePLP } from "@faststore/core"
   
  const context = usePLP()
• Query: ServerProductQuery

  Fragment	Side	Query operation	Page	Where is used	Return	Parameters
  ServerProduct	Server	product	PDP	In the function getStaticProps() from PDP.	General product data from StoreProduct (opens in a new tab).	The locator with slug key/value.

  
  

  How to consume it

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

    import { usePDP } from "@faststore/core"
   
    const context = usePDP()
• Query: ClientProductQuery

  Fragment	Side	Query operation	Page	Where is used	Return	Parameters
  ClientProduct	Client	product	PDP	In the hook useProductQuery() from PDP.	General product data from StoreProduct (opens in a new tab) 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.

  
  

  How to consume it

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

    import { usePDP } from "@faststore/core"
   
    const context = usePDP()
• Query: ClientManyProductsQuery

  Fragment	Side	Query operation	Page	Where is used	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 (opens in a new tab)) with the totalCount from StorePageInfo (opens in a new tab).	Frontend data from the useLocalizedVariables() and useSession() hooks.

  
  

  How to consume it

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

  import { usePage } from "@faststore/core"
   
  const 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.

  import { usePage } from "@faststore/core"
   
  const context = usePage<PLPContext | SearchPageContext>()
• Query: ClientShippingSimulationQuery

  Fragment	Side	Query operation	Page	Where is used	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).

  
  

  How to consume it

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

• Query: ClientSearchSuggestionsQuery

  Fragment	Side	Query operation	Page	Where is used	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.

  
  

  How to consume it

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

• Query: ClientTopSearchSuggestionsQuery

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

  
  

  How to consume it

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