FastStore versions and support levels
Understand FastStore versions, support levels, and guidance for upgrading.
FastStore has four majors: FastStore v1, FastStore v2, FastStore v3, and FastStore v4. FastStore v4 is the current recommended version for all new projects. This document outlines the key differences between these versions, their support levels, and guidelines for upgrading.
FastStore v1
FastStore v1 was the first version of the framework. While it served as the foundation for FastStore, it's no longer actively maintained. New projects must use FastStore v4.
FastStore v2 and v3
FastStore v2 and v3 share the same core architecture and introduced major improvements over FastStore v1, such as:
- Simplified updates: Stores are monitored for version updates with minimal friction, including automatic non-critical updates and a more efficient integration process.
- Separation of VTEX-managed code and store customizations: Clear segmentation between VTEX and custom code to help in the debug process.
- CMS-first approach: Headless CMS manages content updates (texts, images, links) while behavioral and UI component changes remain code-based, ensuring a structured workflow.
- Optimized performance and quality monitoring: Ongoing performance tracking with proactive safeguards to prevent deployments that don't meet Lighthouse and quality standards.
- Semantic versioning: FastStore v2 and v3 use Semantic Versioning for managing releases:
- Majors: Introduce breaking changes, including incompatible API updates.
- Minors: Introduce backward-compatible features.
- Patches: Include backward-compatible bug fixes.
FastStore v4
FastStore v4 is the latest version, building on the same core architecture as v2 and v3 while introducing important updates focused on performance, dependency management, and localization. The key changes in v4 are:
- Centralized dependency management: Next.js and other core dependencies are now managed by
@faststore/cli, ensuring consistency across projects, reducing dependency conflicts, and simplifying long-term maintenance. Next.js is updated to version 16. - Explicit GraphQL dependency: GraphQL is now exposed as an explicit project dependency, giving developers greater control over versions and avoiding hidden dependency issues.
- Localization (Beta): Native localization integrated with the CMS, enabling scalable global storefronts with multi-locale content management, multi-locale catalog support, multiple currencies (trade policies/sales channels), and default locale fallback behavior.
Key differences between FastStore versions
One of the main changes from FastStore v1 to v2 and v3 was the separation between VTEX code and store-specific customizations, which introduced the
core package for VTEX code and reserved the /src folder for store-specific customizations. FastStore v4 builds on this architecture with centralized dependency management via @faststore/cli. The tables below compare all four versions side by side:Packages
FastStore v2, v3, and v4 share the same core packages. The main differences between them are in project onboarding and deployment (see Other aspects below).
| Package name | FastStore v1 | FastStore v2 | FastStore v3 | FastStore v4 |
|---|---|---|---|---|
api | ✅ | ✅ | ✅ | ✅ |
cli | ✅ | ✅ | ✅ | ✅ |
components | ✅ | ✅ | ✅ | ✅ |
core | ❌ | ✅ | ✅ | ✅ |
graphql-utils | ✅ | ✅ | ✅ | ✅ |
lighthouse | ✅ | ✅ | ✅ | ✅ |
sdk | ✅ | ✅ | ✅ | ✅ |
styles | ✅ | ❌ | ❌ | ❌ |
ui | ✅ | ✅ | ✅ | ✅ |
Other aspects
| Aspect | FastStore v1 | FastStore v2 | FastStore v3 | FastStore v4 |
|---|---|---|---|---|
| Documentation | FastStore v1 Portal | Developers Portal | Developers Portal | Developers Portal |
| Project onboarding | Cloning the FastStore starter repository | Onboarding app | WebOps | WebOps |
| Development framework | Gatsby / Next.js | Next.js | Next.js | Next.js 16 (managed by @faststore/cli) |
| GraphQL dependency | Internal | Internal | Internal | Explicit project dependency |
Support levels
Different levels of support are available depending on the FastStore version. The following table details the status, support availability, and recommendations for new projects for each version.
| Criteria | FastStore v1 | FastStore v2 | FastStore v3 | FastStore v4 |
|---|---|---|---|---|
| Status | No longer updated. | No longer updated. | Actively maintained. | Actively maintained. |
| Support | Limited support. Only bugs and vulnerabilities related to public VTEX APIs are addressed. | Limited support. Only bugs and vulnerabilities related to public VTEX APIs are addressed. | Full support. | Full support. |
| New projects | Not supported. | Not available for new projects. Existing v2 stores should upgrade to v4. | Not available for new projects. Existing v3 stores should upgrade to v4. | Recommended for all new storefront implementations. |
If you have any questions about the level of support provided for different FastStore versions, open a ticket with the VTEX Support team.
Upgrade between FastStore versions
Before upgrading to a new FastStore version, contact VTEX to ensure compatibility and a smooth transition. For assistance, open a ticket with the VTEX Support team.
For FastStore projects hosted in the
vtex-sites organization and not using WebOps (FastStore v1), open a ticket with VTEX Support to move your project to your account's GitHub organization and update it to v4.For stores using FastStore v2 hosted in the account's GitHub organization that need to upgrade to v4, follow the guide Upgrading FastStore to v4.
For stores using FastStore v3 that need to upgrade to v4, follow the guide Upgrading FastStore to v4.