Upgrading FastStore to v4

In this guide, you'll learn how to upgrade your FastStore project to the v4 major version. It covers the main changes introduced in this version, including updates to dependencies, configuration, and styling utilities.

Follow the instructions that match your current FastStore version to ensure a smooth and consistent migration.

Upgrading from v3 to v4

Change the `@faststore/cli` version

Make sure your project is up to date with FastStore 4.1.0 version or the latest. To do so, follow the steps in Updating the '@faststore/cli' package version.

Update `package.json`

Open your package.json and apply the following changes:

	Description
Add `graphql` to `^16.11.0`	GraphQL must now be explicitly declared as a dependency in your `package.json` file. It should be version `^16.11.0` or higher. Previously, this was managed internally by `@faststore/cli`.
Remove the `next` entry from `dependencies`	Next.js is now managed internally by `@faststore/cli`, and declaring it separately causes version conflicts.
Update `TypeScript` version	To ensure correct TypeScript typing, update the TypeScript version to `^5.9.3`.


_10{
_10  ...
_10  "dependencies": {
_10    "@faststore/cli": "^4.0.0",
_10    "graphql": "^16.11.0",
_10    "react": "^18.2.0",
_10    "react-dom": "^18.2.0"
_10  },
_10
_10}


_10{
_10  ...
_10  "devDependencies": {
_10    ...
_10    "typescript": "^5.9.3"
_10    ...
_10  },
_10}

The example above shows only the entries relevant to this change. Keep the rest of your package.json intact.

Update `package.json` for stores using the monorepo

For stores using the monorepo, in addition to the updates described in Update package.json, you must also add @inquirer/type to the resolutions field.

This is required to ensure consistent dependency resolution across the monorepo and to avoid version conflicts related to the inquirer package.


_10{
_10  ...
_10  "resolutions": {
_10    ...
_10    "@inquirer/type": "^1.5.5"
_10  }
_10}

Update the Node.js version in discovery.config.js

In your discovery.config.js, ensure the experimental object includes nodeVersion: 24:


_10experimental: {
_10  nodeVersion: 24,
_10},

Update the SCSS utilities import

Only applies if you have custom SCSS files using FastStore utility mixins.

In previous versions, FastStore utility mixins were imported globally. This meant you could use mixins like media or layout-content without explicitly importing them in your file.

With FastStore v4, utilities are no longer globally available. You must explicitly import them in each SCSS file where they are used. This improves traceability and avoids conflicts between mixins.

Before (global import, no namespace):


_10@import "~@faststore/ui/src/styles/base/utilities";
_10
_10/* Usage without namespace */
_10@include media("<tablet") { ... }
_10@include layout-content;

After (explicit import at the top of the file):


_10@use "@faststore/ui/src/styles/base/utilities" as u;
_10
_10/* Usage with namespace */
_10@include u.media("<tablet") { ... }
_10@include u.layout-content;

By using @use, you explicitly declare dependencies and access the mixins through a namespace (u in this case), making the origin of each utility clear and easier to maintain.

Any file with custom mixins needs to be updated to adapt to the Sass library update, which no longer allows @import; only @use is supported.

Update imports to use `@faststore/core/api`

@faststore/graphql-utils is deprecated in FastStore v4. The gql tag used for GraphQL documents should no longer be imported from that package. Update imports to use @faststore/core/api instead. For example, replace import { gql } from '@faststore/graphql-utils' with import { gql } from '@faststore/core/api'.

Sync the change with CMS

After updating the imports, you must sync the changes with the CMS. The steps depend on which CMS your store uses.

Stores using Headless CMS (legacy)

FastStore v4 introduces breaking changes that move several previously hardcoded labels and messages into the CMS. Before publishing, you must sync the CMS, configure the new fields in the affected sections, and republish any pages that use them.

Run yarn cms-sync to sync the schema changes with the Headless CMS.
Review the breaking changes below, configure the new fields in the relevant sections, and republish the affected pages.

Breaking changes affecting Headless CMS (legacy) sections

The following components had hardcoded labels removed in v4. Each one now exposes new fields in the corresponding Headless CMS (legacy) section that must be configured after the sync.

