Skip to main content

v4.0.0+ to v4.0.6 migration guide

The Strapi v4.0.0+ to v4.0.6 migration guide upgrades versions of v4.0.0 and above to v4.0.6. The migration adds the session middleware to the middleware array and configures the session middleware. The session middleware is based on koa-session and is necessary to fix the login provider feature of the Users & Permissions plugin. Additionally, password protection in the Documentation plugin uses the session middleware. The migration guide consists of 3 sections:

  • upgrading the application dependencies
  • migrating the breaking changes to the middleware
  • reinitializing the application
✋ Caution

Plugins extension that create custom code or modify existing code, will need to be updated and compared to the changes in the repository. Not updating the plugin extensions could break the application.

Upgrading the application dependencies​

Upgrade all of the Strapi packages in the package.json to 4.0.6:

path: ./package.json

{
  // ...
  "dependencies": {
    "@strapi/strapi": "4.0.6",
    "@strapi/plugin-users-permissions": "4.0.6",
    "@strapi/plugin-i18n": "4.0.6",
    "sqlite3": "5.0.2"
    // ...
  }
}

  1. Save the edited package.json file.

  2. Install the upgraded version:

    yarn
    💡 Tip

    If the operation doesn't work, try removing your yarn.lock or package-lock.json. If that doesn't help, remove the node_modules folder as well and try again.

Fixing the breaking changes​

  1. Add the strapi::session middleware to the array in the middleware configuration file ./config/middlewares.js:
path: ./config/middlewares.js

module.exports = [
  'strapi::errors',
  'strapi::security',
  'strapi::cors',
  'strapi::poweredBy',
  'strapi::logger',
  'strapi::query',
  'strapi::body',
  'strapi::session',
  'strapi::favicon',
  'strapi::public',
];
  1. Configure the session middleware by adding the key settings to the server.js configuration file (see session middleware for more information). The secrets are typically stored in .env during development. In most use cases the keys will be different for each environment. For example, a different set of keys should be used for the production and the development environments. Storing default keys in the configuration file is not recommended.
path: ./config/server.js

  // ...
  app: {
    keys: env.array("APP_KEYS"),
  },
// ...
Example of the updated file
path: ./config/server.js

module.exports = ({ env }) => ({
  host: env('HOST', '0.0.0.0'),
  port: env.int('PORT', 1337),
  app: {
    keys: env.array("APP_KEYS"),
  },
  // ...
});

⚠️ Warning

It is a security risk to expose static session middleware keys in a deployed environment. An .env file or environment variables should be used instead.

Example: sessions keys in .env file
APP_KEYS=[someSecret, anotherSecret, additionalSecrets]

or

APP_KEYS=someSecret,anotherSecret,additionalSecrets

Rebuild the application​

Run the following command in your project root directory to rebuild Strapi's admin panel:

yarn build

Restart the application​

Run the following command in your project root directory to restart the application:

yarn develop