Skip to content
Arc XP

Upgrade to Themes v4

Themes 4 is scheduled for release December 16, 2025. Dates are subject to change.

This guide explains how to upgrade to Themes 4 if you’re using Arc’s out-of-the-box Themes blocks, along with notes for customers who maintain custom or forked blocks Themes 4 is fully compatible with Engine 7, leveraging Node 22 and React 19, and ensures that all supported Themes blocks — including Outbound Feeds and Subscriptions — continue to run on secure, up-to-date runtimes.

Upgrading to Themes 4 is required before the June 1, 2026 deprecation of Themes 3 and Engine 6, which are tied to the AWS Lambda Node.js 20 runtime. Moving to Themes 4 ensures you remain on a supported platform, gain access to the latest performance and security improvements, and are prepared for ongoing enhancements across the Arc XP ecosystem.

Quick Summary

✔ Update themesReleaseVersion

✔ Set FUSION_RELEASE=7

✔ Use Node 22

✔ Ensure custom blocks are React 19 compatible

Steps to Upgrade

Upgrading really isn’t difficult — it only takes a few quick updates to your configuration, and we’ll walk you through each one. However — you’ll still need to ensure that any custom blocks or components in your bundle are compatible with PageBuilder Engine 7.x.x.

  1. Update your blocks.json Set your Themes release version to V4: "themesReleaseVersion": "arc-themes-release-version-4.0.0"

  2. Confirm your Engine release version In your .env, make sure you’re running Engine 7: FUSION_RELEASE=7.0.0

  3. Use Node 22 Themes V4 and Engine 7 require Node 22. We strongly recommend updating your .nvmrc so PageBuilder always runs using the correct version: 22

At this point, Themes V4 will run locally.

However — you’ll still need to ensure that any custom blocks or components in your bundle are compatible with PageBuilder Engine 7.x.x.

Full migration guide: Migrating from PageBuilder Engine 6.x to 7.x

Key Migration Tips

When upgrading from Engine 6 → 7, most required changes relate to React 19 compatibility. Below are the updates we see most commonly needed when upgrading custom code:

Modernize React usage

  • Convert class components to function components
  • Remove legacy lifecycle methods (componentWillMount, UNSAFE_*)
  • Replace Component.defaultProps with default function parameters
  • Stop using findDOMNode and instead rely on refs
  • Move from legacy context API → createContext() / useContext()

Check dependency compatibility

All dependencies must support React 19 and Node 22.

If you see an error like this:

TypeError: Cannot read properties of undefined (reading 'ReactCurrentDispatcher')

…it usually means a dependency is installing a different React version (often via a peer dependency), which will break your bundle during local development.

After these updates, you’re fully set to run Themes 4.

Customers with Custom Blocks

For customers with custom blocks, here are the key learnings we recommend keeping in mind. These come directly from issues we encountered during our own upgrade work and can help you avoid common pitfalls:

  • Dependency issues were the most frequent source of breakage, especially when packages pulled in older React versions or incompatible peer dependencies.
  • Several patterns deprecated in React 19 caused failures, including legacy lifecycle methods and the removal of defaultProps on function components.
  • Syntax and API changes in React 19 required updates in places where older patterns were still in use.
  • npm package updates triggered cascading issues, particularly when packages had not yet adopted React 19 or Node 22.
  • Google reCAPTCHA v2 was incompatible with Node 20+, which caused unexpected downstream failures until replaced.
  • Testing suites surfaced mismatches between server and client output, making it important to verify SSR and hydration behavior under React 19.
  • Common errors to watch for include missing peer dependencies, React version mismatches, and undefined dispatcher errors, which usually signal that a dependency is bundling its own React version.