Skip to main content

v4.0.6+ to v4.1.8 migration guide

The Strapi v4.0.6+ to v4.1.8 migration guide upgrades versions of v4.0.6 and above to v4.1.8. The minimum configuration for config/admin now includes the API token API_TOKEN_SALT. Strapi no longer populates default values for the admin JWT in config/admin. Initial values are generated and stored in the .env file during project creation. Strapi no longer passes secrets to non-development environments, requiring users to set the secrets purposefully. The migration to v4.1.8 consists of 4 steps:

  • Upgrading the application dependencies
  • Fixing the breaking changes
  • Setting secrets for non-development environments
  • 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 to 4.1.8​

☑️ Prerequisites

Stop the server before starting the upgrade.

  1. Upgrade all of the Strapi packages in the package.json to 4.1.8:
path: ./package.json

{
  // ...
  "dependencies": {
    "@strapi/strapi": "4.1.8",
    "@strapi/plugin-users-permissions": "4.1.8",
    "@strapi/plugin-i18n": "4.1.8",
    "better-sqlite3": "7.4.6"
    // ...
  }
}

  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. Modify the config/admin file. Strapi, by default, creates the environmental variable API_TOKEN_SALT and populates a unique value, stored in /.env at project creation. In order to update config/admin:
  • add the apiToken object,
  • remove the comma and default value from the ADMIN_JWT_SECRET parenthetical.
path: config/admin.js

module.exports = ({ env }) => ({
  auth: {
    secret: env('ADMIN_JWT_SECRET'),
  },
  apiToken: {
    salt: env('API_TOKEN_SALT'),
  },
});

  1. ConfigureJWT_SECRET. JWT_SECRET is used by the Users and Permissions plugin, and populated in /.env. The property should be stored in config/plugins.js (or config/plugins.ts for a TypeScript project). The plugins file is not created by default in a Strapi application. If the file does not exist, users should create the file and add the following code snippet.
path: ./config/plugins.js

module.exports = ({ env }) => ({
  // ...
  'users-permissions': {
    config: {
    jwtSecret: env('JWT_SECRET')
  },
  },
  // ...
});

Setting secrets for non-development environments​

Users are required to set secrets for each unique environment, such as a production environment deployment on a platform. Strapi no longer passes the following secrets to non-development environments:

  • APP_KEYS
  • JWT_SECRET
  • API_TOKEN_SALT
  • ADMIN_JWT_SECRET

There are multiple methods to generate secrets, for example running openssl rand -base64 32 in the terminal (Mac and Linux OS). Generating unique secrets for each environment is recommended for increased security.

✋ Caution

The Hosting Provider Guides are being updated to reflect these changes. Community contributions updating the hosting guides are encouraged.

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