Last updated

Migration guide: Developer portal 1.1.0

Deprecated docs

The developer portal beta is approaching end of life.

Use Realm and Reunite instead. Read the migration guide.

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 impact the appearance and behavior of your portal, and provides upgrade instructions for your deployments.

In this guide:

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 are included in the Developer portal, and 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 is 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.

Redocly CLI integration

The new Developer portal uses the latest version of the redocly-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 rules object of the top-level redocly.yaml configuration file

or

Button component usage

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

    - <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 recreates 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 do not receive security upgrades or new features and improvements. Additionally, you are not able to use the new Reference docs 2.0 for integrated API reference documentation in your portal.

 
Next page