Skip to content
Arc XP

Migrating from PageBuilder Engine 6.x to 7.x

PageBuilder Engine 7.x introduces major platform dependency upgrades to keep PageBuilder on supported and modern development stack. While most Arc XP public interfaces remain stable, you must plan and test for the new Node.js 22 runtime and the React 19 upgrade alongside dependency library changes outlined below.

Key changes requiring customer code validation:

  • Node.js 22 upgrade – Test your bundle on Node 22; rebuild native deps.
  • React 19 upgrade – Update React + related libs; run type checks and core UI smoke tests.
  • MongoDB (Driver) 4 → 6 – Plan data export/import or clean restore; datastore driver updated under the hood.
  • GraphQL.js 14 → 16 – Switch to new import/execute patterns; stricter validation may surface new errors.
  • TypeScript 4.9.4 → 5.8.x – Update tsconfig & tooling; decorators and module resolution rules changed.
  • Sass 1.80.6 → 1.85.1 – Minor fixes; rebuild CSS and spot‑check key pages.

Run a quick build/run smoke test even if you only use Arc XP’s APIs; indirect dependency updates may still introduce new errors or build/runtime changes.

Requirements

Runtime & Core Platform Changes

Node.js 22 Support

Engine 7.x adds support for running bundles on Node.js 22. Plan to validate and migrate to Node 22 as older LTS version (Engine 6 will be deprecated in summer 2026).

Key considerations moving from Node 20 → 22 that are not directly used in PageBuilder but may affect your npm dependencies or custom bundle code:

  • New JS v8 engine: a bit faster and stricter; quirky code that worked before might now error.
  • Some old or deprecated Node features may be removed or act differently—check if you used outdated fs, http, timers, URL, or crypto code.
  • Reinstall any packages with native components so they rebuild for Node 22.
  • If you rely on experimental flags or permissions, verify they still behave the same.

If you skipped Engine 6.x, first complete that migration (Node 18 → 20) before adopting Node 22. See Engine 5.x → 6.x guide.

React 19 Upgrade

Engine 7.x upgrades the React runtime from 18 to React 19.

Potential impacts in your code base:

  • Stricter TypeScript types: run a full type check after upgrading React and its type packages.
  • Suspense & streaming may render slightly differently: test hydration boundaries.
  • Third‑party UI libs (components, state, router): confirm React 19 support before upgrading.
  • Legacy APIs (old context, UNSAFE_ lifecycles): remove them—React 19 warns or may break.
  • Strict Mode dev mounts: re-check components with side‑effects that assume single mount.

If you provide reusable components or content sources (i.e: as private npm packages), publish a prerelease of your components on React 19.

Upgrading your code and dependencies

Perform a targeted audit rather than blanket upgrades:

  1. Run npm outdated to surface additional indirect version gaps.
  2. Prioritize HIGH and MEDIUM impact items summarized below.
  3. Execute smoke tests (bundle smoke testing) and type checks after updating tsconfig for TypeScript 5.x.

For generalized strategy, see Major / breaking upgrade guidance.

Other PageBuilder Engine Dependency Upgrades

These library upgrades ship with Engine 7.x. If your bundle (or custom Themes/OBF code) does not import them directly, you likely only need to run smoke tests; still skim for awareness because stricter validation or type changes can surface indirectly. Each item lists the minimal actions (update pattern) plus what to re‑test.

GraphQL.js 14 → 16

  • Use named imports only; update execute / subscribe to object form.
  • resolveType must return the type name (string); remove deprecated APIs.
  • Rerun tests—stricter validation may surface new errors (limit 100).

TypeScript 4.9.4 → 5.8.x

  • Update tsconfig (module & moduleResolution, standard decorators) and tooling.
  • Enable a clean type check; fix new lib / decorator / enum diagnostics.
  • Consider verbatimModuleSyntax; remove unused or side‑effect only imports.

Sass 1.80.6 → 1.85.1

  • Rebuild CSS; spot‑check pages with math/function mixes.
  • No expected breaking changes—treat as regression test only.

MongoDB Data Store (Driver 4 → 6)

  • Platform driver updated: defaults (writeConcern=majority, readConcern=local) & stricter options.
  • Prepare a dated export; be ready for export/import or clean pb‑data restore.
  • See the “Local Data Migration or Fresh Restore” section below for the detailed workflow.

Local Data Migration or Fresh Restore

A core dependency that stores your PageBuilder data (pages, templates, assets, config) locally is the MongoDB. Engine 7.x upgrades MongoDB from version 4 to version 6, which includes some breaking changes and new defaults. This change requires data to be refreshed via either:

a. Retain local pb-data with doing Export / Import

  1. Before upgrading to Engine 7, run npx fusion dump to export your local pb-data to a dated archive in the /data/dumps/<timestamp>.tar.gz folder.
  2. Update your .env file to set new Engine version FUSION_RELEASE=7
  3. Place the data file in your project under the /data/restore folder.
  4. Delete /data/db folder (to clean up current/old MongoDB data).
  5. npx fusion start will automatically restore the data on first run.

b. Fresh pb-data restore from Arc XP environment

  1. Download PB Data from the Arc XP Admin
  2. Place the data file in your project under the /data/restore folder.
  3. npx fusion start will automatically restore the data on first run.

Upgrading from earlier Engine versions (3.x, 4.x, 5.x → 7.x)

If you are on Engine 5.x or earlier, upgrade sequentially to reduce surface area of concurrent changes.

For example, if you are on Engine 4.x, your upgrade path would be:

  1. Engine 5.x (Node 18) → follow existing 4.x → 5.x migration guidance.
  2. Engine 6.x (Node 20 introduction) – complete Node 20 validation.
  3. Engine 7.x – apply dependency updates outlined in this document.

Jumping directly from Engine 3.x/4.x/5.x to 7.x compounds runtime (Node 16 → 20) plus dependency changes, making root cause analysis harder.

Themes and Outbound Feeds (OBF) bundles

A compatible Themes and OBF bundles will be released soon. Customers using Themes or OBF blocks must remain on Engine 6.x.

Past Versions Migration Guides