From 82a42f34a1565028436890b96eb48104b5363cbb Mon Sep 17 00:00:00 2001 From: Philipp Hugenroth Date: Fri, 2 Jun 2023 17:01:00 +0200 Subject: [PATCH 01/11] Add Migrating to v5 Guide in Custom Theme Documentation Signed-off-by: Philipp Hugenroth --- docs/getting-started/app-custom-theme.md | 25 ++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/docs/getting-started/app-custom-theme.md b/docs/getting-started/app-custom-theme.md index 3b042d5eb4..dff7754852 100644 --- a/docs/getting-started/app-custom-theme.md +++ b/docs/getting-started/app-custom-theme.md @@ -484,3 +484,28 @@ You can see more ways to use this in the [Storybook Sidebar examples](https://ba In addition to a custom theme, a custom logo, you can also customize the homepage of your app. Read the full guide on the [next page](homepage.md). + +## Migrating to Material UI v5 + +For supporting Material UI v5 in addition to v4 we introduced a `UnifiedThemeProvider` allowing a step-by-step migration. To use it you have to update your App's `ThemeProvider` in `app/src/App.tsx` like the following: + +```diff + Provider: ({ children }) => ( +- +- {children} +- ++ + ), +``` + +When you are looking for migrating code from v4 to v5 the [Migration Guide provided by MUI](https://mui.com/material-ui/migration/migration-v4/) might be a helpful resource. It is worth mentioning that we are still using `@mui/styles` & thereby `jss`. You might stumble accross the migration to `emotion` for `makeStyles` or `withStyles`. It is not required to move to `emotion` yet. + +### Plugins + +To migrate your plugin to MUI v5 you can build up on the resources available. + +1. Run the migration `codemod` for the path of the specific plug: `npx @mui/codemod v5.0.0/preset-safe ` +2. Manual fix imports to align with linting rules & take a look at potential `TODO:` items the `codemod` could not fix. +3. Remove types & methods from `@backstage/theme`, which are marked as `@deprecated` + +You can follow the [migration of the GraphiQL plugin](https://github.com/backstage/backstage/pull/17696) as an example plugin migration. From ecc4e417e4d7a8be4ea39e80f75741dd37db57ff Mon Sep 17 00:00:00 2001 From: Philipp Hugenroth Date: Tue, 13 Jun 2023 13:04:40 +0200 Subject: [PATCH 02/11] Improve English & add additional information from feedback Signed-off-by: Philipp Hugenroth --- docs/getting-started/app-custom-theme.md | 26 ++++++++++++++---------- 1 file changed, 15 insertions(+), 11 deletions(-) diff --git a/docs/getting-started/app-custom-theme.md b/docs/getting-started/app-custom-theme.md index dff7754852..bbbb878942 100644 --- a/docs/getting-started/app-custom-theme.md +++ b/docs/getting-started/app-custom-theme.md @@ -487,25 +487,29 @@ homepage of your app. Read the full guide on the [next page](homepage.md). ## Migrating to Material UI v5 -For supporting Material UI v5 in addition to v4 we introduced a `UnifiedThemeProvider` allowing a step-by-step migration. To use it you have to update your App's `ThemeProvider` in `app/src/App.tsx` like the following: +To support Material UI v5 in addition to v4, we have introduced a `UnifiedThemeProvider`. This allows a step-by-step migration. To use it, you need to update your app's `ThemeProvider` in `app/src/App.tsx` as follows ```diff - Provider: ({ children }) => ( -- -- {children} -- -+ + provider: ({ children }) => ( +- . +- {children}. +- ), ``` -When you are looking for migrating code from v4 to v5 the [Migration Guide provided by MUI](https://mui.com/material-ui/migration/migration-v4/) might be a helpful resource. It is worth mentioning that we are still using `@mui/styles` & thereby `jss`. You might stumble accross the migration to `emotion` for `makeStyles` or `withStyles`. It is not required to move to `emotion` yet. +In addition, the [Migration Guide provided by MUI](https://mui.com/material-ui/migration/migration-v4/) is a helpful resource that breaks down the differences between v4 & v5. It is worth noting that we are still using `@mui/styles` & `jss`. You may stumble upon documentation for migrating to `emotion` when using `makeStyles` or `withStyles`. It is not necessary to switch to `emotion` yet. + +To comply with MUI recommendations, we are enforcing a new linting rules that favours standard imports over named imports and also restricting 3rd level imports as they are considered private ([Guide: Minimizing Bundle Size](https://mui.com/material-ui/guides/minimizing-bundle-size)). + +For current knonw issues with the MUI v5 migration follow our [Milestone on GitHub](https://github.com/backstage/backstage/milestone/40). Please open a new issue if you run into different problems. ### Plugins -To migrate your plugin to MUI v5 you can build up on the resources available. +To migrate your plugin to MUI v5, you can build on the resources available. -1. Run the migration `codemod` for the path of the specific plug: `npx @mui/codemod v5.0.0/preset-safe ` -2. Manual fix imports to align with linting rules & take a look at potential `TODO:` items the `codemod` could not fix. -3. Remove types & methods from `@backstage/theme`, which are marked as `@deprecated` +1. Run the migration `codemod` for the path of the specific plugin: `npx @mui/codemod v5.0.0/preset-safe `. +2. Manually fix the imports to match the new [linting rules](https://mui.com/material-ui/guides/minimizing-bundle-size). Take a look at possible `TODO:` items the `codemod` could not fix. +3. Removal of types & methods from `@backstage/theme` which are marked as `@deprecated`. You can follow the [migration of the GraphiQL plugin](https://github.com/backstage/backstage/pull/17696) as an example plugin migration. From b4be4e630a7957dd15c346ffda5ac9e21958c042 Mon Sep 17 00:00:00 2001 From: Philipp Hugenroth Date: Tue, 13 Jun 2023 13:17:30 +0200 Subject: [PATCH 03/11] Move migration guides to tutorials Signed-off-by: Philipp Hugenroth --- docs/getting-started/app-custom-theme.md | 27 +------------------ docs/tutorials/migrate-to-mui5.md | 34 ++++++++++++++++++++++++ 2 files changed, 35 insertions(+), 26 deletions(-) create mode 100644 docs/tutorials/migrate-to-mui5.md diff --git a/docs/getting-started/app-custom-theme.md b/docs/getting-started/app-custom-theme.md index bbbb878942..d6a13ca6e3 100644 --- a/docs/getting-started/app-custom-theme.md +++ b/docs/getting-started/app-custom-theme.md @@ -487,29 +487,4 @@ homepage of your app. Read the full guide on the [next page](homepage.md). ## Migrating to Material UI v5 -To support Material UI v5 in addition to v4, we have introduced a `UnifiedThemeProvider`. This allows a step-by-step migration. To use it, you need to update your app's `ThemeProvider` in `app/src/App.tsx` as follows - -```diff - provider: ({ children }) => ( -- . -- {children}. -- - ), -``` - -In addition, the [Migration Guide provided by MUI](https://mui.com/material-ui/migration/migration-v4/) is a helpful resource that breaks down the differences between v4 & v5. It is worth noting that we are still using `@mui/styles` & `jss`. You may stumble upon documentation for migrating to `emotion` when using `makeStyles` or `withStyles`. It is not necessary to switch to `emotion` yet. - -To comply with MUI recommendations, we are enforcing a new linting rules that favours standard imports over named imports and also restricting 3rd level imports as they are considered private ([Guide: Minimizing Bundle Size](https://mui.com/material-ui/guides/minimizing-bundle-size)). - -For current knonw issues with the MUI v5 migration follow our [Milestone on GitHub](https://github.com/backstage/backstage/milestone/40). Please open a new issue if you run into different problems. - -### Plugins - -To migrate your plugin to MUI v5, you can build on the resources available. - -1. Run the migration `codemod` for the path of the specific plugin: `npx @mui/codemod v5.0.0/preset-safe `. -2. Manually fix the imports to match the new [linting rules](https://mui.com/material-ui/guides/minimizing-bundle-size). Take a look at possible `TODO:` items the `codemod` could not fix. -3. Removal of types & methods from `@backstage/theme` which are marked as `@deprecated`. - -You can follow the [migration of the GraphiQL plugin](https://github.com/backstage/backstage/pull/17696) as an example plugin migration. +We now support Material UI v5 in Backstage. Check out our [migration guide](../tutorials/migrate-to-mui5.md) to get started. diff --git a/docs/tutorials/migrate-to-mui5.md b/docs/tutorials/migrate-to-mui5.md new file mode 100644 index 0000000000..f757094d4c --- /dev/null +++ b/docs/tutorials/migrate-to-mui5.md @@ -0,0 +1,34 @@ +--- +id: migrate-to-mui5 +title: Migrating from Material UI v4 to v5 +description: Additionally resources to the Material UI migration guide specifically for Backstage +--- + +Before diving into the specific changes in Backstage, it may be helpful to take a look at the [Migration Guide provided by MUI](https://mui.com/material-ui/migration/migration-v4/). It breaks down the differences between v4, v5 and will make it easier to understand the impact on your Backstage instance & plugins. + +To support Material UI v5 in addition to v4, we have introduced a `UnifiedThemeProvider`. This allows a gradual migration by running both versions in parallel. To use it, you need to update your app's `ThemeProvider` in `app/src/App.tsx` as follows: + +```diff + provider: ({ children }) => ( +- . +- {children}. +- + ), +``` + +It is worth noting that we are still using `@mui/styles` & `jss`. You may stumble upon documentation for migrating to `emotion` when using `makeStyles` or `withStyles`. It is not necessary to switch to `emotion` yet. + +To comply with MUI recommendations, we are enforcing a new linting rules that favours standard imports over named imports and also restricting 3rd level imports as they are considered private ([Guide: Minimizing Bundle Size](https://mui.com/material-ui/guides/minimizing-bundle-size)). + +For current knonw issues with the MUI v5 migration follow our [Milestone on GitHub](https://github.com/backstage/backstage/milestone/40). Please open a new issue if you run into different problems. + +### Plugins + +To migrate your plugin to MUI v5, you can build on the resources available. + +1. Run the migration `codemod` for the path of the specific plugin: `npx @mui/codemod v5.0.0/preset-safe `. +2. Manually fix the imports to match the new [linting rules](https://mui.com/material-ui/guides/minimizing-bundle-size). Take a look at possible `TODO:` items the `codemod` could not fix. +3. Removal of types & methods from `@backstage/theme` which are marked as `@deprecated`. + +You can follow the [migration of the GraphiQL plugin](https://github.com/backstage/backstage/pull/17696) as an example plugin migration. From cc0f489d1cc2a33b3953f43d93b99b423166ce81 Mon Sep 17 00:00:00 2001 From: Philipp Hugenroth Date: Mon, 19 Jun 2023 09:15:28 +0200 Subject: [PATCH 04/11] Update MUI 5 Migration doc Signed-off-by: Philipp Hugenroth --- docs/tutorials/migrate-to-mui5.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/tutorials/migrate-to-mui5.md b/docs/tutorials/migrate-to-mui5.md index f757094d4c..3bbb2b43af 100644 --- a/docs/tutorials/migrate-to-mui5.md +++ b/docs/tutorials/migrate-to-mui5.md @@ -27,8 +27,9 @@ For current knonw issues with the MUI v5 migration follow our [Milestone on GitH To migrate your plugin to MUI v5, you can build on the resources available. -1. Run the migration `codemod` for the path of the specific plugin: `npx @mui/codemod v5.0.0/preset-safe `. -2. Manually fix the imports to match the new [linting rules](https://mui.com/material-ui/guides/minimizing-bundle-size). Take a look at possible `TODO:` items the `codemod` could not fix. -3. Removal of types & methods from `@backstage/theme` which are marked as `@deprecated`. +1. Manually fix the imports from named to default imports to match the new [linting rules for minimizing bundle size](https://mui.com/material-ui/guides/minimizing-bundle-size). +2. Run the migration `codemod` for the path of the specific plugin: `npx @mui/codemod v5.0.0/preset-safe plugins/`. +3. Take a look at possible `TODO:` items the `codemod` could not fix. +4. Remove types & methods from `@backstage/theme` which are marked as `@deprecated`. You can follow the [migration of the GraphiQL plugin](https://github.com/backstage/backstage/pull/17696) as an example plugin migration. From 62c6901fe80a6a9874d0672f275e2f2bc11f6b47 Mon Sep 17 00:00:00 2001 From: Philipp Hugenroth Date: Mon, 19 Jun 2023 09:20:20 +0200 Subject: [PATCH 05/11] Fix spelling issue Signed-off-by: Philipp Hugenroth --- docs/tutorials/migrate-to-mui5.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/migrate-to-mui5.md b/docs/tutorials/migrate-to-mui5.md index 3bbb2b43af..e36c1dc467 100644 --- a/docs/tutorials/migrate-to-mui5.md +++ b/docs/tutorials/migrate-to-mui5.md @@ -21,7 +21,7 @@ It is worth noting that we are still using `@mui/styles` & `jss`. You may stumbl To comply with MUI recommendations, we are enforcing a new linting rules that favours standard imports over named imports and also restricting 3rd level imports as they are considered private ([Guide: Minimizing Bundle Size](https://mui.com/material-ui/guides/minimizing-bundle-size)). -For current knonw issues with the MUI v5 migration follow our [Milestone on GitHub](https://github.com/backstage/backstage/milestone/40). Please open a new issue if you run into different problems. +For current known issues with the MUI v5 migration, follow our [Milestone on GitHub](https://github.com/backstage/backstage/milestone/40). Please open a new issue if you run into different problems. ### Plugins From d1f3e73a8e10e522be6cf979c0732e5c22076572 Mon Sep 17 00:00:00 2001 From: Philipp Hugenroth Date: Thu, 28 Sep 2023 15:24:26 +0200 Subject: [PATCH 06/11] Context on react 17 Signed-off-by: Philipp Hugenroth --- docs/tutorials/migrate-to-mui5.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/tutorials/migrate-to-mui5.md b/docs/tutorials/migrate-to-mui5.md index e36c1dc467..6f1036e4c2 100644 --- a/docs/tutorials/migrate-to-mui5.md +++ b/docs/tutorials/migrate-to-mui5.md @@ -17,10 +17,12 @@ To support Material UI v5 in addition to v4, we have introduced a `UnifiedThemeP ), ``` -It is worth noting that we are still using `@mui/styles` & `jss`. You may stumble upon documentation for migrating to `emotion` when using `makeStyles` or `withStyles`. It is not necessary to switch to `emotion` yet. +It is worth noting that we are still using `@mui/styles` & `jss`. You may stumble upon documentation for migrating to `emotion` when using `makeStyles` or `withStyles`. It is not necessary to switch to `emotion`. To comply with MUI recommendations, we are enforcing a new linting rules that favours standard imports over named imports and also restricting 3rd level imports as they are considered private ([Guide: Minimizing Bundle Size](https://mui.com/material-ui/guides/minimizing-bundle-size)). +Important to keep in mind is, that Material UI v5 is meant to be used with React Version 17 or higher. This means if you intend to use the Material UI v5 components in your plugins you have to enforce React Version to be at least 17. + For current known issues with the MUI v5 migration, follow our [Milestone on GitHub](https://github.com/backstage/backstage/milestone/40). Please open a new issue if you run into different problems. ### Plugins @@ -31,5 +33,6 @@ To migrate your plugin to MUI v5, you can build on the resources available. 2. Run the migration `codemod` for the path of the specific plugin: `npx @mui/codemod v5.0.0/preset-safe plugins/`. 3. Take a look at possible `TODO:` items the `codemod` could not fix. 4. Remove types & methods from `@backstage/theme` which are marked as `@deprecated`. +5. Ensure you are using `"react": "^17.0.0"` (or newer) as a peer dependency You can follow the [migration of the GraphiQL plugin](https://github.com/backstage/backstage/pull/17696) as an example plugin migration. From a647d24d257745a199bd32a7d4e8152a7d515263 Mon Sep 17 00:00:00 2001 From: Philipp Hugenroth Date: Fri, 17 Nov 2023 14:47:41 +0100 Subject: [PATCH 07/11] let's get this in... Signed-off-by: Philipp Hugenroth --- docs/tutorials/migrate-to-mui5.md | 42 ++++++++++++++++++++----------- 1 file changed, 27 insertions(+), 15 deletions(-) diff --git a/docs/tutorials/migrate-to-mui5.md b/docs/tutorials/migrate-to-mui5.md index 6f1036e4c2..cda662be7d 100644 --- a/docs/tutorials/migrate-to-mui5.md +++ b/docs/tutorials/migrate-to-mui5.md @@ -1,33 +1,45 @@ --- id: migrate-to-mui5 title: Migrating from Material UI v4 to v5 -description: Additionally resources to the Material UI migration guide specifically for Backstage +description: Additional resources for the Material UI v5 migration guide specifically for Backstage --- -Before diving into the specific changes in Backstage, it may be helpful to take a look at the [Migration Guide provided by MUI](https://mui.com/material-ui/migration/migration-v4/). It breaks down the differences between v4, v5 and will make it easier to understand the impact on your Backstage instance & plugins. +Backstage supports developing new plugins or components using Material UI v5. At the same time, large parts of the application as well as existing plugins will still be using Material UI v4. To support Material UI v4 and v5 at the same time, we have introduced a new concept called the `UnifiedTheme`. The goal of the `UnifiedTheme` is to allow gradual migration by running both versions in parallel, applying theme options similarly & supporting potential future versions of Material UI. -To support Material UI v5 in addition to v4, we have introduced a `UnifiedThemeProvider`. This allows a gradual migration by running both versions in parallel. To use it, you need to update your app's `ThemeProvider` in `app/src/App.tsx` as follows: +By default, the `UnifiedThemeProvider` is already used. If you add a custom theme in your `createApp` function, you would need to replace the Material UI `ThemeProvider` with the `UnifiedThemeProvider`: -```diff - provider: ({ children }) => ( -- . -- {children}. -- - ), +```diff ts +const app = createApp({ + // ... + themes: [ + { + // ... + provider: ({ children }) => ( +- . +- {children}. +- + ), + } + ] +}); ``` +Before making specific changes to your Backstage instance, it might be helpful to take a look at the [Migration Guide provided by Material UI](https://mui.com/material-ui/migration/migration-v4/) first. It breaks down the differences between v4 and v5, and will make it easier to understand the impact on your Backstage instance & plugins. + It is worth noting that we are still using `@mui/styles` & `jss`. You may stumble upon documentation for migrating to `emotion` when using `makeStyles` or `withStyles`. It is not necessary to switch to `emotion`. -To comply with MUI recommendations, we are enforcing a new linting rules that favours standard imports over named imports and also restricting 3rd level imports as they are considered private ([Guide: Minimizing Bundle Size](https://mui.com/material-ui/guides/minimizing-bundle-size)). +To comply with Material UI recommendations, we are enforcing a new linting rule that favors standard imports over named imports and also restricts 3rd-level imports as they are considered private ([Guide: Minimizing Bundle Size](https://mui.com/material-ui/guides/minimizing-bundle-size)). -Important to keep in mind is, that Material UI v5 is meant to be used with React Version 17 or higher. This means if you intend to use the Material UI v5 components in your plugins you have to enforce React Version to be at least 17. +Important to keep in mind is that Material UI v5 is meant to be used with React Version 17 or higher. This means if you intend to use the Material UI v5 components in your plugins, you have to enforce React Version to be at least 17 for these plugins as well. -For current known issues with the MUI v5 migration, follow our [Milestone on GitHub](https://github.com/backstage/backstage/milestone/40). Please open a new issue if you run into different problems. +There are `core-components` as well as components exported from `*-react` plugins written in Material UI v4, which expect Material UI components as props. In these cases you will still be forced to import Material UI v4 components. + +For current known issues with the Material UI v5 migration, follow our [Milestone on GitHub](https://github.com/backstage/backstage/milestone/40). Please open a new issue if you run into different problems. ### Plugins -To migrate your plugin to MUI v5, you can build on the resources available. +To migrate your plugin to Material UI v5, you can build on the resources available. 1. Manually fix the imports from named to default imports to match the new [linting rules for minimizing bundle size](https://mui.com/material-ui/guides/minimizing-bundle-size). 2. Run the migration `codemod` for the path of the specific plugin: `npx @mui/codemod v5.0.0/preset-safe plugins/`. @@ -35,4 +47,4 @@ To migrate your plugin to MUI v5, you can build on the resources available. 4. Remove types & methods from `@backstage/theme` which are marked as `@deprecated`. 5. Ensure you are using `"react": "^17.0.0"` (or newer) as a peer dependency -You can follow the [migration of the GraphiQL plugin](https://github.com/backstage/backstage/pull/17696) as an example plugin migration. +You can follow the [migration of the GraphiQL plugin](https://github.com/backstage/backstage/pull/17696) as an example of a plugin migration. From 07e668952d06679cad39a21fa782aea026cea581 Mon Sep 17 00:00:00 2001 From: Philipp Hugenroth Date: Mon, 20 Nov 2023 11:16:31 +0100 Subject: [PATCH 08/11] Add guide to sidebar Signed-off-by: Philipp Hugenroth --- mkdocs.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/mkdocs.yml b/mkdocs.yml index de66c97884..d4735c63fc 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -193,6 +193,7 @@ nav: - Switching Backstage from SQLite to PostgreSQL: 'tutorials/switching-sqlite-postgres.md' - Using the Backstage Proxy from Within a Plugin: 'tutorials/using-backstage-proxy-within-plugin.md' - Migration to Yarn 3: 'tutorials/yarn-migration.md' + - Migration to Material UI v5: 'tutorials/migrate-to-mui5.md' - Architecture Decision Records (ADRs): - Overview: 'architecture-decisions/index.md' - ADR001 - Architecture Decision Record (ADR) log: 'architecture-decisions/adr001-add-adr-log.md' From e75937670cef4b0ded7ea37533d8fa9f56e63f81 Mon Sep 17 00:00:00 2001 From: Philipp Hugenroth Date: Mon, 20 Nov 2023 15:30:32 +0100 Subject: [PATCH 09/11] always forget this one Signed-off-by: Philipp Hugenroth --- microsite/sidebars.json | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/microsite/sidebars.json b/microsite/sidebars.json index c9b1c99eba..c33bf37785 100644 --- a/microsite/sidebars.json +++ b/microsite/sidebars.json @@ -408,7 +408,8 @@ "tutorials/configuring-plugin-databases", "tutorials/switching-sqlite-postgres", "tutorials/using-backstage-proxy-within-plugin", - "tutorials/yarn-migration" + "tutorials/yarn-migration", + "tutorials/migrate-to-mui5.md" ], "Architecture Decision Records (ADRs)": [ "architecture-decisions/adrs-overview", From 2717528ddb12798915ee002a587ba59ee9977f8e Mon Sep 17 00:00:00 2001 From: Philipp Hugenroth Date: Thu, 23 Nov 2023 14:24:00 +0100 Subject: [PATCH 10/11] Update microsite/sidebars.json Co-authored-by: Camila Belo Signed-off-by: Philipp Hugenroth --- microsite/sidebars.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/microsite/sidebars.json b/microsite/sidebars.json index c33bf37785..fb513697cb 100644 --- a/microsite/sidebars.json +++ b/microsite/sidebars.json @@ -409,7 +409,7 @@ "tutorials/switching-sqlite-postgres", "tutorials/using-backstage-proxy-within-plugin", "tutorials/yarn-migration", - "tutorials/migrate-to-mui5.md" + "tutorials/migrate-to-mui5" ], "Architecture Decision Records (ADRs)": [ "architecture-decisions/adrs-overview", From d535229fe465adb267909469c92c4e45111f2739 Mon Sep 17 00:00:00 2001 From: Philipp Hugenroth Date: Mon, 27 Nov 2023 16:25:20 +0100 Subject: [PATCH 11/11] Improve code examples Signed-off-by: Philipp Hugenroth --- docs/tutorials/migrate-to-mui5.md | 49 ++++++++++++++++++++----------- 1 file changed, 32 insertions(+), 17 deletions(-) diff --git a/docs/tutorials/migrate-to-mui5.md b/docs/tutorials/migrate-to-mui5.md index cda662be7d..96129ceb8a 100644 --- a/docs/tutorials/migrate-to-mui5.md +++ b/docs/tutorials/migrate-to-mui5.md @@ -9,31 +9,46 @@ Backstage supports developing new plugins or components using Material UI v5. At By default, the `UnifiedThemeProvider` is already used. If you add a custom theme in your `createApp` function, you would need to replace the Material UI `ThemeProvider` with the `UnifiedThemeProvider`: ```diff ts -const app = createApp({ - // ... - themes: [ - { - // ... - provider: ({ children }) => ( -- . -- {children}. -- - ), - } - ] -}); ++ import import { ++ UnifiedThemeProvider, ++ themes as builtinThemes, ++ } from '@backstage/theme'; + + const app = createApp({ + // ... + themes: [ + { + // ... + provider: ({ children }) => ( +- . +- {children}. +- + ), + } + ] + }); ``` Before making specific changes to your Backstage instance, it might be helpful to take a look at the [Migration Guide provided by Material UI](https://mui.com/material-ui/migration/migration-v4/) first. It breaks down the differences between v4 and v5, and will make it easier to understand the impact on your Backstage instance & plugins. It is worth noting that we are still using `@mui/styles` & `jss`. You may stumble upon documentation for migrating to `emotion` when using `makeStyles` or `withStyles`. It is not necessary to switch to `emotion`. +Important to keep in mind is that Material UI v5 is meant to be used with React Version 17 or higher. This means if you intend to use the Material UI v5 components in your plugins, you have to enforce React Version to be at least 17 for these plugins: + +```json +... + "peerDependencies": { + "react": "^17.0.0 || ^18.0.0", + "react-dom": "^17.0.0 || ^18.0.0", + "react-router-dom": "6.0.0-beta.0 || ^6.3.0" + }, +... +``` + To comply with Material UI recommendations, we are enforcing a new linting rule that favors standard imports over named imports and also restricts 3rd-level imports as they are considered private ([Guide: Minimizing Bundle Size](https://mui.com/material-ui/guides/minimizing-bundle-size)). -Important to keep in mind is that Material UI v5 is meant to be used with React Version 17 or higher. This means if you intend to use the Material UI v5 components in your plugins, you have to enforce React Version to be at least 17 for these plugins as well. - -There are `core-components` as well as components exported from `*-react` plugins written in Material UI v4, which expect Material UI components as props. In these cases you will still be forced to import Material UI v4 components. +There are `core-components` as well as components exported from Backstage `*-react` plugins written in Material UI v4, which expect Material UI components as props. In these cases you will still be forced to use Material UI v4. For current known issues with the Material UI v5 migration, follow our [Milestone on GitHub](https://github.com/backstage/backstage/milestone/40). Please open a new issue if you run into different problems.