Release: 3.21

Buy Now Pay Later, in-page CMS editing, and marketplace checkout

Front-Commerce 3.21 introduces a brand new Pledg extension that powers Buy Now Pay Later simulations on the product page through a new paymentPlans GraphQL field. Editorial teams gain a new in-page Page Editor with a full Media Manager and Media Picker, wired to Gezy's media API out of the box. The Gezy Marketplace adds multi-shipment checkout and a fully configurable Quick Order page that any catalog can plug into.

Front-Commerce 3.21 drops Node.js 20 support, which reached end-of-life on March 24, 2026. Make sure your environments run Node.js 22.22.0 or higher (or Node.js 24.14.0 or higher).

Let's dive into the details!

Pledg: Buy Now Pay Later on the product page

Front-Commerce 3.21 ships with a new @front-commerce/pledg extension that displays Buy Now Pay Later payment plan simulations directly on the product page. Customers can preview installment (3x, 4x, …) and deferred schedules before they add the product to their cart, with a "Learn more" modal detailing every payment date and amount.

• New paymentPlans GraphQL field: Front-Commerce core now exposes a generic Product.paymentPlans field that aggregates plans from every registered simulator. @front-commerce/pledg is the first built-in simulator and is wired with Gezy, Magento 1 and Magento 2.
• PaymentPlansBanners theme component: Theme Chocolatine ships a new component that renders the available plans, with a learn-more modal displaying the full schedule.
• Price bounds awareness: when a product price falls outside a payment method's configured min/max range, the simulator displays a dedicated label and disables the "Learn more" CTA.
• Pluggable simulators: third-party extensions can register their own BNPL providers through the new simulator registration API.

Learn more in the Pledg extension documentation and in the Implement a custom payment plan simulator guide.

CMS: in-page Page Editor

Contributors with contribution mode enabled get a new Page Editor switch in the editorial toolbox. Toggling it opens an editor overlay on top of the live page, so editorial teams can compose and refine content without leaving the storefront, with a live preview that updates as they type.

