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.
Step by step
Step 1: Create a new file
- In the
srcfolder of your store code, create afragmentsfolder.
_10mkdir fragments
- In the
fragmentsfolder, create a file namedServerProduct.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: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
| ClientProductGallery | Client | search | PLP | In the hook useProductGalleryQuery() from the ProductListingPage (PLP) and Search Pages. | 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.
_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>()
Query: ServerCollectionPageQuery
| ServerCollectionPage | Server | collection | PLP | In the function getStaticProps() from PLP. | seo, breadcrumbList and meta data from the collection (StoreCollection). | Collection slug that comes from URL. |
How to consume it
Use the
usePLP() hook when integrating your section with a Product Listing Page (PLP).
_10import { usePLP } from "@faststore/core"_10_10const context = usePLP()
Query: ServerProductQuery
| ServerProduct | Server | product | PDP | In the function getStaticProps() from PDP. | General product data from StoreProduct. | The locator with slug key/value. |
How to consume it
usePDP(): Use this hook when integrating your section with a Product Detail Page (PDP).
_10 import { usePDP } from "@faststore/core"_10_10 const context = usePDP()
Query: ClientProductQuery
| 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. |
How to consume it
usePDP(): Use this hook when integrating your section with a Product Detail Page (PDP).
_10 import { usePDP } from "@faststore/core"_10_10 const context = usePDP()
Query: ClientManyProductsQuery
| ClientManyProducts | Client | search | PLP, Search Page, and pages that use ProductShelf, and ProductTiles components. |
| 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.
_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>()
Query: ClientShippingSimulationQuery
| 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
| 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
| 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.