Upgrade From 5.34.x to 5.35.0

Step-by-Step Guide

1. Upgrade Webiny Packages

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

The next step is to run the project upgrade:

yarn webiny upgrade

3. Upgrade Your Code to the New Lambda Function Setup

4. Deploy Your Project

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.

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:

{
  // ...
  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:

{
  // ...
  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 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:

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"]);

Default Form Layout Replaced

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

{
  // ...
  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:

{// ...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:

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

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:

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  }}));

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:

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:

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