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 v4 or the latest version. 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

Run the following commands:

vtex login
vtex content generate-schema cms/faststore/components cms/faststore/pages -o cms/faststore/schema.json -b vtex.faststore
vtex content upload-schema cms/faststore/schema.json

Stores using CMS without custom components

Run the following commands:

vtex login
vtex content upload-schema node_modules/@faststore/core/cms/faststore/schema.json

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.