> This page is for Developer.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.bigcommerce.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server.

# Querying Within a BigCommerce Storefront

Plan: Developer Foundations

Lesson 7 of 28 · 15 min

## YAML Front Matter

YAML Front Matter is used at the top of Stencil templates to configure certain details about the data loaded during the page render and made available to the Handlebars template context. A `gql` attribute in this front matter can be used to build a custom query to the GraphQL Storefront API.

A query declared in this way will be run before the page response is returned, and the GraphQL response data will be available for direct use within the Stencil template. Because of the context of these requests, they do not require any manual authentication token management.

The following is an example of front matter making a query for a product's metafields, which would be possible in the `product.html` template where the `$productId` variable is automatically made available to GraphQL queries.

```yaml showLineNumbers={false}
gql: "query productById($productId: Int!) {
 site {
   product(entityId: $productId) {
     variants(first: 25) {
       edges {
         node {
           metafields(namespace: "Example Category") {
             edges {
               node {
                 key
                 value
               }
             }
           }
         }
       }
     }
   }
 }
}"
```

Any data in the GraphQL response could then be used in Handlebars:

```handlebars showLineNumbers={false}
{{#if gql.data.site.product}}
{{#each gql.data.site.product.metafields.edges}}
  {{#with node}}
    <label>{{key}}:</label> {{value}}
  {{/with}}
{{/each}}
{{/if}}
```

Different Stencil templates make different GraphQL variables available to front matter, as listed in the [BigCommerce documentation](/developer/docs/storefront/stencil/themes/context/frontmatter-reference).

## Client-Side Use

GraphQL Storefront API calls can be made directly in client-side JS from within a Stencil theme or from a script in the Script Manager. This can be accessed in the control panel in Storefront > Script Manager for single storefront or Channel Manager > Edit Settings for a Channel > Script Manager for multi-storefront.

Stencil makes a **standard** storefront token available automatically. You're not required to generate a token of your own for this context.

Here's an example request using the `{{settings.storefront_api.token}}` Handlebars object and `fetch()`:

```html showLineNumbers={false}
<script>
fetch('/graphql', {
  method: 'POST',
  credentials: 'same-origin',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer {{ settings.storefront_api.token }}' // use auto-generated token
  },
  body: JSON.stringify({
    query: `query MyFirstQuery {
      site {
        settings {
          storeName
        }
        products {
          edges {
            node {
              name
              sku
              defaultImage {
                url(width: 1280)
              }
            }
          }
        }
      }
    }`
  })
})
.then(res => res.json())
.then(data => console.log(data)) // will log JSON result to browser console
.catch(error => console.error(error));
</script>
```

> **Info**
>
> The above code must be used in a place where the `{{settings.storefront_api.token}}` handlebars variable can be accessed in order to get credentials for the API request. For example, `.html` files in Stencil themes and Script Manager.

> **Info**
>
> The fetch request's credentials property must be set to same-origin.

In addition to using `fetch()`, there are other ways to query the API:

* **Using Apollo Client** - Apollo is a popular GraphQL client that is easy to use in BigCommerce themes. For a quick example of adding Apollo Client to Cornerstone, checkout [this](https://github.com/bigcommerce/cornerstone/commit/508feeb1b00d2bb2940771e5e91250a08b6be4d9) Cornerstone commit on GitHub.
* **Using any GraphQL Client** - GraphQL is a standard with client libraries in many languages, so feel free to explore your options.

## Resources

* [Front Matter GraphQL Attributes](/developer/docs/storefront/stencil/themes/context/frontmatter-reference)
* [Querying within a BigCommerce Storefront](/developer/docs/storefront/guides/graphql-storefront-api#querying-within-a-bigcommerce-storefront)
* [Example Using Apollo Client](https://github.com/bigcommerce/cornerstone/compare/graphQL-example)