Docs Developer Site
Developer Docs React4XP 7.x Legacy mode upgrade

Legacy mode upgrade

Contents

React4XP 7 is still compatible with how parts are rendered in version 5, where each part is a separate entry rendered by its own controller, outside the componentRegistry.

This means you may upgrade a legacy React4XP application to version 7 without adopting the component registry. The render() function and the rendering it does are unchanged from version 6.

Legacy mode covers parts only. Pages and layouts depend on the componentRegistry, and must be migrated as described in the 6.x documentation’s recommended upgrade before or during the move to version 7.

Step by step

  1. Do the standard XP 7 to XP 8 upgrade of the application.

  2. Apply the React4XP specifics: dependencies, the react4xp API, build tooling and types.

  3. Apply the legacy mode specifics below.

Part controllers

Keep your version 5 style controllers. As part of the standard XP 8 upgrade they move from site/ to cms/, and as in version 6, Enonic.Xp.Http.Request from @enonic/js-utils/types/Request is replaced with Request from @enonic-types/core:

src/main/resources/cms/parts/example/example.ts
import {render} from '/lib/enonic/react4xp';
import {getComponent} from '/lib/xp/portal';
import type {Request} from '@enonic-types/core';


export function get(request: Request) {
    const component = getComponent();
    const props = {};

    return render(component, props, request);
}

Entries

The entries do not move along with the controllers. When render() is given a component object, it derives the entry name from the component descriptor as site/parts/<name>/<name>, and React4XP still compiles entries found below src/main/resources/site/. XP 8 itself ignores that folder, so keep it for the legacy entries only:

src/main/resources/
├── cms/
│   └── parts/
│       └── example/
│           ├── example.ts        (1)
│           └── example.yaml
└── site/
    └── parts/
        └── example/
            └── example.tsx       (2)
1 The controller, moved to cms/ by the standard upgrade.
2 The entry, left in site/ so its jsxPath stays site/parts/example/example.

Alternatively, move the entry to one of the entryDirs configured in react4xp.config.js and pass its jsxPath to render() explicitly, for example render('example', props, request) for react4xp/entries/example.tsx.

Site descriptor

Legacy parts are rendered by XP’s regular component pipeline, so requests to them must not be caught by the React4XP site mapping. The inverted pattern that excluded them in site.xml is written as invertPattern: true in site.yaml, and the react4xp API must be mounted:

src/main/resources/cms/site.yaml
kind: "Site"
mappings:
  - controller: "/cms/app.js"
    order: 10
    pattern: "/r4xp5.*"       (1)
    invertPattern: true
  - controller: "/cms/component.js"
    service: "component"
    order: 10
apis:
  - "asset"
  - "react4xp"                (2)
1 Content rendered with legacy parts must live under a path matching this pattern - adjust it to fit your site.
2 Required on XP 8, also for legacy parts - render() resolves its asset URLs through this API.
If the application has no componentRegistry at all, drop the mappings section and keep only apis.

Removed APIs

Compiled assets are now served by the react4xp API instead of the react4xp XP service. render() handles this by itself, so the only requirement is to mount the API as shown above.

Two things are gone without a direct replacement:

  • The react4xp-dependencies XP service, which returned the dependency URLs of a set of entries over HTTP. Server-side, getComponentChunkUrls from /lib/enonic/react4xp still provides the same information.

  • serviceUrl from /lib/enonic/react4xp. Use assetUrl to build URLs to compiled assets.

Build and deploy

Build and deploy as described in the upgrade notes.

Contents

Contents