Release Notes > Older Releases > 5.35.0
Upgrade From 5.34.x to 5.35.0
Learn how to upgrade Webiny from 5.34.x to 5.35.0.
Before upgrading to 5.35.0
, please ensure your Webiny project is using the new project
setup, introduced with Webiny
5.29.0. In case you did not already migrate, please visit the migration
guide.
- how to upgrade Webiny from 5.34.x to 5.35.0
Make sure to check out the 5.35.0 changelog to get familiar with the changes introduced in this release.
Step-by-Step Guide
The following steps will guide you through the upgrade process. Please note that this guide assumes you are using the new project setup, introduced with Webiny 5.29.0. In case you did not already migrate, please visit the migration guide.
1. Upgrade Webiny Packages
Upgrade all @webiny/*
packages by running the following command:
Once the upgrade has finished, running the yarn webiny --version
command in your terminal should return 5.35.0
.
2. Run the Upgrade Command
The next step is to run the project upgrade:
For more information, please read the Upgrade Command - Additional Notes section below.
3. Upgrade Your Code to the New Lambda Function Setup
In the 5.35.0 we are removing the Headless CMS Lambda function from the deployment. This is a breaking change, but it should not take you a long time to fix.
Please read the Removing the Headless CMS Lambda Function article to learn how to upgrade your code to the new Lambda function setup.
4. Deploy Your Project
Proceed by redeploying your Webiny project:
Once deployed, access your Admin app to finalize the Page Builder upgrade, which will migrate your existing page blocks to the new Block Manager.
Make sure you deploy the entire system using the command shown above! You have to deploy all apps before using the system. Partial deploys may cause the upgrade to be applied incorrectly.
As stated in the Upgrade Webiny section, we recommend that you
first deploy your changes into one of your pre-production environments, like dev
or staging
.
Learn more about different deployment environments in the CI/CD / Environments key topic.
Upgrade Command
Additional Notes
The following sections explains some of the steps that the upgrade command performs. We recommend that you read through them to get familiar with the changes introduced in this release.
Note that there might be cases where the upgrade command will not be able to automatically apply the changes. In such cases, you will be prompted to manually apply the changes.
Theme Object
The upgrade command will perform a couple of code level changes related to your website’s theme object structure.
Note that in order to receive these changes, your project must be using the latest Page Builder page rendering engine, introduced with Webiny 5.34.0.
styles.typography
Prior to this release, within the theme object, the styles.typography
property referenced an object where keys represented the typography variant (heading1, heading2, etc.), and values were objects representing the actual typography styles. For example:
From now on, the styles.typography
property references an object where keys represent the typography type (heading, paragraph, etc.), and values are arrays of objects, where each object represents a specific typography variant. Each typography variant is an object that consists of four properties: id
, name
, tag
, and styles
. For example:
The upgrade command will automatically update the styles.typography
object in your theme/theme.ts
file. But do note that if you’ve added custom typography variants, the upgrade might not be able to update the styles.typography
object correctly. In that case, manual intervention will be required.
Accessing Typography Styles
The second change is related to the way typography styles are accessed. Previously, you could access typography styles via the styles.typography
object, and then by using the typography variant as a key, for example:
Since the structure of the styles.typography
object has changed, you will need to access typography styles via the styles.typography
object, and then by using the typography type as a key, and finally by using the typography variant as a key, for example
But, since this is a bit cumbersome, we’ve introduced a new utility function called stylesById
that will make it easier to access typography styles. For example, if you want to access the heading1
typography variant, you can do so by using the following:
The upgrade command will automatically update the styles.typography
object in your theme/theme.ts
file. But
if for some reason it fails to do so, you can manually update usage of the styles.typography
object in your project.
Theme Object Accessed via Context Object
Prior to version 5.35.0, upon creating styled React components, if required, the theme
object would be accessed by directly importing the theme/theme.ts
file. This is no longer the case as, from now on, the object should be accessed via React context.
For example, if in your Webiny project you had something like the following:
With the new version, the following changes should be made:
Note that the upgrade command will try to detect legacy usages of the theme
object and will try to adjust them automatically. However, if you have custom code that uses the theme
object, you might need to make the necessary adjustments manually. You will notice this as, upon running the webiny watch
command against the Admin or the Website application, errors will be reported.
Default Form Layout Replaced
Because of all of the theme object-related changes, and also new improvements that have been introduced to the Form Builder application, note that your default form layout will be backed up and completely replaced with the latest version of the layout. This means that if you have made any customizations to the default form layout, you will need to manually re-apply them to the new layout.
Note that in order to receive these changes, your project must be using the latest Page Builder page rendering engine, introduced with Webiny 5.34.0.
Emotion 11
With this release, we are upgrading Emotion library to version 11.
Across multiple package.json
files, the upgrade command will upgrade versions of all @emotion
packages to version 11. It will also replace all usages of the @emotion/core
package with the new @emotion/react
(@emotion/core
package is now deprecated).
Note that in order to receive these changes, your project must be using the latest Page Builder page rendering engine, introduced with Webiny 5.34.0.
Troubleshooting
The following are some of the most common issues that you might encounter when upgrading to version 5.35.0.
Typography Variant Was Categorized as a Paragraph, Double Check if a Different Category Is More Appropriate.
This warning is printed when the upgrade command is unable to categorize a custom typography variant that you might have added to the theme/theme.ts
file, within the styles.typography
object. For example, this will happen if you have something like the following:
Since it’s impossible to detect the correct category, the upgrade command will categorize the myCustomTypography
variant as a paragraph:
If you believe that this is not the correct category, you can manually update the styles.typography
object in your theme/theme.ts
file. For example, you might want to move the myCustomTypography
variant into the headings
category:
To learn more about the new theme object and typography-related changes, check out the above Theme Object section.
Could Not Migrate Some of the Theme Object's Typography-Related Code.
This error is printed when the upgrade command is unable to migrate all of the typography-related code in your project. This usually happens when you have custom code that uses the theme
object or sometimes in case typography variants are being accessed. For example, if you had the following Emotion styled component:
The heading1
object is now accessed via the theme
context object, so the above code will need to be adjusted to the following:
To learn more about the new theme object and typography-related changes, check out the above Theme Object section.
Found Custom Emotion Plugins in Your Project. Please Make Sure to Update Them to the Latest Version.
Note that if you’ve been using custom Babel plugins for Emotion, you will need to manually update them to the latest version.
These are usually introduced via webiny.config.ts
files. For example, if you had something like the following in either your apps/admin/webiny.config.ts
or apps/website/webiny.config.ts
files:
You will need to adjust it to the following:
In case of the above, note that the options for the @emotion/babel-plugin
are different from the ones for the babel-plugin-emotion
plugin. You can find more information about the new plugin here.
To learn more about the Emotion 11 upgrade, check out the above Emotion 11 section.
Some of the Theme-Related Upgrades Were Not Applied Because You Are Using an Older Version of the Page Builder Rendering Engine.
If you received this warning while upgrading, it means that your project is not using the latest Page Builder rendering engine, introduced with Webiny 5.34.0. To learn more about the new rendering engine and how to upgrade, check out the Page Builder - Page Rendering Engine Migration tutorial.
Running thewebiny upgrade
Command Fails WithENOENT: no such file or directory, chmod ...
Message
If you’re receiving an error similar to the following:
This could be due to a caching issue. To fix it, try running the following commands:
Alternatively, we’ve seen upgrading npx
to the latest version also fixes the issue: