Migration guide: Developer portal 1.1.0

Developer portal 1.1.0 is a major release that implements the new Reference docs 2.0 features and enhancements for integrated API reference documentation. This migration guide highlights changes that will impact the appearance and behavior of your portal, and provides upgrade instructions for your deployments.

In this guide:

  1. New features in Developer portal 1.1.0
  2. Compatibility changes
  3. Upgrade to Developer portal 1.1.0
  4. Continue using Developer portal 1.0.x

New features

The biggest feature in Developer portal 1.1.0 is the integration of Reference docs 2.0. This means that all new features, options, and compatibility changes from Reference docs 2.0 will be included in the Developer portal, and will affect the appearance and behavior of integrated API reference documentation.

For more information about deprecated options and required changes, refer to the Compatibility changes section of the Reference docs 2.0 migration guide.

Compatibility changes

These changes break compatibility with previous versions. Adjust your portal settings accordingly before upgrading to prevent build failures after the upgrade.

Renamed package

The package @redocly/ui is now deprecated. We recommend you start migrating to the new package @redocly/developer-portal/ui, as the old one will be supported only for a limited time.

Adjust Reference docs configuration options

The new Developer portal uses the new Reference docs package which had some compatibility changes. Adjust settings in all .page.yaml files according to the Reference docs migration guide.

For example:

  type: reference-docs
  definitionId: petstore
  settings:
-   layout:
-     showNextButton: false
+   showNextButton: false

The new Reference docs package introduces a number of new theme knobs. Make sure to adjust some if needed.

OpenAPI CLI integration

The new Developer portal uses the latest version of the openapi-cli package which may detect new errors that were not found by the previous version.

To prevent such errors from blocking the portal build, you can either:

  • disable some rules in the lint.rules section of the top-level .redocly.yaml configuration file

or

Button component usage

If you're using the Button component anywhere in your portal, be aware that some of its properties have changed and must be modified in order to display the component properly.

Specifically, you must make the following changes:

  • Button defaults to the secondary color (used to be primary), adjust where needed:

    - <Button> My Button </Button>
    + <Button color="primary"> My Button </Button>
  • transparent was removed, use variant="outlined" instead

    - <Button transparent> My Button </Button>
    + <Button color="primary" variant="outlined"> My Button </Button>
  • inversed was removed, use color="secondary" instead

    - <Button inversed transparent> My Button </Button>
    + <Button color="secondary" variant="outlined"> My Button </Button>
  • big and small was removed, use size instead

    - <Button big> My Button </Button>
    + <Button color="primary" size="large"> My Button </Button>
    - <Button small> My Button </Button>
    + <Button color="primary" size="small"> My Button </Button>
  • color doesn't accept any colors, instead color has to be defined in theme.colors

    page.mdxtheme.ts
    - <Button color="orange"> My Button </Button>
    + <Button color="myBrand"> My Button </Button>
    colors: {
      primary: { ... }
    + myBrand: { main: "orange", contrastText: "#fff" }
      ...
    }

Default font settings

The default font family in the Developer portal theme and in the Reference docs theme has changed to typography.fontFamily='Source Sans Pro, sans-serif'.

The default code font family has changed to typography.code.fontFamily='Source Code Pro, sans-serif'.

If you don't have your custom fonts specified in theme.ts or if you want to use these fonts too, you must add the following to the stylesheets section in your siteConfig.yaml file:

  stylesheets:
+   - https://fonts.googleapis.com/css?family=Source+Code+Pro:300,400,600,700|Source+Code+Pro&display=swap`

Upgrade to Developer portal 1.1.0

  1. Prior to upgrading the portal, access the root directory of your Developer portal project and remove yarn.lock and node_modules from it.
  2. In the same root directory, access the package.json file. Open the file and find @redocly/developer-portal in the @dependencies section.
  3. Change the version number to 1.1.0-beta.28 (or the most current version) like in the following example:

     "dependencies": {
     "@redocly/developer-portal": "1.1.0-beta.28"
    }
  4. Save the changes to the package.json file.
  5. Run yarn install in the root directory to upgrade your portal.

Installing the new portal version will recreate the yarn.lock file. Make sure to commit the changes to that file into your version control system. This is a prerequisite for Developer portal projects hosted in Workflows, because it enables Workflows to build your portal with the new version.

Continue using Developer portal 1.0.x

The last supported version in the Developer portal 1.0.x release channel is 1.0.0-beta.162.

We advise all customers to switch to the new Developer portal and upgrade to the 1.1.0-beta.28 or most current version.

If you choose to continue using an older version of the Developer portal, keep in mind that you will not receive security upgrades or new features and improvements. Additionally, you will not be able to use the new Reference docs 2.0 for integrated API reference documentation in your portal.