# Migrating from PageBuilder Engine 6.x to 7.x

Source: https://dev.arcxp.com/pagebuilder-engine/how-to-guides/migration-guides/migrating-from-pagebuilder-engine-6x-to-7x/

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.92.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

- You need to use new PageBuilder CLI 3.2 or later, when using Engine 7.x. See [PageBuilder CLI release notes](https://docs.arcxp.com/en/what-s-new-in-arc-xp/what-s-new-in-pagebuilder.html#UUID-3af02ef3-4d50-4cc5-0e90-35e35dcd362c%5Fsection-idm235067410768218).
- When upgrading to new CLI version, a local data reset is required. See [Local Data Migration or Fresh Restore](#local-data-migration-or-fresh-restore) section of this document for more details.

## 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](https://dev.arcxp.com/pagebuilder-engine/developer-docs/migrating-from-pagebuilder-engine-5x-to-6x/).

### 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.

### PropTypes and Custom Fields

React 19 removed `prop-types` from the React package itself, but **this does not affect your bundle code**. PropTypes are **not** deprecated. They are simply no longer bundled with React core.

PageBuilder Engine has always provided its own PropTypes implementation and externalizes all common import forms at build time. Whether your components import from `'prop-types'`, `'fusion:prop-types'`, or `'@arc-fusion/prop-types'`, Engine resolves them all to the same built-in implementation. No changes are required in your bundle code.

## 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](https://dev.arcxp.com/pagebuilder-engine/developer-docs/smoke-testing-bundle-code/)) and type checks after updating tsconfig for TypeScript 5.x.

For generalized strategy, see [Major / breaking upgrade guidance](https://dev.arcxp.com/pagebuilder-engine/developer-docs/upgrading-your-bundle-code-with-major-or-breaking-pagebuilder-engine-releases/).

## 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.92.1**

- Rebuild CSS; spot‑check pages with math/function mixes.

**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.

> **Note:**
> 
> Engine 7.x upgrades these dependencies, and Arc XP’s managed Themes blocks are updated to be compatible in Themes 4.x. That does not extend to custom blocks or any Themes blocks your team has forked. Your team should audit those against the new versions and update as needed.

### Local Data Migration or Fresh Restore

> **Note:**
> 
> This only affects for local PageBuilder data. Arc XP environments are not impacted.

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](https://dev.arcxp.com/pagebuilder-engine/developer-docs/how-to-run-pagebuilder-engine-locally-starting-with-my-organizations-live-bundle-and-pages#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](https://dev.arcxp.com/pagebuilder-engine/developer-docs/migrating-from-pagebuilder-engine-4x-to-5x/) 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

Themes 4 is fully compatible with Engine 7.x. Customers using Arc’s out-of-the-box Themes blocks or Outbound Feeds can upgrade to Engine 7.x by following the [Themes 4 upgrade guide](https://dev.arcxp.com/themes/migration-guides/upgrade-to-themes-4/).

For additional information about the Themes 4 release, see the [Themes 4 release notes](https://docs.arcxp.com/en/what-s-new-in-arc-xp/what-s-new-in-themes.html#UUID-603b7cfb-b675-5693-4330-637eeefc99d9%5Fsection-id235309558913989%5Fbody).

## Bundle size and Lambda packaging

Some bundles that ran fine on Engine 6 fail to deploy on Engine 7 with Lambda size errors, even with no application code changes. The cause is almost always packaging.

Engine 7 ships with updated dependencies that take up more space in the Lambda artifact. If your bundle was already near the 250 MB unzipped limit, that extra headroom disappears.

Before upgrading, check two things:

- **Dependencies mis-classified as runtime:** packages in `dependencies` instead of `devDependencies` inflate the Lambda footprint. The full transitive tree gets installed. Easy to miss when the same repo serves multiple platforms.
- **Non-runtime files in the bundle zip:** test coverage reports, CI artifacts, and docs folders add size with no benefit at runtime.

See [Optimizing unzipped Lambda size](https://dev.arcxp.com/pagebuilder-engine/developer-docs/optimizing-unzipped-lambda-size-with-pre-building-large-dependencies/) for a step-by-step checklist and the pre-build technique for larger dependencies.

## Past Versions Migration Guides

- [Migrating from PageBuilder Engine 5.x to 6.x](https://dev.arcxp.com/pagebuilder-engine/developer-docs/migrating-from-pagebuilder-engine-5x-to-6x/)
- [Migrating from PageBuilder Engine 4.x to 5.x](https://dev.arcxp.com/pagebuilder-engine/developer-docs/migrating-from-pagebuilder-engine-4x-to-5x/)
- [Migrating from PageBuilder Engine 3.x to 4.x](https://dev.arcxp.com/pagebuilder-engine/developer-docs/migrating-from-pagebuilder-engine-3x-to-4x/)