跳到主要内容

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 v3Equivalent feature in v4
    strapi.notification callsuseNotification hook
    strapi.lockApp callslockApp method from the useOverlayBlocker hook
    strapi.unlockApp callsunlockApp method from the useOverlayBlocker hook
    strapi.backendUrl callsstrapi.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.