This guide provides detailed information about the migration process and necessary changes for Custom Applications and Custom Views to ensure a successful migration.

Preparation

Before starting, we recommend that you understand the key changes introduced in the relevant React major versions.

You can find detailed information in the official upgrade guides:

• React 18 upgrade guide
• React 19 upgrade guide

Dependencies

We updated the following dependencies (besides React) to a major version:

• react-intl: v7.1.4
• @emotion/react: v11.14.0
• downshift: v8.5.0
• @testing-library/react: v16.1.0
• @testing-library/dom: v10.4.0

We replaced the following third-party libraries because they don't support newer versions of React:

• react-beautiful-dnd was replaced with @hello-pangea/dnd
• react-sortable-hoc was replaced with @hello-pangea/dnd

Testing

Given the update of both react and react-testing-library dependencies, we had to refactor several patterns in our tests.

This utility can be referenced in two ways:

1. From the @testing-library/react package
2. From the @commercetools-frontend/application-shell/test-utils package
   • We should use this one only if our hook depends on the application context or other information stored in any provider of the application shell

In some tests where we were expecting a hook to throw an error, we also had to refactor the expectation like this (it depends on how the error is managed in the hook):

// BEFORE
const { result } = renderHook();
expect(result.error).toEqual(Error('Expected error message'));

// AFTER
expect(() => renderHook()).toThrow(
  'Expected error message'
);

// BEFORE
input.click();

// AFTER
fireEvent.click(input);

For example:

// BEFORE
await jest.runAllTimersAsync()

// AFTER
await act(async () => await jest.runAllTimersAsync());

// BEFORE
it.only('should render 35% after ten seconds', async () => {
  const { getByText } = renderApp(
    <ProjectCreateProgressBar dataset={sampleDatasets.B2B} />
  );
  act(() => {
    jest.advanceTimersByTime(10000);
  });
  expect(getByText(/35%/i)).toBeInTheDocument();
});

// AFTER
it.only('should render 35% after ten seconds', async () => {
  const { getByText } = renderApp(
    <ProjectCreateProgressBar dataset={sampleDatasets.B2B} />
  );
  await act(async () => jest.advanceTimersByTimeAsync(3000));
  await act(async () => jest.advanceTimersByTimeAsync(3000));
  await act(async () => jest.advanceTimersByTimeAsync(3000));
  expect(getByText(/35%/i)).toBeInTheDocument();
});

General code adjustments

We found some issues passing the whole props object to a child in a component due to the key prop, so it's better to destructure that property before passing the props to the child.

This is the warning we saw in the logs:

Warning: A props object containing a "key" prop is being spread into JSX

and here is how we refactored our code:

// Before
<LocalBreadcrumbNode {...props} />

// After
const { key, ...restProps } = props;
<LocalBreadcrumbNode key={key} {...restProps} />

Also, we found some places where we were wrapping a single component with a React.Fragment and now that yields a warning as well:

// BEFORE
const MyComponent = () => (
  <>
    <h1>My title</h1>
  </>
);

// AFTER
const MyComponent = () => (
  <h1>My title</h1>
);

TypeScript type changes

React 19 is stricter with TypeScript types, so we had to adjust some things:

// BEFORE
type TButtonProps = {
  text: string;
  icon: ReactElement;
};

// AFTER
type TButtonProps = {
  text: string;
  icon: ReactElement<TIconProps>;
};

// BEFORE
const myRef = useRef<string>();

// AFTER
const myRef = useRef<string>(undefined);

// BEFORE
const myReducer = useReducer<TReducerParams>();

// AFTER
const myReducer = useReducer();

React-intl updates

A combination of the new react-intl major version we're using and the stricter TS types validation from React 19 pushed us to change the way we provided parameters to i18n messages when the value of the parameters were JSX elements.

In this case, we need to provide a key property to the element provided as a parameter:

// BEFORE
<FormattedMessage
  {...messages.myMessage}
  values={{
    name: (
      <Text.Body as="span">{user.name}</Text.Body>
    )
  }}
/>

// AFTER
<FormattedMessage
  {...messages.myMessage}
  values={{
    name: (
      <Text.Body key="username" as="span">{user.name}</Text.Body>
    )
  }}
/>

React-transition-group updates

const nodeRef = useRef();

<CSSTransition nodeRef={nodeRef}>
  <div ref={nodeRef}>
  </div>
</CSSTransition>

Formik updates

We use the Formik library in our applications to manage HTML forms, and we found issues in certain scenarios where we were expecting some form state updates to have been consolidated, but they weren't.

Formik holds an internal state in a reducer and tries to trigger React re-renders (by another internal useState state) whenever something changes. The main issue is that React 18 introduced batched state updates. This caused some internal form changes to not be synced with the React state, so the code that was waiting for the new state found the old one.

We found a workaround by forcing a React state synchronization programmatically:

// BEFORE
const handleFormSubmit = (values, formikBag) => {
  saveValues(values);
  formikBag.resetForm();
  validateCleanForm(); // <--- This was not finding the form reset
};

// AFTER
const handleFormSubmit = (values, formikBag) => {
  saveValues(values);
  React.flushSync(() => formikBag.resetForm());
  validateCleanForm(); // <--- Now the form is reset here
};

Custom Views

To turn off Strict Mode, update your Custom View entry point component:

// BEFORE
<CustomViewShell enableReactStrictMode applicationMessages={loadMessages}>
  <AsyncApplicationRoutes />
</CustomViewShell>

// AFTER
<CustomViewShell applicationMessages={loadMessages}>
  <AsyncApplicationRoutes />
</CustomViewShell>