@faststore/core 4.5.0-dev.3 → 4.5.0-dev.5

package/CHANGELOG.md

@@ -3,6 +3,18 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [4.5.0-dev.5](https://github.com/vtex/faststore/compare/v4.5.0-dev.4...v4.5.0-dev.5) (2026-07-27)
+
+### Features
+
+- forward Pricing Fallback price token to Checkout ([#3415](https://github.com/vtex/faststore/issues/3415)) ([bc6cda2](https://github.com/vtex/faststore/commit/bc6cda2cdaed0540896ca7202246ad2d3dcd5766))
+
+# [4.5.0-dev.4](https://github.com/vtex/faststore/compare/v4.5.0-dev.3...v4.5.0-dev.4) (2026-07-24)
+
+### Features
+
+- **core:** localized product URLs, breadcrumbs PDP and PLPs ([#3402](https://github.com/vtex/faststore/issues/3402)) ([3c6b6ef](https://github.com/vtex/faststore/commit/3c6b6ef29ef902ccae3ff784297b24e6c6bc7802)), closes [#3352](https://github.com/vtex/faststore/issues/3352) [#3401](https://github.com/vtex/faststore/issues/3401)
+
 # [4.5.0-dev.3](https://github.com/vtex/faststore/compare/v4.5.0-dev.2...v4.5.0-dev.3) (2026-07-22)
 
 ### Features

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@faststore/core",
-  "version": "4.5.0-dev.3",
+  "version": "4.5.0-dev.5",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -71,11 +71,11 @@
     "style-loader": "^3.3.1",
     "swr": "^2.2.5",
     "use-sync-external-store": "^1.6.0",
-    "@faststore/diagnostics": "4.5.0-dev.3",
-    "@faststore/lighthouse": "4.5.0-dev.3",
-    "@faststore/sdk": "4.5.0-dev.3",
-    "@faststore/api": "4.5.0-dev.3",
-    "@faststore/ui": "4.5.0-dev.3"
+    "@faststore/api": "4.5.0-dev.5",
+    "@faststore/diagnostics": "4.5.0-dev.5",
+    "@faststore/sdk": "4.5.0-dev.5",
+    "@faststore/lighthouse": "4.5.0-dev.5",
+    "@faststore/ui": "4.5.0-dev.5"
   },
   "devDependencies": {
     "@cypress/code-coverage": "^3.12.1",

package/src/components/product/ProductCard/ProductCard.tsx

@@ -234,6 +234,7 @@ export const fragment = gql(`
         listPriceWithTaxes
         priceWithTaxes
         quantity
+        priceToken
         seller {
           identifier
         }

package/src/components/search/SearchProductItem/SearchProductItem.tsx

@@ -82,6 +82,7 @@ function SearchProductItem({
           listPriceWithTaxes,
           seller,
           priceWithTaxes,
+          priceToken,
           quantity: offersQuantity,
         },
       ],
@@ -127,6 +128,7 @@ function SearchProductItem({
       listPriceWithTaxes,
       seller,
       quantity,
+      priceToken,
       itemOffered: {
         sku,
         name,

package/src/components/sections/EmptyState/EmptyState.tsx

@@ -1,5 +1,5 @@
-import type { PropsWithChildren } from 'react'
 import { useRouter } from 'next/router'
+import type { PropsWithChildren } from 'react'
 
 import { Icon as UIIcon, Loader as UILoader } from '@faststore/ui'
 
@@ -9,8 +9,8 @@ import Section from '../Section'
 
 import styles from './section.module.scss'
 
-import { EmptyStateDefaultComponents } from './DefaultComponents'
 import { getOverridableSection } from '../../../sdk/overrides/getOverriddenSection'
+import { EmptyStateDefaultComponents } from './DefaultComponents'
 
 export interface EmptyStateProps {
   /**
@@ -53,11 +53,12 @@ const useErrorState = () => {
     query: { errorId, fromUrl },
     pathname,
     asPath,
+    locale,
   } = router
 
   return {
     errorId,
-    fromUrl: fromUrl ?? asPath ?? pathname,
+    fromUrl: fromUrl ?? (locale ? `/${locale}${asPath}` : asPath) ?? pathname,
   }
 }
 

package/src/components/sections/ProductDetails/ProductDetails.tsx

@@ -401,6 +401,7 @@ export const fragment = gql(`
         listPrice
         listPriceWithTaxes
         quantity
+        priceToken
         seller {
           identifier
         }

package/src/components/templates/ProductListingPage/ProductListingPage.tsx

@@ -21,6 +21,7 @@ import type { PLPContentType } from 'src/server/cms/plp'
 
 import storeConfig from '../../../../discovery.config'
 import { faststoreLoader } from 'src/components/ui/Image/loader'
+import { LocalizedProductProvider } from 'src/sdk/localization/LocalizedProductContext'
 import ProductListing from './ProductListing'
 import { getStoreURL } from 'src/sdk/localization/useLocalizationConfig'
 
@@ -142,43 +143,48 @@ export default function ProductListingPage({
     : undefined
 
   return (
-    <SearchProvider
-      onChange={applySearchState}
-      itemsPerPage={itemsPerPage}
-      shouldResetInfiniteScroll={!storeConfig.experimental?.scrollRestoration}
-      {...searchParams}
+    <LocalizedProductProvider
+      otherLocales={server.collection?.otherLocales}
+      urlSuffix=""
     >
-      {lcpImageUrl && (
-        <Head>
-          <link
-            rel="preload"
-            as="image"
-            href={lcpImageUrl}
-            fetchPriority="high"
-          />
-        </Head>
-      )}
-      {/* SEO */}
-      <NextSeo
-        title={title}
-        description={description}
-        titleTemplate={titleTemplate}
-        canonical={canonical}
-        openGraph={{
-          type: 'website',
-          title,
-          description,
-        }}
-      />
-      <BreadcrumbJsonLd itemListElements={itemListElements} />
-
-      <ProductListing
-        globalSections={globalSections}
-        globalSettings={globalSettings}
-        page={plpContentType}
-        data={server}
-        serverManyProductsVariables={serverManyProductsVariables}
-      />
-    </SearchProvider>
+      <SearchProvider
+        onChange={applySearchState}
+        itemsPerPage={itemsPerPage}
+        shouldResetInfiniteScroll={!storeConfig.experimental?.scrollRestoration}
+        {...searchParams}
+      >
+        {lcpImageUrl && (
+          <Head>
+            <link
+              rel="preload"
+              as="image"
+              href={lcpImageUrl}
+              fetchPriority="high"
+            />
+          </Head>
+        )}
+        {/* SEO */}
+        <NextSeo
+          title={title}
+          description={description}
+          titleTemplate={titleTemplate}
+          canonical={canonical}
+          openGraph={{
+            type: 'website',
+            title,
+            description,
+          }}
+        />
+        <BreadcrumbJsonLd itemListElements={itemListElements} />
+
+        <ProductListing
+          globalSections={globalSections}
+          globalSettings={globalSettings}
+          page={plpContentType}
+          data={server}
+          serverManyProductsVariables={serverManyProductsVariables}
+        />
+      </SearchProvider>
+    </LocalizedProductProvider>
   )
 }

package/src/components/ui/Breadcrumb/Breadcrumb.tsx

@@ -2,7 +2,6 @@ import type { BreadcrumbProps as UIBreadcrumbProps } from '@faststore/ui'
 import { Breadcrumb as UIBreadcrumb } from '@faststore/ui'
 import { memo } from 'react'
 
-import storeConfig from 'discovery.config'
 import Link from 'src/components/ui/Link'
 import { useOverrideComponents } from 'src/sdk/overrides/OverrideContext'
 export interface BreadcrumbProps extends UIBreadcrumbProps {
@@ -32,17 +31,11 @@ const Breadcrumb = ({ icon, alt, ...otherProps }: BreadcrumbProps) => {
           />
         </Link>
       }
-      renderLink={({ itemProps: { item: link, name } }) =>
-        // workaround to display the name without a link since localized slug is not available yet
-        // TODO: when localized slugs are available remove this workaround
-        storeConfig.localization?.enabled ? (
-          <span data-fs-breadcrumb-link>{name}</span>
-        ) : (
-          <Link data-fs-breadcrumb-link href={link} prefetch={false}>
-            {name}
-          </Link>
-        )
-      }
+      renderLink={({ itemProps: { item: link, name } }) => (
+        <Link data-fs-breadcrumb-link href={link} prefetch={false}>
+          {name}
+        </Link>
+      )}
       {...Breadcrumb.props}
       {...otherProps}
     />

package/src/components/ui/LocalizationButton/LocalizationButton.tsx

@@ -6,6 +6,7 @@ import { Icon, Button as UIButton } from '@faststore/ui'
 import storeConfig from 'discovery.config'
 import LocalizationSelector from 'src/components/localization/LocalizationSelector'
 import { useBindingSelector } from 'src/sdk/localization'
+import { useLocalizedProduct } from 'src/sdk/localization/LocalizedProductContext'
 import { useSession } from 'src/sdk/session'
 
 export interface LocalizationButtonErrorMessages {
@@ -41,6 +42,9 @@ const LocalizationButton = ({
   const [isSelectorOpen, setIsSelectorOpen] = useState(false)
   const buttonRef = useRef<HTMLButtonElement>(null)
 
+  const otherLocales = useLocalizedProduct()?.otherLocales ?? undefined
+  const urlSuffix = useLocalizedProduct()?.urlSuffix ?? '/p'
+
   const {
     languages,
     currencies,
@@ -52,7 +56,7 @@ const LocalizationButton = ({
     reset,
     isSaveEnabled,
     error,
-  } = useBindingSelector()
+  } = useBindingSelector(otherLocales, urlSuffix)
 
   const { locale: sessionLocale, currency: sessionCurrency } = useSession()
 

package/src/components/ui/ProductComparison/ProductComparisonSidebar.tsx

@@ -89,6 +89,7 @@ function ProductComparisonSidebar(props: UIProductComparisonSidebarProps) {
             listPriceWithTaxes: offer.listPriceWithTaxes,
             priceWithTaxes: offer.priceWithTaxes,
             quantity: offer.quantity,
+            priceToken: offer.priceToken,
             seller: { identifier: offer.seller.identifier },
           })),
         },
@@ -129,6 +130,7 @@ function ProductComparisonSidebar(props: UIProductComparisonSidebarProps) {
                 seller,
                 quantity,
                 listPriceWithTaxes,
+                priceToken,
               },
             ],
           },
@@ -141,6 +143,7 @@ function ProductComparisonSidebar(props: UIProductComparisonSidebarProps) {
           listPrice,
           listPriceWithTaxes,
           seller,
+          priceToken,
           quantity: productIdToBuy === id ? 1 : 0,
           itemOffered: {
             sku,
@@ -226,6 +229,7 @@ export const fragment = gql(`
         listPrice
         quantity
         listPriceWithTaxes
+        priceToken
         seller {
           identifier
         }

package/src/components/ui/ProductDetails/ProductDetailsSettings.tsx

@@ -79,6 +79,7 @@ function ProductDetailsSettings({
           listPrice,
           seller,
           listPriceWithTaxes,
+          priceToken,
         },
       ],
     },
@@ -92,6 +93,7 @@ function ProductDetailsSettings({
     listPriceWithTaxes,
     seller,
     quantity,
+    priceToken,
     itemOffered: {
       sku,
       name: variantName,

package/src/components/ui/SKUMatrix/SKUMatrixSidebar.tsx

@@ -53,7 +53,15 @@ function SKUMatrixSidebar(props: SKUMatrixProps) {
     .map((item) => {
       const {
         offers: {
-          offers: [{ price, priceWithTaxes, listPrice, listPriceWithTaxes }],
+          offers: [
+            {
+              price,
+              priceWithTaxes,
+              listPrice,
+              listPriceWithTaxes,
+              priceToken,
+            },
+          ],
         },
       } = item
 
@@ -64,6 +72,7 @@ function SKUMatrixSidebar(props: SKUMatrixProps) {
         listPrice,
         listPriceWithTaxes,
         seller,
+        priceToken,
         quantity: item.selectedCount,
         itemOffered: {
           sku: item.id,
@@ -131,6 +140,7 @@ export const fragment = gql(`
               itemCondition
               availability
               quantity
+              priceToken
             }
           }
           additionalProperty {

package/src/experimental/index.ts

@@ -82,3 +82,5 @@ export type { UseBindingSelectorReturn } from '../sdk/localization/useBindingSel
 export { useLink as useLink_unstable } from '../sdk/ui/useLink'
 export { default as Link_unstable } from '../components/ui/Link'
 export { localizeRedirectDestination as localizeRedirectDestination_unstable } from '../utils/localization/localizeRedirectDestination'
+export { useLocalizedProduct as useLocalizedProduct_unstable } from '../sdk/localization/LocalizedProductContext'
+export type { LocalizedProductLocale as LocalizedProductLocale_unstable } from '../sdk/localization/LocalizedProductContext'

package/src/pages/[...slug].tsx

@@ -106,6 +106,10 @@ const query = gql(`
           value
         }
       }
+      otherLocales {
+        locale
+        slug
+      }
     }
   }
 `)
@@ -172,6 +176,7 @@ export const getStaticProps: GetStaticProps<
     >({
       variables: { slug },
       operation: query,
+      locale,
     }),
     contentService.getPlpContent(
       {

package/src/pages/[slug]/p.tsx

@@ -34,6 +34,7 @@ import {
   getGlobalSectionsData,
   type GlobalSectionsData,
 } from 'src/components/cms/GlobalSections'
+import { LocalizedProductProvider } from 'src/sdk/localization/LocalizedProductContext'
 import { getStoreURL } from 'src/sdk/localization/useLocalizationConfig'
 import { getOfferUrl, useOffer } from 'src/sdk/offer'
 import PageProvider, { type PDPContext } from 'src/sdk/overrides/PageProvider'
@@ -94,6 +95,62 @@ const overwriteMerge = (_: any[], sourceArray: any[]) => sourceArray
 const isClientOfferEnabled = (storeConfig as StoreConfig).experimental
   .enableClientOffer
 
+function buildHreflangLinks(
+  storeConfig: StoreConfig,
+  otherLocales: Array<{ locale: string; slug: string }> | null | undefined
+): Array<{ rel: string; hrefLang: string; href: string }> {
+  if (!storeConfig.localization?.enabled || !otherLocales?.length) return []
+
+  const locales = storeConfig.localization.locales
+  const baseStoreUrl = storeConfig.storeUrl.replace(/\/$/, '')
+  const defaultLocale = storeConfig.localization.defaultLocale
+  const links: Array<{ rel: string; hrefLang: string; href: string }> = []
+
+  for (const { locale, slug } of otherLocales) {
+    const bindingUrl = locales?.[locale]?.bindings?.[0]?.url
+    if (typeof bindingUrl === 'string' && bindingUrl.length > 0) {
+      links.push({
+        rel: 'alternate',
+        hrefLang: locale,
+        href: `${bindingUrl.replace(/\/$/, '')}/${slug}/p`,
+      })
+    }
+  }
+
+  // PREMISE: the default locale is served at the store root (no locale prefix),
+  // which is how Next.js i18n sub-path routing works — the `defaultLocale` has no
+  // prefix while other locales live under `/{locale}`. Hence `x-default` points to
+  // `${storeUrl}/{slug}/p`. If a store ever serves its default locale under a path
+  // prefix or a dedicated domain instead of the root, this href must be derived
+  // from that locale's binding URL instead of `storeUrl`.
+  const defaultEntry = otherLocales.find((e) => e.locale === defaultLocale)
+  if (defaultEntry) {
+    links.push({
+      rel: 'alternate',
+      hrefLang: 'x-default',
+      href: `${baseStoreUrl}/${defaultEntry.slug}/p`,
+    })
+  }
+
+  return links
+}
+
+// With client-side offer enabled, `useOffer` only refreshes price aggregates —
+// it does not rebuild the per-seller array the buy button reads. Keep that array
+// from SSG, but inject the fresh Pricing Fallback token into the best offer so the
+// value sent to the cart respects the token's short validity window.
+const withFreshPriceToken = (
+  serverOffers: ServerProductQueryQuery['product']['offers'],
+  offer: ReturnType<typeof useOffer>
+) => ({
+  ...offer.offers,
+  offers: serverOffers.offers.map((offerItem, index) =>
+    index === 0
+      ? { ...offerItem, priceToken: offer.priceToken ?? offerItem.priceToken }
+      : offerItem
+  ),
+})
+
 function Page({
   data: server,
   sections,
@@ -136,6 +193,12 @@ function Page({
       product.offers.offers[0]?.itemCondition ?? ''
     ]
 
+  // hreflang alternate links for multi-locale stores
+  const hreflangLinks = buildHreflangLinks(
+    storeConfig as StoreConfig,
+    server.product.otherLocales
+  )
+
   let itemListElements = product.breadcrumbList.itemListElement ?? []
   if (itemListElements.length !== 0) {
     itemListElements = itemListElements.map(
@@ -151,7 +214,11 @@ function Page({
     ? (() => {
         const offer = useOffer({ skuId: product.sku })
         return {
-          client: { product: { offers: offer.offers } },
+          client: {
+            product: {
+              offers: withFreshPriceToken(product.offers, offer),
+            },
+          },
           isValidating: offer.isValidating,
         }
       })()
@@ -245,13 +312,11 @@ function Page({
               ]
             : []),
         ]}
+        additionalLinkTags={hreflangLinks}
         titleTemplate={titleTemplate}
       />
 
-      {/* TODO: when localized slugs are available remove this workaround */}
-      {!storeConfig.localization?.enabled && (
-        <BreadcrumbJsonLd itemListElements={itemListElements} />
-      )}
+      <BreadcrumbJsonLd itemListElements={itemListElements} />
 
       <ProductJsonLd
         id={`${meta.canonical}${settings?.seo?.id ?? ''}`}
@@ -283,13 +348,15 @@ function Page({
         If needed, wrap your component in a <Section /> component
         (not the HTML tag) before rendering it here.
       */}
-      <PageProvider context={context}>
-        <RenderSections
-          sections={sections}
-          globalSections={globalSections}
-          components={COMPONENTS}
-        />
-      </PageProvider>
+      <LocalizedProductProvider otherLocales={server.product.otherLocales}>
+        <PageProvider context={context}>
+          <RenderSections
+            sections={sections}
+            globalSections={globalSections}
+            components={COMPONENTS}
+          />
+        </PageProvider>
+      </LocalizedProductProvider>
     </>
   )
 }
@@ -341,6 +408,7 @@ const query = gql(`
           priceValidUntil
           priceCurrency
           itemCondition
+          priceToken
           seller {
             identifier
           }
@@ -351,6 +419,11 @@ const query = gql(`
         productGroupID
       }
 
+      otherLocales {
+        locale
+        slug
+      }
+
       ...ProductDetailsFragment_product
     }
   }

package/src/sdk/account/useReorder.ts

@@ -78,8 +78,9 @@ export const useReorder = () => {
           seller: {
             identifier: item.seller,
           },
-          price: item.price ?? 0,
-          listPrice: item.price ?? 0,
+          price: item.price,
+          listPrice: item.price,
+          priceToken: null,
           itemOffered: {
             sku: item.id ?? '',
             image: item.imageUrl
@@ -111,7 +112,7 @@ export const useReorder = () => {
         orderPayload.orderNumber = currentCart.id
       }
 
-      const { validateCart: validated } = await request<
+      const result = await request<
         ValidateCartMutationMutation,
         ValidateCartMutationMutationVariables
       >(ValidateCartMutation, {
@@ -121,6 +122,8 @@ export const useReorder = () => {
         },
       })
 
+      const validated = result?.validateCart ?? null
+
       if (!validated) {
         throw new ReorderError('Failed to add items to cart')
       }
@@ -132,7 +135,7 @@ export const useReorder = () => {
           id: getItemId(item),
         })),
         messages: validated.messages,
-        shouldSplitItem: validated.order.shouldSplitItem,
+        shouldSplitItem: validated.order.shouldSplitItem ?? undefined,
       }
 
       cartStore.set(updatedCart)

package/src/sdk/cart/index.ts

@@ -18,8 +18,9 @@ import { createValidationStore, useStore } from '../useStore'
 
 export interface CartItem
   extends SDKCartItem,
-    Omit<CartItemFragment, 'isGift'> {
+    Omit<CartItemFragment, 'isGift' | 'priceToken'> {
   isGift?: boolean | null
+  priceToken?: string | null
 }
 
 export interface Cart extends SDKCart<CartItem> {
@@ -58,6 +59,7 @@ export const ValidateCartMutation = gql(`
     listPrice
     listPriceWithTaxes
     isGift
+    priceToken
     itemOffered {
       ...CartProductItem
     }
@@ -128,12 +130,14 @@ const validateCart = async (cart: Cart): Promise<Cart | null> => {
             seller,
             quantity,
             itemOffered,
+            priceToken,
           }): IStoreOffer => {
             return {
               price,
               listPrice,
               seller,
               quantity,
+              priceToken,
               itemOffered: {
                 sku: itemOffered.sku,
                 image: itemOffered.image,

package/src/sdk/localization/LocalizedProductContext.tsx

@@ -0,0 +1,65 @@
+import { createContext, useContext, useMemo } from 'react'
+import type { PropsWithChildren } from 'react'
+
+export interface LocalizedProductLocale {
+  locale: string
+  slug: string
+}
+
+interface LocalizedProductData {
+  /**
+   * Localized slug entries for all available locales of the current page.
+   * Null when localization is disabled or the page type does not support it.
+   */
+  otherLocales: LocalizedProductLocale[] | null
+  /**
+   * Suffix appended after the localized slug when building the redirect URL.
+   * Use '/p' for product pages (PDP), '' for collection/PLP pages.
+   */
+  urlSuffix: string
+}
+
+const LocalizedProductContext = createContext<LocalizedProductData | null>(null)
+
+type LocalizedProductProviderProps = Readonly<
+  PropsWithChildren<{
+    otherLocales: LocalizedProductLocale[] | null | undefined
+    /**
+     * Suffix to append to the localized slug when building the redirect URL.
+     * Defaults to '/p' (product pages). Pass '' for collection/PLP pages.
+     */
+    urlSuffix?: string
+  }>
+>
+
+/**
+ * Provides localized page data (otherLocales, urlSuffix) to any component in
+ * the tree — including global components like LocalizationButton that are
+ * not co-located with page sections.
+ *
+ * Set in p.tsx (PDP) and [...slug].tsx (PLP); returns null outside those pages.
+ */
+export function LocalizedProductProvider({
+  otherLocales,
+  urlSuffix = '/p',
+  children,
+}: LocalizedProductProviderProps) {
+  const value = useMemo(
+    () => ({ otherLocales: otherLocales ?? null, urlSuffix }),
+    [otherLocales, urlSuffix]
+  )
+
+  return (
+    <LocalizedProductContext.Provider value={value}>
+      {children}
+    </LocalizedProductContext.Provider>
+  )
+}
+
+/**
+ * Returns localized product data for the current page.
+ * Safe to call from any component — returns null outside a product page.
+ */
+export function useLocalizedProduct(): LocalizedProductData | null {
+  return useContext(LocalizedProductContext)
+}