v4 code migration: Updating strapi global variable calls

This guide is part of the v4 code migration guide designed to help you migrate the code of a Strapi application from v3.6.x to v4.0.x

🤓 v3/v4 comparison

In Strapi v3, a window.strapi global variable is used to display notifications, freeze user interactions when requests are pending, and get the backend URL.

In Strapi v4, strapi.notification, strapi.lockApp and strapi.unlockApp are not supported anymore and replaced by specific React hooks. Calls to strapi.backendUrl are still supported.

To migrate to Strapi v4:

1. Remove all calls to strapi.notification, strapi.lockApp and strapi.unlockApp from the code.

2. Adapt your code, using the following table to find Strapi v4 hooks equivalent to Strapi v3 features. All hooks are provided by the @strapi/helper-plugin module:

   Feature in v3	Equivalent feature in v4
   strapi.notification calls	useNotification hook
   strapi.lockApp calls	lockApp method from the useOverlayBlocker hook
   strapi.unlockApp calls	unlockApp method from the useOverlayBlocker hook
   strapi.backendUrl calls	strapi.backendUrl calls (still exist in Strapi v4)

The following examples should help you get started using the useNotification hook and lockApp/unlockApp methods:

Example of using the useNotification hook in Strapi v4:

./src/plugins/<my-plugin>/admin/*.js

import { useNotification } from '@strapi/helper-plugin';
import { Button, Main } from '@strapi/design-system';

const HomePage = () => {
  const toggleNotification = useNotification();

  const handleClick = () => {
    toggleNotification({
        // required
        type: 'info|success|warning', // choose one from the list
        // required
        message: { id: 'notification.version.update.message', defaultMessage: 'A new version is available' },
        // optional
        link: {
          url: 'https://github.com/strapi/strapi/releases/tag/v4',
          label: {
            id: 'notification.version.update.link',
            defaultMessage: 'See more'
          },
        },
        // optional, default = false
        blockTransition: true,
        // optional
        onClose: () => localStorage.setItem('STRAPI_UPDATE_NOTIF', true),
      });
  }

  return (
    <Main>
      <h1>This is the homepage</h1>
      <Button onClick={handleClick}>Display notification</Button>
    </Main>
  );
};

Example of using the lockApp and unlockApp methods in Strapi v4:

./src/plugins/<my-plugin>/admin/*.js

import { useOverlayBlocker } from '@strapi/helper-plugin';

const MyCompo = () => {
const { lockApp, unlockApp } = useOverlayBlocker();

 return null
}

Example of logging the backend URL value in Strapi v4:

./src/plugins/<my-plugin>/*.js

const myHelper = () => {
  console.log(strapi.backendURL); // http://localhost:1337
};

Using the @strapi/helper-plugin Storybook

The @strapi/helper-plugin module provided with Strapi v4 features a Storybook instance. The Storybook instance can be run to display further documentation about the internal components specifically targeted for the Strapi admin panel. This includes information about the useNotification hook. To access the documentation included with @strapi/helper-plugin:

1. Clone the Strapi repository:

   git clone git@github.com:strapi/strapi.git

2. Install all the dependencies:

   cd strapi && yarn setup

3. Run the @strapi/helper-plugin Storybook instance:

   cd packages/core/helper-plugin
   yarn storybook

💡 Tip

When running the Storybook instance provided with the @strapi/helper-plugin, the documentation for the useNotification hook can be found at http://localhost:6006/?path=/story/hooks-usenotification--page.