- how to upgrade Webiny from 5.16.0 to 5.17.0
Make sure to check out the 5.17.0 changelog to get familiar with all the changes introduced in this release.
First, we need to prepare your project for the upgrade process. With security packages refactor, some packages no longer exist, and if we try to upgrade dependencies straight away,
yarn will complain. To fix that, we need to clean up your project first, to eliminate references to those deprecated packages.
In your project root, run the following:
We’re now ready to upgrade all
@webiny/* packages! Run the following command:
Once the upgrade has finished, running the
yarn webiny --version command in your terminal should return
Before moving on, make sure you commit all your changes.
Now let’s run the project upgrade:
The upgrade script will make a couple of changes to your existing API project application’s code (located within the
api folder) and several changes to your Admin Area project application. Once the upgrade command has finished, you can run the
git status command to see all changes that the command performed.
After testing the upgrade with several of our clients, we discovered various edge cases that were not originally handled by the migration script. Those edge cases originated from the earlier Webiny versions, prior to 5.16. To make the upgrade script more robust, you need to run the following gist, before deploying your project:
If you’re deploying your project from a CI/CD pipeline, make sure you add this command before your deploy step.
Before moving on to the next step, review the changes in your IDE, and remove the backup files created by the upgrade script.
Finally, proceed by redeploying your Webiny project:
As stated in the Upgrade Webiny section, we recommend that you first deploy your changes into one of your pre-production environments, like
We are aware of the problems that can occur when upgrading project files, especially since there are so many files that make up a single Webiny project. It also requires a lot of effort and time on our side to write these upgrade scripts, test them, and make them reliable (at least for the major part of our users).
With that, we want to let you know that we are already working on an improved project setup which will greatly reduce the amount of files in your project, and will bring the need for these project-level file modifications in between releases to a minimum.
If you’re willing to contribute your thoughts and ideas, join the Github discussion Webiny Projects - Simplify Organization of Folders and Files.
Although the new security layer takes the old
security-authorization plugins into consideration, we recommend migrating your custom security plugins, if you have any.
To see an example of an up-to-date authentication plugin, see the official implementation of a Cognito authentication plugin. As you will find, we no longer need a dedicated plugin, but instead, we register an authentication function directly into the
security app, which lives on the
context object. Same goes for authorization plugins.
This way, it’s much easier to group your functionality into one
ContextPlugin plugin, and hook into all the parts of the system you want to extend.
If you use the
UserPlugin plugin to hook into Cognito users in your project, you will need to migrate it to the new event system. All the previous events are supported, they just have slightly different TS types, and are registered differently. Here’s an example:
And the same goes for other events that were supported previously. Note how
context object is no longer passed to your callback as an argument, but is instead available to you from the parent scope.