• Add and reorder sections: a top-bar "Add section" button opens a section selection modal, sections can be dragged into the desired order, and a sidebar form (auto-generated from each section's schema) lets contributors edit content fields and layout config side by side with the preview.
• Section styling controls: each section now exposes a base config editor for layout properties — including a background image picker (with opacity slider) and background color, picked from the media library.
• Undo / redo and unsaved-changes guard: the editor keeps a full history of edits, the top bar surfaces undo/redo controls, and an indicator warns contributors when navigating away with unpublished changes.
• Atomic publish: a single "Publish" action persists every section (props, config, ordering) and the page metadata (SEO title and description) in one transaction, with success/error feedback inline in the top bar.

CMS: Media Manager and Media Picker

The CMS now ships with a full Media Manager and a reusable Media Picker that any section or field can plug into to let contributors choose images from a shared media library.

• Media Manager: a full-screen dialog that lets contributors browse the media library as a tree (folders and files in a grid), navigate through breadcrumbs, create sub-folders, upload one or many files to the current folder, rename files and folders inline, and delete them (folder deletion is recursive, with a confirmation dialog).
• Tree-wide search: a search input filters the entire media tree by file name in real time, with dedicated empty states for empty folders and "no results" searches.
• Media Picker: a MediaInput form field renders a clickable preview that opens the Media Manager in picker mode. Contributors select a file from the grid and confirm — images render as thumbnails, non-image files (PDFs and others) display a generic document icon, and a clear button drops the current selection. Image, PDF and arbitrary file types are supported.
• Optimized delivery: images embedded on the storefront are automatically resized and cached, so media-rich pages stay fast.
• Pluggable backend: the Media Manager is driven by a MediaBackend contract, so platform packages can wire it to their own media API.

CMS: Gezy media backend

@front-commerce/gezy now ships a GezyMediaBackend implementation that wires the CMS Media Manager to Gezy's v4 CMS media API. Folders, files, uploads, renames, deletes and tree-wide search all hit Gezy directly, so images uploaded from the in-page editor are persisted on the platform.

Gezy Marketplace: multi-shipment checkout and Quick Order

Marketplace orders frequently span multiple merchants, each with their own shipping options. Front-Commerce 3.21 introduces a full multi-shipment checkout capability and brings a configurable Quick Order page to marketplace shops.

• Multi-shipment checkout: an alternative checkout flow, with streamlined steps, lets customers ship a single order to several addresses and pick a delivery method for each merchant group.
• Cart merchant display: each marketplace cart line now shows the merchant name and a link to the merchant page.
• Quick Order for marketplace shops: the Quick Order page now lets marketplace customers bulk-add offers from a CSV file. An offer selection modal opens when a row needs configuration, either at pick time or via a "Configure" button.
• CSV order downloads: order CSV exports now include each line's offer_id for marketplace orders.

Quick Order: faster bulk ordering

The Quick Order page lets your customers fill their cart in one go, by uploading a CSV file or filling rows manually. It is ideal for B2B buyers placing large or recurring orders.

In 3.21 the page adapts to your catalog: it now supports marketplace offers (with an offer-selection step when a product needs configuration), custom CSV columns, and project-specific submission rules. Existing projects keep their current behavior, with no change required.

If you have customized the Quick Order page, review the breaking changes in the 3.20 to 3.21 migration guide.

Learn more in the Quick orders guide.

Other changes

Features

• Adyen:
  • We added support for the Adyen Magento 2 plugin v9.x and v10.x. The paymentDetails and payment-status REST endpoints have been refactored to align with the new URLs and payload structures introduced in v9
• Core:
  • We introduced a single convention for admin GraphQL endpoints and Remix routes (Query.admin.<domain>..., admin<Domain>... mutations, api.admin.<domain>... routes) with automatic contribution-mode protection and domain-derived permission enforcement; the admin* mutation prefix is now reserved for admin-only operations
  • We added a blockLevel option to registerNodeType to render a <p> as a <div> when it wraps a block-level node, preventing hydration mismatches on CMS content
  • We exposed a typed metadata channel for Content Composition entries so React components and non-React contexts (loaders, utilities) can read sibling <ComponentName>.CompositionMetadata.ts files
  • We added a findIdentity helper on UserJourney so downstream packages can look up identities by service name without accessing the encapsulated identities field
• Gezy:
  • We obtained an OAuth v4 token during customer authentication, enabling API v4 calls for authenticated customers
  • We migrated the Gezy health check to the API v4 /health endpoint, with a fallback to the legacy check when v4 is not available
• Magento2:
  • We added a blockLevel option to registerWidgetType so custom widgets rendering block-level content can sit safely inside a CMS paragraph; see the WYSIWYG platform guide
• Storybook (new):
  • We added a new @front-commerce/storybook package providing a Storybook preset to mock useApiFetcher calls in stories via MSW through parameters.msw.handlers; the 3.21.0 codemod patches your Storybook config automatically (see the migration guide)
• Theme Chocolatine:
  • We added a "Download CSV" action on the order detail page

Improvements

• Core:
  • Lifecycle hooks (onServerServicesInit, afterServerServicesInit) now receive an optional context argument exposing the Remix serverBuild, letting packages validate route registrations at startup
• Magento1:
  • We exposed Shipment.items and TrackingDetails.items (they were previously returning empty arrays)
• Remix:
  • We pre-bundle the entire React family in a single optimizeDeps pass in dev mode, fixing intermittent useContext crashes on HMR
• Theme Chocolatine:
  • We restored the "Shipping method" label inside each shipment block on the order details page

Bug Fixes

• Core:
  • We fixed an issue where a granted negotiableQuote permission with no matching /user/negotiable-quotes route registered by the backend module would leave a dead link in the account navigation
• Gezy:
  • We made the lang parameter optional in createApiClient so technical callers without a request-bound language type-check correctly
  • We fixed an issue where CustomerLoader debug logs would access error.response.data on an unknown error value instead of using axios.isAxiosError
  • We fixed missing response type imports in CustomerLoader (GetClientInfoResponse, GezyStatusResponse, GezyUpdatePasswordResponse) and fixed the AressesInfosResponse typo
  • We fixed an issue where PasswordComplexityError would be instantiated without the required GezyError code in CustomerLoader and the error translator
• Magento1:
  • We fixed an issue on multistore setups where customers signing up through Social Login would have their account wrongly attached to the Admin store view instead of the store they registered from
  • We fixed Social Login on multistore setups by forwarding the scopeKey and the guest cart token to the Magento admin-login endpoint, so Magento can resolve the right customer per website and merge the guest cart on Google/Facebook login
  • We fixed an [object Object] server error on the order detail page for virtual product orders (no shipping address) by guarding formatAddresses and formatShipments, routing virtual items to Order.virtualShipments, and fixing the order detail error boundary
• Remix:
  • We fixed an issue where dynamic routes would not render their CSS at SSR for stores served under a path prefix, and would crash on hot reload
  • We fixed useApiFetcher to keep loading true during SWR revalidations, so consumers like useCart() and useMiniCart() no longer flash stale data
• Theme Chocolatine:
  • We fixed an issue where the default marketplace offer was never selected on single-offer products, causing AddToCart to fall back to the non-marketplace flow and corrupt the marketplace cart
  • We fixed a memory leak in useDelayedIsOpen where the opening setTimeout was never stored and never cleaned up, which could trigger a state update on an unmounted component
  • We hardened the Link atom to reject unsafe URL protocols (javascript:, data:, vbscript:, file:, and any scheme that is not http:/https:/mailto:/tel: or a relative path); unsafe values are substituted with "#" at render time
  • We fixed an issue where the BottomBar component and its story were not correctly exported
• Twicpics:
  • We fixed an issue where the size prop was ignored on non-full-width images

Dependencies updates

Core / Runtime packages:

Package	From	To
@contentful/rich-text-types	17.2.5	17.2.7
@formatjs/cli-lib	8.5.0	8.5.5
async-ratelimiter	1.6.5	1.6.6
contentful	11.12.0	11.12.3
dotenv	17.4.1	17.4.2
express	4.22.1	4.22.2
isbot	5.1.37	5.1.40
lru-cache	11.2.6	11.3.6
react-cookie	8.1.0	8.1.2
ua-parser-js	2.0.9	2.0.10
universal-cookie	8.1.0	8.1.2
uuid	13.0.0	13.0.2

GraphQL:

Package	From	To
graphql	16.13.1	16.13.2
@graphql-codegen/fragment-matcher	6.0.0	6.0.1
@graphql-codegen/schema-ast	5.0.1	5.0.2
@graphql-codegen/typescript	5.0.9	5.0.10
@graphql-tools/merge	9.1.7	9.1.9
@graphql-tools/schema	10.0.31	10.0.33
@graphql-tools/utils	11.0.0	11.0.1
vite-plugin-graphql-codegen	3.9.0	3.9.1

React family:

Package	From	To
react	19.2.4	19.2.6
react-dom	19.2.4	19.2.6
@types/react	19.2.14	19.2.15

Payment Providers:

Package	From	To
@adyen/adyen-web	6.32.0	6.32.1

Search:

Package	From	To
algoliasearch	5.50.1	5.50.2

Workbox:

Package	From	To
workbox-precaching	7.4.0	7.4.1
workbox-recipes	7.4.0	7.4.1
workbox-routing	7.4.0	7.4.1
workbox-strategies	7.4.0	7.4.1
workbox-window	7.4.0	7.4.1

Build Tools:

Package	From	To
@types/node	22.19.17	22.19.19
fs-extra	11.3.4	11.3.5
happy-dom	20.8.3	20.8.9
memfs	4.57.1	4.57.3
p-queue	9.1.1	9.1.2
parse5	8.0.0	8.0.1
postcss	8.5.8	8.5.15
postcss-url	10.1.3	10.1.4
qs	6.15.0	6.15.2
rollup	4.60.1	4.60.4
terser	5.46.1	5.46.2

Dev Tools / Linting:

Package	From	To
@eslint/markdown	8.0.1	8.0.2
eslint	10.2.0	10.2.1
prettier	3.8.1	3.8.3
typescript-eslint	8.58.0	8.58.1

Storybook:

Package	From	To
storybook	10.3.4	10.3.6
@storybook/addon-docs	10.3.4	10.3.6
@storybook/addon-links	10.3.4	10.3.6
@storybook/addon-onboarding	10.3.4	10.3.6
@storybook/builder-vite	10.3.4	10.3.6
@storybook/react-vite	10.3.4	10.3.6
@chromatic-com/storybook	5.1.1	5.1.2
eslint-plugin-storybook	10.3.4	10.3.6

---

Fixes from 3.21 have also been backported into previous minor versions. The following patch versions were released: 3.20.2, 3.19.2, 3.18.5, 3.17.4, 3.16.5, 3.15.6, and 3.14.7.

---

Upgrade Front-Commerce (Migration guides): 3.21.0
Read the full changelog (Customers only): 3.21.0.