Warning
You're browsing the documentation for an old version of Webiny. Consider upgrading your project to Webiny 5.35.x.
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.
What you’ll learn
  • 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
anchor

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
anchor

Upgrade all @webiny/* packages by running the following command:

yarn up "@webiny/*@5.35.0"

Once the upgrade has finished, running the yarn webiny --version command in your terminal should return 5.35.0.

2. Run the Upgrade Command
anchor

The next step is to run the project upgrade:

yarn webiny upgrade
This script will create backups of some files, so make sure you review the changes, and manually apply any changes you might have in those files to the new files.

For more information, please read the Upgrade Command - Additional Notes section below.

If the upgrade command ends in error "Script does not exist.", please clear your npx cache. You can run npx clear-npx-cache to clear it, or just delete it manually from your npx directory.

3. Upgrade Your Code to the New Lambda Function Setup
anchor

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
anchor

Proceed by redeploying your Webiny project:

# Execute in your project root.
yarn webiny deploy --env {environment}

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
anchor

Additional Notes
anchor

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
anchor

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:

apps/theme/theme.ts
{
  // ...
  styles: {
    typography: {
      heading1: {
        // ...
      },
      heading2: {
        // ...
      },
      // ...
    }
  }
}

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:

apps/theme/theme.ts
{
  // ...
  styles: {
    typography: {
      heading: [
        {
          id: "heading1",
          name: "Heading 1",
          tag: "h1",
          styles: {
            // ...
          }
        },
        {
          id: "heading2",
          name: "Heading 2",
          tag: "h2",
          styles: {
            // ...
          }
        },
        // ...
      ],
      paragraph: [
        {
          id: "paragraph1",
          name: "Paragraph 1",
          tag: "p",
          styles: {
            // ...
          }
        },
        {
          id: "paragraph2",
          name: "Paragraph 2",
          tag: "p",
          styles: {
            // ...
          }
        },
        // ...
      ],
      // ...
    }
  }
}

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:

theme.styles.typography.heading1

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

theme.styles.typography["headings"][0]

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:

theme.styles.typography["headings"].stylesById["heading1"]

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 external link 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 external link.

For example, if in your Webiny project you had something like the following:

import theme from "../../theme";

const Heading = styled.div(theme.styles.typography["heading1"]);

With the new version, the following changes should be made:

// No need for the import anymore.import theme from "../../theme";
// The theme object is now accessed via the context object.const Heading = styled.div(theme.styles.typography["heading1"]);const Heading = styled.div(({ theme }) => theme.styles.typography["heading1"]);
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
anchor

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
anchor

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 external link packages to version 11. It will also replace all usages of the @emotion/core external link package with the new @emotion/react external link (@emotion/core external link 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
anchor

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

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:

apps/theme/theme.ts
{
  // ...
  styles: {
    typography: {
      // Custom typography key.
      myCustomTypography: {
        // ...
      },
    }
  }
}

Since it’s impossible to detect the correct category, the upgrade command will categorize the myCustomTypography variant as a paragraph:

apps/theme/theme.ts
{// ...styles: {  typography: {    paragraphs: {      // Custom typography key.      myCustomTypography: {        // ...      },    },  }}}

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:

apps/theme/theme.ts
{// ...styles: {  typography: {    paragraphs: {      // Remove the custom typography variant here.      myCustomTypography: {        // ...      }    },    headings: {      // Move the custom typography variant here.      myCustomTypography: {        // ...      }    }  }}}

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

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:

const CustomStyledComponent = styled('div')({
    h1: {
        ...typography.heading1,
        marginBottom: 20,
        marginTop: 50
    }
});

The heading1 object is now accessed via the theme context object, so the above code will need to be adjusted to the following:

const CustomStyledComponent = styled('div')({const CustomStyledComponent = styled('div')(({ theme }) => ({ // The theme object is now accessed via the context object.   h1: {      ...typography.heading1,      ...theme.styles.typography["headings"].stylesById("heading1"),      marginBottom: 20,      marginTop: 50  }}));

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

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:

apps/admin/webiny.config.ts or apps/website/webiny.config.ts
import { createWebsiteAppConfig } from "@webiny/serverless-cms-aws";

export default createWebsiteAppConfig(({ config }) => {
    config.babel(babelConfig => {
        return {
            ...babelConfig,
            plugins: [...babelConfig.plugins, ["babel-plugin-emotion", { autoLabel: true }]]
        };
    });
});

You will need to adjust it to the following:

apps/admin/webiny.config.ts or apps/website/webiny.config.ts
import { createWebsiteAppConfig } from "@webiny/serverless-cms-aws";
export default createWebsiteAppConfig(({ config }) => {  config.babel(babelConfig => {      return {          ...babelConfig,          plugins: [...babelConfig.plugins, ["babel-plugin-emotion", { autoLabel: true }]]          plugins: [...babelConfig.plugins, ["@emotion", { autoLabel: "always"}]]
      };  });});

In case of the above, note that the options for the @emotion/babel-plugin external link are different from the ones for the babel-plugin-emotion external link plugin. You can find more information about the new plugin here external link.

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

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.