⚠️ After March 18, 2024, the FastStore documentation will be migrated to the Developer Portal. For more information, access the official release note.

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.

ℹ️

To access the list of queries and their corresponding fragments, refer to 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.


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
  1. In the fragments folder, create the file named ServerProduct.ts.
touch ServerProduct.ts
⚠️

The name of the file should match the name of the query you want to extend without the Query suffix. In our example we're extending the ServerProductQuery, so the fragment file must be 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:

src/fragments/ServerProduct.ts
 
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
    FragmentSideQuery operationPageWhere is usedReturnParameters
    ClientProductGalleryClientsearchPLP

    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
    FragmentSideQuery operationPageWhere is usedReturnParameters
    ServerCollectionPageServercollectionPLPIn 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
    FragmentSideQuery operationPageWhere is usedReturnParameters
    ServerProductServerproductPDPIn 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
    FragmentSideQuery operationPageWhere is usedReturnParameters
    ClientProductClientproductPDPIn 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
    FragmentSideQuery operationPageWhere is usedReturnParameters
    ClientManyProductsClientsearch

    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
    FragmentSideQuery operationPageWhere is usedReturnParameters
    ClientShippingSimulationClientshippingPDPIn 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
    FragmentSideQuery operationPageWhere is usedReturnParameters
    ClientSearchSuggestionsClientsearchSearchInput 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
    FragmentSideQuery operationPageWhere is usedReturnParameters
    ClientTopSearchSuggestionsClientsearchSearchInput 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.