Upgrade From 5.34.x to 5.35.0

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:

3. Upgrade Your Code to the New Lambda Function Setup

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.

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.

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.

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).

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:

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:

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.

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 upgradeCommand 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: