Menu
Guides
API Reference
App Development
Storefront Development
VTEX IO Apps
Troubleshooting
Release Notes
Storefront Development
Getting started with storefront solutions
FastStore
Store Framework
CMS Portal (Legacy)
Storefront best practices

Managing content with `scopes` and `requiredScopes`

Use `scopes` and `requiredScopes` to define which store sections can be added to specific pages, ensuring proper content structure for your store.

4 min read
scopes and requiredScopes are Headless CMS schema definitions that determine which store Sections can be added to FastStore's native Content Types.
These features help manage the content structure and ensure store sections are used in appropriate contexts. For example, the Hero component is only available for the homepage or pages like the Product Details Page (PDP).

Before you begin

Update the @faststore/core package version

Make sure you have @faststore/core version 3.0.18 or greater to benefit from this feature. If you do not have the updated package, follow the instructions in Updating the @faststore/core package version.

Set Headless CMS

Make sure you have set up sections.json in your store project by following the Setting up the Headless CMS guide. This file contains the store's custom Section definitions.

Understand FastStore customization options

While FastStore v2 and v3 don't support custom Content Types, you can create custom Sections. To control where these Sections appear, use the requiredScopes property. Your custom Sections use the same scopes as FastStore's native Content Types, ensuring consistency with the existing structure.

scopes

scopes are labels that define the context provided by a Content Type. They help categorize Content Types based on their capabilities.
The scopes are string arrays in FastStore's native Content Type definitions. You can inspect these definitions in the @faststore/core content-types.json file. For example:

_10
{
_10
"id": "home",
_10
"name": "Home",
_10
"scopes": ["home"],
_10
"isSingleton": true,
_10
"configurationSchemaSets": [...]
_10
}

In this example, the Home Content Type stores content for your homepage and has a home scope. This scope definition means that only sections designed for the homepage context can be used with this Content Type.

Default FastStore scopes

When creating custom sections, you can restrict their usage to specific Content Types using these default scopes:
scopes nameContent Type
customLanding Page
globalGlobal Sections
landingLanding Page
pdpProduct Details Page
plpProduct Listing Page
searchSearch Page
Custom sections must use these predefined scopes in their requiredScopes. This ensures they integrate with FastStore's content architecture.

requiredScopes

requiredScopes define the Content Types a section can be used in. Similar to scopes, requiredScopes are specified as string arrays within the section definition in the sections.json file.
A section is only available for a Content Type in Headless CMS if the Content Type's scopes include at least one matching scope from the section's requiredScopes. Sections with an empty requiredScopes array can be used in any Content Type.
While you can define requiredScopes for custom sections, they must use scopes from default Content Types to maintain consistency across all store sections.
In the following example, the ProductShelf section is only available for PDPs:

_10
{
_10
"name": "ProductShelf",
_10
"requiredScopes": ["pdp"],
_10
"schema": {...},
_10
}

Empty requiredScopes

When a section has an empty requiredScopes ([]), the section is available for all Content Types. In the following example, the Navbar section is available for use in any Content Type because it has no required scopes:

_10
{
_10
"name": "Navbar",
_10
"requiredScopes": [ ],
_10
"schema": {...}
_10
}

Default FastStore requiredScopes

When creating custom sections for Headless CMS, you can use these default requiredScopes for specific Content Types:
requiredScopes nameSection name
customCrossSellingShelf
pdpCrossSellingShelf, Breadcrumb, and ProductDetails
plpBreadcrumb and ProductGallery
searchProductGallery

Using scopes and requiredScopes

In the following example, we will make a new Call To Action Section available on the native Landing Page Content Type.
To better understand this tutorial, make sure you create the new Call To Action component by following the instructions in the Creating a new section guide.

Setting up the Headless CMS files

Make sure you have set up sections.json in your store project by following the Setting up the Headless CMS guide.
  1. In the sections.json file, add the following:
    sections.json

    _39
    [
    _39
    {
    _39
    "name": "CallToAction",
    _39
    "requiredScopes": ["custom"],
    _39
    "schema": {
    _39
    "title": "Call To Action",
    _39
    "description": "Get your 20% off on the first purchase!",
    _39
    "type": "object",
    _39
    "required": [
    _39
    "title",
    _39
    "link"
    _39
    ],
    _39
    "properties": {
    _39
    "title": {
    _39
    "title": "Title",
    _39
    "type": "string"
    _39
    },
    _39
    "link": {
    _39
    "title": "Link Path",
    _39
    "type": "object",
    _39
    "required": [
    _39
    "text",
    _39
    "url"
    _39
    ],
    _39
    "properties": {
    _39
    "text": {
    _39
    "title": "Text",
    _39
    "type": "string"
    _39
    },
    _39
    "url": {
    _39
    "title": "URL",
    _39
    "type": "string"
    _39
    }
    _39
    }
    _39
    }
    _39
    }
    _39
    }
    _39
    }
    _39
    ]

The native Landing Page Content Type has the custom scope. When editors open a Landing Page, Headless CMS matches that scope against the Section's requiredScopes and makes the Call To Action Section available.

Syncing the Headless CMS changes

  1. Open the terminal and run yarn cms-sync to sync the new files created in the previous step.
  2. In the VTEX Admin, go to Storefront > Headless CMS, and open the FastStore project.
  3. Click on the Create Document dropdown.
  4. Click Landing Page.
  5. In the Sections tab, click Add Section (+).
  6. Select the Call To Action Section.
  7. Set the Section fields as you wish.
  8. Click Save.
  9. Click Preview to preview the saved content.