Breadcrumb (PR #3099): The "All products" label, previously fixed in code for pages without a breadcrumb list (such as Search), is now configurable through the Fallback label field in the Breadcrumb section. After syncing, configure this field and republish pages that include the Breadcrumb section.
Sort (PR #3100): Sort option labels are no longer hardcoded. They are now configured through the sortBySelector field in the ProductGallery section. After syncing, configure the labels and republish pages that include the ProductGallery section.
Invalid quantity toast (PR #3102): The toast message shown when an invalid quantity is entered (in the PDP quantity selector, the Navbar search suggestions with quick order enabled, or the SKU matrix sidebar) is no longer hardcoded. It is now configured through the invalidQuantityToast field, available in both the Navbar and ProductDetails sections. After syncing, configure the labels in both sections and republish the affected pages.
ScrollToTopButton: Removed from the ProductListing template. It must now be added manually through the Headless CMS on PLP and Search pages.
Other components with hardcoded messages removed (PR #3192): Hardcoded labels were also removed from the components listed below. After syncing the CMS, review the corresponding sections and configure the new fields as needed:
- Filter: FilterSlider, FilterDesktop, FilterDeliveryMethodFacet
- Region: RegionSlider, RegionPopover
- Cart: EmptyCart (title, buttonLabel)
- Product: ProductCard, ProductCardContent (buttonLabel, outOfStockLabel, includeTaxesLabel, sponsoredLabel), ProductDetailsSettings (buyButtonTitle)
- Common: Breadcrumb (alt, icon), Footer (logoLink defaults), Navbar (collapseSearchAriaLabel)
- Search: SearchProductItem (outOfStockLabel in quickOrderSettings), SearchInput, SearchTop, SearchHistory
- EmptyGallery
- Hooks: useDeliveryPromise, useShippingSimulation
- PickupPointCards

Stores using CMS with custom components

If your store already uses the new Content plugin format, with component schemas and Content Type schemas stored in separate .jsonc files, you can skip the migration steps in this section and follow the instructions in Generate and upload the schema below.

If your store still uses the legacy sections.json and content-types.json files, you must first split them into the new format before generating the schema.

If sections.json is still in the legacy format, run the following command:


_10vtex content split-components -i cms/faststore/sections.json -o cms/faststore/components

If content-types.json is still in the legacy format, run:


_10vtex content split-content-types -i cms/faststore/content-types.json -s cms/faststore/sections.json -o cms/faststore/pages

The paths above are examples based on the default FastStore project structure. If your project stores component schemas and Content Type schemas in different locations, adjust the input and output paths accordingly.

Generate and upload the schema

After ensuring your CMS files are in the new format, generate and upload the schema:


_10vtex login {accountName}

Generate the schema:


_10vtex content generate-schema cms/faststore/components cms/faststore/pages -o cms/faststore/schema.json

Upload the schema:


_10vtex content upload-schema cms/faststore/schema.json

The table below explains the command arguments:

Argument	Description
`cms/faststore/components`	Directory containing your component schema files.
`cms/faststore/pages`	Directory containing your Content Type schema files.
`-o cms/faststore/schema.json`	Local output path for the generated schema file before upload.

For more details on these commands, see Content plugin.

Stores using CMS without custom components

If your store does not have any custom CMS schema files yet and should use only the default FastStore schema, you do not need to run generate-schema. Instead, create a schema.json file in cms/faststore and add the following content:


_10{
_10  "$base": "vtex.faststore"
_10}

Upload this content by running the following command in the terminal:


_10vtex content upload-schema cms/faststore/schema.json

This creates a schema for your store in CMS that points to the FastStore base schema.

You can also use "vtex.faststore@4.1.0" as the $base value if you want to pin the version explicitly. Otherwise, use "vtex.faststore" to get the latest version.

After uploading the file, you can safely delete the local cms/faststore/schema.json file.

Update Node.js runtime version in WebOps (existing projects only)

To ensure compatibility with FastStore v4, update your project to use Node.js v24 in the runtime environment.

Test locally with Node.js v24

Build and run your project locally using Node.js v24. Identify and fix any compatibility issues that may arise during the process.

Update Node.js version in WebOps and deploy

After validating locally, update the Node.js version to v24 in WebOps and deploy your changes:

Open the VTEX Admin and access Storefront > FastStore WebOps.
Go to the Settings tab and in the Node.js version configuration, set it to v24.
Click Save.
Trigger a new deployment to apply the changes.

Upgrading from v2 to v4

To upgrade your project from v2 to v4, first follow the instructions in Upgrading from FastStore v2 to v3. Once completed, proceed with the steps in Upgrading from v3 to v4.