Documentation
Feedback
Guides
Storefront Development

Storefront Development
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

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

_10
mkdir fragments

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

_10
touch 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
_10
import { gql } from '@faststore/core/api'
_10
_10
export 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.
Query: ClientProductGalleryQuery
ClientProductGalleryClientsearchPLP
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().

How to consume it

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

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

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

Query: ServerCollectionPageQuery
ServerCollectionPageServercollectionPLPIn 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).

_10
import { usePLP } from "@faststore/core"
_10
_10
const context = usePLP()

Query: ServerProductQuery
ServerProductServerproductPDPIn 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
ClientProductClientproductPDPIn 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
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) with the totalCount from StorePageInfo.
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.

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

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

Query: ClientShippingSimulationQuery
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
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
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.
Contributors
2
Photo of the contributor
Photo of the contributor
+ 2 contributors
Was this helpful?
Yes
No
Suggest edits (Github)
Contributors
2
Photo of the contributor
Photo of the contributor
+ 2 contributors
On this page