From 23c7f9a68deed2ddb8cff0efe19e05b01f66210c Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Mon, 29 Aug 2022 15:47:31 +0200 Subject: [PATCH] docs: add react router migration docs to sidebar + few tweaks Co-authored-by: Johan Haals Signed-off-by: Patrik Oldsberg --- .../react-router-stable-migration.md | 35 +++++++++++-------- microsite/sidebars.json | 1 + mkdocs.yml | 1 + 3 files changed, 22 insertions(+), 15 deletions(-) diff --git a/docs/tutorials/react-router-stable-migration.md b/docs/tutorials/react-router-stable-migration.md index 521cfe355d..1e5b5816c2 100644 --- a/docs/tutorials/react-router-stable-migration.md +++ b/docs/tutorials/react-router-stable-migration.md @@ -1,17 +1,20 @@ --- -id: read-router-stable-migration -title: react-router stable migration -description: Guide for how to migrate from react-router beta to react-router 6 stable +id: react-router-stable-migration +title: React Router 6.0 Migration +description: Guide for how to migrate from React Router v6 beta to React Router v6 stable --- -Backstage has for a long time been using `react-router` version `6.0.0-beta.0`. We adopted this unstable -version because v6 had some new and features that fit really well with Backstage, particularly relative routing. -Because we jumped on this early and unstable version, we knew that we would at some point need -a breaking migration to the stable version of `react-router` v6, which is the point we're at now! +Backstage has for a long time been using `react-router` version `6.0.0-beta.0`. +We adopted this unstable version because v6 had some new features that fit +really well with Backstage, particularly relative routing. Because we jumped on +this early and unstable version, we knew that we would at some point need a +breaking migration to the stable version of `react-router` v6, which is the +point we're at now! -This migration is required but controlled by each app, meaning that you choose when you want -to migrate your app. There will however be some point in the future where we drop support for the -beta version of `react-router`, at which point you would be forced to migrate. +This migration is required but controlled by each app, meaning that you choose +when you want to migrate your app. There will however be some point in the +future where we drop support for the beta version of `react-router`, at which +time you would be forced to migrate. The stable version of React Router v6 brings a number of improvements and bug fixes. Notably, the way that paths are resolved has been improved, which fixes a @@ -25,12 +28,14 @@ The first Backstage release to support `react-router` v6 is `1.6`. You should up ### Step 2 - Move `react-router` to `peerDependencies` -It's important that only one version of `react-router` is installed in the project at a time. Similar to how the `react` version -is handled, all plugins and packages now declare a peer dependency on the React Router dependencies, rather than a direct dependency. -The only exception to this is the app package, which has the direct dependencies that end up deciding what version of React Router that -you are using in your project. +It's important that only one version of `react-router` is installed in the +project at a time. Similar to how the `react` version is handled, all plugins +and packages now declare a peer dependency on the React Router dependencies, +rather than a direct dependency. The only exception to this is the app package +(in `packages/app/package.json`), which has the direct dependencies that end up +deciding what version of React Router that you are using in your project. -Your internal packages might specify a dependency on `react-router` or `react-router-dom` in their `package.json` and important that those are converted to `peerDependencies` so we can control the version of `react-router` in the app `package.json`. +Your internal packages might specify a dependency on `react-router` or `react-router-dom` in their `package.json`, and it's important that those are converted to `peerDependencies` so that we can control the version of `react-router` in the app `package.json`. You can automate this step by running the following command: diff --git a/microsite/sidebars.json b/microsite/sidebars.json index 04f5623c86..283a87dfbc 100644 --- a/microsite/sidebars.json +++ b/microsite/sidebars.json @@ -325,6 +325,7 @@ "Tutorials": [ "tutorials/journey", "tutorials/quickstart-app-plugin", + "tutorials/react-router-stable-migration", "tutorials/package-role-migration", "tutorials/migrating-away-from-core", "tutorials/configuring-plugin-databases", diff --git a/mkdocs.yml b/mkdocs.yml index e3bd86afdb..0240744824 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -181,6 +181,7 @@ nav: - Deprecations: 'api/deprecations.md' - Tutorials: - Future developer journey: 'tutorials/journey.md' + - React Router 6.0 Migration: 'tutorials/react-router-stable-migration.md' - Package Role Migration: 'tutorials/package-role-migration.md' - Migrating away from @backstage/core: 'tutorials/migrating-away-from-core.md' - Adding Custom Plugin to Existing Monorepo App: 'tutorials/quickstart-app-plugin.md'