From 9dc1bd53d32a8e8f05471c8ef6bee51807bbf78f Mon Sep 17 00:00:00 2001 From: Rajib Quayum Date: Fri, 27 Feb 2026 12:32:54 -0500 Subject: [PATCH 01/14] fix: move MUI 5 class name setup to own file with new entry point in package, update various index files to import class name setup as the first thing Signed-off-by: Rajib Quayum --- packages/app-legacy/src/index.tsx | 1 + packages/app/src/index.tsx | 1 + .../default-app/packages/app/src/index.tsx | 1 + .../next-app/packages/app/src/index.tsx | 1 + packages/theme/package.json | 9 ++++- .../theme/src/unified/MuiClassNameSetup.ts | 40 +++++++++++++++++++ .../src/unified/UnifiedThemeProvider.tsx | 11 +---- packages/theme/src/unified/index.ts | 1 + 8 files changed, 54 insertions(+), 11 deletions(-) create mode 100644 packages/theme/src/unified/MuiClassNameSetup.ts diff --git a/packages/app-legacy/src/index.tsx b/packages/app-legacy/src/index.tsx index 05dcc024bf..d7699e3d9d 100644 --- a/packages/app-legacy/src/index.tsx +++ b/packages/app-legacy/src/index.tsx @@ -14,6 +14,7 @@ * limitations under the License. */ +import '@backstage/theme/MuiClassNameSetup'; import '@backstage/cli/asset-types'; import ReactDOM from 'react-dom/client'; import App from './App'; diff --git a/packages/app/src/index.tsx b/packages/app/src/index.tsx index fd86261385..873670de0f 100644 --- a/packages/app/src/index.tsx +++ b/packages/app/src/index.tsx @@ -14,6 +14,7 @@ * limitations under the License. */ +import '@backstage/theme/MuiClassNameSetup'; import '@backstage/cli/asset-types'; import ReactDOM from 'react-dom/client'; import app from './App'; diff --git a/packages/create-app/templates/default-app/packages/app/src/index.tsx b/packages/create-app/templates/default-app/packages/app/src/index.tsx index 46f31902f4..3cc56c886c 100644 --- a/packages/create-app/templates/default-app/packages/app/src/index.tsx +++ b/packages/create-app/templates/default-app/packages/app/src/index.tsx @@ -1,3 +1,4 @@ +import '@backstage/theme/MuiClassNameSetup'; import '@backstage/cli/asset-types'; import ReactDOM from 'react-dom/client'; import App from './App'; diff --git a/packages/create-app/templates/next-app/packages/app/src/index.tsx b/packages/create-app/templates/next-app/packages/app/src/index.tsx index ac9e52bdc1..6936ff50bc 100644 --- a/packages/create-app/templates/next-app/packages/app/src/index.tsx +++ b/packages/create-app/templates/next-app/packages/app/src/index.tsx @@ -1,3 +1,4 @@ +import '@backstage/theme/MuiClassNameSetup'; import '@backstage/cli/asset-types'; import ReactDOM from 'react-dom/client'; import App from './App'; diff --git a/packages/theme/package.json b/packages/theme/package.json index e95ae20b36..f27fc9e385 100644 --- a/packages/theme/package.json +++ b/packages/theme/package.json @@ -20,7 +20,14 @@ "directory": "packages/theme" }, "license": "Apache-2.0", - "sideEffects": false, + "sideEffects": [ + "./src/unified/MuiClassNameSetup.ts" + ], + "exports": { + ".": "./src/index.ts", + "./MuiClassNameSetup": "./src/unified/MuiClassNameSetup.ts", + "./package.json": "./package.json" + }, "main": "src/index.ts", "types": "src/index.ts", "files": [ diff --git a/packages/theme/src/unified/MuiClassNameSetup.ts b/packages/theme/src/unified/MuiClassNameSetup.ts new file mode 100644 index 0000000000..1c1b854211 --- /dev/null +++ b/packages/theme/src/unified/MuiClassNameSetup.ts @@ -0,0 +1,40 @@ +/* + * Copyright 2026 The Backstage Authors + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +import { unstable_ClassNameGenerator as ClassNameGenerator } from '@mui/material/className'; + +/** + * This API is introduced in @mui/material (v5.0.5) as a replacement of deprecated createGenerateClassName & only affects v5 Material UI components from `@mui/*`. + * + * This needs to be configured before any MUI 5 component can possibly be imported. See: https://v5.mui.com/material-ui/experimental-api/classname-generator/#caveat + * + * ```packages/app/index.ts + * + * import '@backstage/theme/MuiClassNameSetup'; // must be the very first import! + * import '@backstage/cli/asset-types'; + * import ReactDOM from 'react-dom/client'; + * import app from './App'; + * import '@backstage/ui/css/styles.css'; + * + * ReactDOM.createRoot(document.getElementById('root')!).render(app); + * ``` + */ +ClassNameGenerator.configure(componentName => { + return componentName.startsWith('v5-') + ? componentName + : `v5-${componentName}`; +}); + +export {}; diff --git a/packages/theme/src/unified/UnifiedThemeProvider.tsx b/packages/theme/src/unified/UnifiedThemeProvider.tsx index 69d843ed3e..b93746dad4 100644 --- a/packages/theme/src/unified/UnifiedThemeProvider.tsx +++ b/packages/theme/src/unified/UnifiedThemeProvider.tsx @@ -27,7 +27,7 @@ import { Theme as Mui5Theme, } from '@mui/material/styles'; import { UnifiedTheme } from './types'; -import { unstable_ClassNameGenerator as ClassNameGenerator } from '@mui/material/className'; +import './MuiClassNameSetup'; /** * Props for {@link UnifiedThemeProvider}. @@ -41,15 +41,6 @@ export interface UnifiedThemeProviderProps { themeName?: string; } -/** - * This API is introduced in @mui/material (v5.0.5) as a replacement of deprecated createGenerateClassName & only affects v5 Material UI components from `@mui/*`. - * - * This call needs to be in the same module as the `UnifiedThemeProvider` to ensure that it doesn't get removed by tree shaking - */ -ClassNameGenerator.configure(componentName => { - return `v5-${componentName}`; -}); - // Background at https://mui.com/x/migration/migration-data-grid-v4/#using-mui-core-v4-with-v5 // Rather than disabling globals and custom seed, we instead only set a production prefix that // won't collide with Material UI 5 styles. We've already got the separate class name generator diff --git a/packages/theme/src/unified/index.ts b/packages/theme/src/unified/index.ts index 747662e195..2428902981 100644 --- a/packages/theme/src/unified/index.ts +++ b/packages/theme/src/unified/index.ts @@ -21,3 +21,4 @@ export { themes } from './themes'; export { UnifiedThemeProvider } from './UnifiedThemeProvider'; export type { UnifiedThemeProviderProps } from './UnifiedThemeProvider'; export type { UnifiedTheme, SupportedThemes, SupportedVersions } from './types'; +export * from './MuiClassNameSetup'; From 83856ffe55a2b936e286ed11f3042e44f288ee64 Mon Sep 17 00:00:00 2001 From: Rajib Quayum Date: Fri, 27 Feb 2026 12:45:57 -0500 Subject: [PATCH 02/14] chore: add changeset Signed-off-by: Rajib Quayum --- .changeset/vast-jeans-boil.md | 24 +++++++++++++++++++ .../theme/src/unified/MuiClassNameSetup.ts | 5 ++-- 2 files changed, 27 insertions(+), 2 deletions(-) create mode 100644 .changeset/vast-jeans-boil.md diff --git a/.changeset/vast-jeans-boil.md b/.changeset/vast-jeans-boil.md new file mode 100644 index 0000000000..86f63b2a6d --- /dev/null +++ b/.changeset/vast-jeans-boil.md @@ -0,0 +1,24 @@ +--- +'example-app-legacy': minor +'@backstage/create-app': minor +'@backstage/theme': minor +'example-app': minor +--- + +Separates MUI 5 class name generator code into separate file and entry point that can be imported before any MUI 5 component loads. + +This addresses the problem where the elements contain the `v5-` prefix for MUI class names, but the static class names from the library do not. + +Import should be made as follows to ensure the prefix problem is addressed correctly: + +```diff +// packages/app/index.ts + ++ import '@backstage/theme/MuiClassNameSetup'; // must be the very first import! +import '@backstage/cli/asset-types'; +import ReactDOM from 'react-dom/client'; +import app from './App'; +import '@backstage/ui/css/styles.css'; + +ReactDOM.createRoot(document.getElementById('root')!).render(app); +``` diff --git a/packages/theme/src/unified/MuiClassNameSetup.ts b/packages/theme/src/unified/MuiClassNameSetup.ts index 1c1b854211..5d9fcbd93d 100644 --- a/packages/theme/src/unified/MuiClassNameSetup.ts +++ b/packages/theme/src/unified/MuiClassNameSetup.ts @@ -20,9 +20,10 @@ import { unstable_ClassNameGenerator as ClassNameGenerator } from '@mui/material * * This needs to be configured before any MUI 5 component can possibly be imported. See: https://v5.mui.com/material-ui/experimental-api/classname-generator/#caveat * - * ```packages/app/index.ts + * ```diff + * // packages/app/index.ts * - * import '@backstage/theme/MuiClassNameSetup'; // must be the very first import! + * + import '@backstage/theme/MuiClassNameSetup'; // must be the very first import! * import '@backstage/cli/asset-types'; * import ReactDOM from 'react-dom/client'; * import app from './App'; From f738d47c357f7df52d8688254e5498f549004d46 Mon Sep 17 00:00:00 2001 From: Rajib Quayum Date: Fri, 27 Feb 2026 12:50:04 -0500 Subject: [PATCH 03/14] chore: add api report file for MuiClassNameSetup Signed-off-by: Rajib Quayum --- packages/theme/report-MuiClassNameSetup.api.md | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 packages/theme/report-MuiClassNameSetup.api.md diff --git a/packages/theme/report-MuiClassNameSetup.api.md b/packages/theme/report-MuiClassNameSetup.api.md new file mode 100644 index 0000000000..c05c3c72a8 --- /dev/null +++ b/packages/theme/report-MuiClassNameSetup.api.md @@ -0,0 +1,7 @@ +## API Report File for "@backstage/theme" + +> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/). + +```ts +// (No @packageDocumentation comment for this package) +``` From 8ac301afc1b0855ece294b6631d3a166b3d46513 Mon Sep 17 00:00:00 2001 From: Rajib Quayum Date: Fri, 27 Feb 2026 13:01:58 -0500 Subject: [PATCH 04/14] chore: fix index.ts path Signed-off-by: Rajib Quayum --- .changeset/vast-jeans-boil.md | 2 +- packages/theme/src/unified/MuiClassNameSetup.ts | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.changeset/vast-jeans-boil.md b/.changeset/vast-jeans-boil.md index 86f63b2a6d..9eb9ed235b 100644 --- a/.changeset/vast-jeans-boil.md +++ b/.changeset/vast-jeans-boil.md @@ -12,7 +12,7 @@ This addresses the problem where the elements contain the `v5-` prefix for MUI c Import should be made as follows to ensure the prefix problem is addressed correctly: ```diff -// packages/app/index.ts +// packages/app/src/index.ts + import '@backstage/theme/MuiClassNameSetup'; // must be the very first import! import '@backstage/cli/asset-types'; diff --git a/packages/theme/src/unified/MuiClassNameSetup.ts b/packages/theme/src/unified/MuiClassNameSetup.ts index 5d9fcbd93d..9511376f5a 100644 --- a/packages/theme/src/unified/MuiClassNameSetup.ts +++ b/packages/theme/src/unified/MuiClassNameSetup.ts @@ -21,7 +21,7 @@ import { unstable_ClassNameGenerator as ClassNameGenerator } from '@mui/material * This needs to be configured before any MUI 5 component can possibly be imported. See: https://v5.mui.com/material-ui/experimental-api/classname-generator/#caveat * * ```diff - * // packages/app/index.ts + * // packages/app/src/index.ts * * + import '@backstage/theme/MuiClassNameSetup'; // must be the very first import! * import '@backstage/cli/asset-types'; From bac85bb5a8da5e4351982f2978a12ae20db02260 Mon Sep 17 00:00:00 2001 From: Rajib Quayum Date: Fri, 27 Feb 2026 13:10:23 -0500 Subject: [PATCH 05/14] chore: update changeset to remove unnecessary ones Signed-off-by: Rajib Quayum --- .changeset/vast-jeans-boil.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/.changeset/vast-jeans-boil.md b/.changeset/vast-jeans-boil.md index 9eb9ed235b..74b2c481b4 100644 --- a/.changeset/vast-jeans-boil.md +++ b/.changeset/vast-jeans-boil.md @@ -1,8 +1,6 @@ --- -'example-app-legacy': minor '@backstage/create-app': minor '@backstage/theme': minor -'example-app': minor --- Separates MUI 5 class name generator code into separate file and entry point that can be imported before any MUI 5 component loads. From 91f86f80b62905a3166ee238565cc4d1cdd1e9bb Mon Sep 17 00:00:00 2001 From: Rajib Quayum Date: Fri, 27 Feb 2026 13:33:08 -0500 Subject: [PATCH 06/14] fix: repo fix Signed-off-by: Rajib Quayum --- packages/theme/package.json | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/packages/theme/package.json b/packages/theme/package.json index f27fc9e385..a23c87c13d 100644 --- a/packages/theme/package.json +++ b/packages/theme/package.json @@ -6,9 +6,7 @@ "role": "web-library" }, "publishConfig": { - "access": "public", - "main": "dist/index.esm.js", - "types": "dist/index.d.ts" + "access": "public" }, "keywords": [ "backstage" @@ -28,6 +26,16 @@ "./MuiClassNameSetup": "./src/unified/MuiClassNameSetup.ts", "./package.json": "./package.json" }, + "typesVersions": { + "*": { + "MuiClassNameSetup": [ + "src/unified/MuiClassNameSetup.ts" + ], + "package.json": [ + "package.json" + ] + } + }, "main": "src/index.ts", "types": "src/index.ts", "files": [ From 15279864d68dbd272cdc56d7f371c59056db5194 Mon Sep 17 00:00:00 2001 From: Rajib Quayum Date: Mon, 2 Mar 2026 09:57:19 -0500 Subject: [PATCH 07/14] chore: remove unnecessary export, reorder import in UnififedThemeProvider Signed-off-by: Rajib Quayum --- packages/theme/src/unified/UnifiedThemeProvider.tsx | 2 +- packages/theme/src/unified/index.ts | 1 - 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/packages/theme/src/unified/UnifiedThemeProvider.tsx b/packages/theme/src/unified/UnifiedThemeProvider.tsx index b93746dad4..678be82209 100644 --- a/packages/theme/src/unified/UnifiedThemeProvider.tsx +++ b/packages/theme/src/unified/UnifiedThemeProvider.tsx @@ -14,6 +14,7 @@ * limitations under the License. */ +import './MuiClassNameSetup'; import { ReactNode } from 'react'; import { ThemeProvider, @@ -27,7 +28,6 @@ import { Theme as Mui5Theme, } from '@mui/material/styles'; import { UnifiedTheme } from './types'; -import './MuiClassNameSetup'; /** * Props for {@link UnifiedThemeProvider}. diff --git a/packages/theme/src/unified/index.ts b/packages/theme/src/unified/index.ts index 2428902981..747662e195 100644 --- a/packages/theme/src/unified/index.ts +++ b/packages/theme/src/unified/index.ts @@ -21,4 +21,3 @@ export { themes } from './themes'; export { UnifiedThemeProvider } from './UnifiedThemeProvider'; export type { UnifiedThemeProviderProps } from './UnifiedThemeProvider'; export type { UnifiedTheme, SupportedThemes, SupportedVersions } from './types'; -export * from './MuiClassNameSetup'; From 39557edd70b1667a3fcd825789ae9169a5af9d06 Mon Sep 17 00:00:00 2001 From: Rajib Quayum Date: Mon, 2 Mar 2026 10:01:02 -0500 Subject: [PATCH 08/14] chore: update sideEffects Signed-off-by: Rajib Quayum --- packages/theme/package.json | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/packages/theme/package.json b/packages/theme/package.json index a23c87c13d..fe272bcf1c 100644 --- a/packages/theme/package.json +++ b/packages/theme/package.json @@ -19,7 +19,8 @@ }, "license": "Apache-2.0", "sideEffects": [ - "./src/unified/MuiClassNameSetup.ts" + "./src/unified/MuiClassNameSetup.ts", + "./dist/MuiClassNameSetup.*" ], "exports": { ".": "./src/index.ts", From beb8eda6a3eb39107a4b0e63ce5057ab73ef54ae Mon Sep 17 00:00:00 2001 From: Rajib Quayum Date: Mon, 2 Mar 2026 10:01:28 -0500 Subject: [PATCH 09/14] chore: fix references to index.tsx in docs Signed-off-by: Rajib Quayum --- .changeset/vast-jeans-boil.md | 2 +- packages/theme/src/unified/MuiClassNameSetup.ts | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.changeset/vast-jeans-boil.md b/.changeset/vast-jeans-boil.md index 74b2c481b4..7fbc49cdfa 100644 --- a/.changeset/vast-jeans-boil.md +++ b/.changeset/vast-jeans-boil.md @@ -10,7 +10,7 @@ This addresses the problem where the elements contain the `v5-` prefix for MUI c Import should be made as follows to ensure the prefix problem is addressed correctly: ```diff -// packages/app/src/index.ts +// packages/app/src/index.tsx + import '@backstage/theme/MuiClassNameSetup'; // must be the very first import! import '@backstage/cli/asset-types'; diff --git a/packages/theme/src/unified/MuiClassNameSetup.ts b/packages/theme/src/unified/MuiClassNameSetup.ts index 9511376f5a..b069394838 100644 --- a/packages/theme/src/unified/MuiClassNameSetup.ts +++ b/packages/theme/src/unified/MuiClassNameSetup.ts @@ -21,7 +21,7 @@ import { unstable_ClassNameGenerator as ClassNameGenerator } from '@mui/material * This needs to be configured before any MUI 5 component can possibly be imported. See: https://v5.mui.com/material-ui/experimental-api/classname-generator/#caveat * * ```diff - * // packages/app/src/index.ts + * // packages/app/src/index.tsx * * + import '@backstage/theme/MuiClassNameSetup'; // must be the very first import! * import '@backstage/cli/asset-types'; From a4dc401ac3f340de7ebc2b036c34785d1a2049d4 Mon Sep 17 00:00:00 2001 From: Rajib Quayum Date: Fri, 3 Apr 2026 09:04:59 -0400 Subject: [PATCH 10/14] chore: revert all previous changes Signed-off-by: Rajib Quayum --- .changeset/vast-jeans-boil.md | 22 ---------- packages/app-legacy/src/index.tsx | 1 - packages/app/src/index.tsx | 1 - .../default-app/packages/app/src/index.tsx | 1 - .../next-app/packages/app/src/index.tsx | 1 - packages/theme/package.json | 24 ++--------- .../theme/report-MuiClassNameSetup.api.md | 7 ---- .../theme/src/unified/MuiClassNameSetup.ts | 41 ------------------- .../src/unified/UnifiedThemeProvider.tsx | 11 ++++- 9 files changed, 14 insertions(+), 95 deletions(-) delete mode 100644 .changeset/vast-jeans-boil.md delete mode 100644 packages/theme/report-MuiClassNameSetup.api.md delete mode 100644 packages/theme/src/unified/MuiClassNameSetup.ts diff --git a/.changeset/vast-jeans-boil.md b/.changeset/vast-jeans-boil.md deleted file mode 100644 index 7fbc49cdfa..0000000000 --- a/.changeset/vast-jeans-boil.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -'@backstage/create-app': minor -'@backstage/theme': minor ---- - -Separates MUI 5 class name generator code into separate file and entry point that can be imported before any MUI 5 component loads. - -This addresses the problem where the elements contain the `v5-` prefix for MUI class names, but the static class names from the library do not. - -Import should be made as follows to ensure the prefix problem is addressed correctly: - -```diff -// packages/app/src/index.tsx - -+ import '@backstage/theme/MuiClassNameSetup'; // must be the very first import! -import '@backstage/cli/asset-types'; -import ReactDOM from 'react-dom/client'; -import app from './App'; -import '@backstage/ui/css/styles.css'; - -ReactDOM.createRoot(document.getElementById('root')!).render(app); -``` diff --git a/packages/app-legacy/src/index.tsx b/packages/app-legacy/src/index.tsx index d7699e3d9d..05dcc024bf 100644 --- a/packages/app-legacy/src/index.tsx +++ b/packages/app-legacy/src/index.tsx @@ -14,7 +14,6 @@ * limitations under the License. */ -import '@backstage/theme/MuiClassNameSetup'; import '@backstage/cli/asset-types'; import ReactDOM from 'react-dom/client'; import App from './App'; diff --git a/packages/app/src/index.tsx b/packages/app/src/index.tsx index 873670de0f..fd86261385 100644 --- a/packages/app/src/index.tsx +++ b/packages/app/src/index.tsx @@ -14,7 +14,6 @@ * limitations under the License. */ -import '@backstage/theme/MuiClassNameSetup'; import '@backstage/cli/asset-types'; import ReactDOM from 'react-dom/client'; import app from './App'; diff --git a/packages/create-app/templates/default-app/packages/app/src/index.tsx b/packages/create-app/templates/default-app/packages/app/src/index.tsx index 3cc56c886c..46f31902f4 100644 --- a/packages/create-app/templates/default-app/packages/app/src/index.tsx +++ b/packages/create-app/templates/default-app/packages/app/src/index.tsx @@ -1,4 +1,3 @@ -import '@backstage/theme/MuiClassNameSetup'; import '@backstage/cli/asset-types'; import ReactDOM from 'react-dom/client'; import App from './App'; diff --git a/packages/create-app/templates/next-app/packages/app/src/index.tsx b/packages/create-app/templates/next-app/packages/app/src/index.tsx index 6936ff50bc..ac9e52bdc1 100644 --- a/packages/create-app/templates/next-app/packages/app/src/index.tsx +++ b/packages/create-app/templates/next-app/packages/app/src/index.tsx @@ -1,4 +1,3 @@ -import '@backstage/theme/MuiClassNameSetup'; import '@backstage/cli/asset-types'; import ReactDOM from 'react-dom/client'; import App from './App'; diff --git a/packages/theme/package.json b/packages/theme/package.json index fe272bcf1c..e95ae20b36 100644 --- a/packages/theme/package.json +++ b/packages/theme/package.json @@ -6,7 +6,9 @@ "role": "web-library" }, "publishConfig": { - "access": "public" + "access": "public", + "main": "dist/index.esm.js", + "types": "dist/index.d.ts" }, "keywords": [ "backstage" @@ -18,25 +20,7 @@ "directory": "packages/theme" }, "license": "Apache-2.0", - "sideEffects": [ - "./src/unified/MuiClassNameSetup.ts", - "./dist/MuiClassNameSetup.*" - ], - "exports": { - ".": "./src/index.ts", - "./MuiClassNameSetup": "./src/unified/MuiClassNameSetup.ts", - "./package.json": "./package.json" - }, - "typesVersions": { - "*": { - "MuiClassNameSetup": [ - "src/unified/MuiClassNameSetup.ts" - ], - "package.json": [ - "package.json" - ] - } - }, + "sideEffects": false, "main": "src/index.ts", "types": "src/index.ts", "files": [ diff --git a/packages/theme/report-MuiClassNameSetup.api.md b/packages/theme/report-MuiClassNameSetup.api.md deleted file mode 100644 index c05c3c72a8..0000000000 --- a/packages/theme/report-MuiClassNameSetup.api.md +++ /dev/null @@ -1,7 +0,0 @@ -## API Report File for "@backstage/theme" - -> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/). - -```ts -// (No @packageDocumentation comment for this package) -``` diff --git a/packages/theme/src/unified/MuiClassNameSetup.ts b/packages/theme/src/unified/MuiClassNameSetup.ts deleted file mode 100644 index b069394838..0000000000 --- a/packages/theme/src/unified/MuiClassNameSetup.ts +++ /dev/null @@ -1,41 +0,0 @@ -/* - * Copyright 2026 The Backstage Authors - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ -import { unstable_ClassNameGenerator as ClassNameGenerator } from '@mui/material/className'; - -/** - * This API is introduced in @mui/material (v5.0.5) as a replacement of deprecated createGenerateClassName & only affects v5 Material UI components from `@mui/*`. - * - * This needs to be configured before any MUI 5 component can possibly be imported. See: https://v5.mui.com/material-ui/experimental-api/classname-generator/#caveat - * - * ```diff - * // packages/app/src/index.tsx - * - * + import '@backstage/theme/MuiClassNameSetup'; // must be the very first import! - * import '@backstage/cli/asset-types'; - * import ReactDOM from 'react-dom/client'; - * import app from './App'; - * import '@backstage/ui/css/styles.css'; - * - * ReactDOM.createRoot(document.getElementById('root')!).render(app); - * ``` - */ -ClassNameGenerator.configure(componentName => { - return componentName.startsWith('v5-') - ? componentName - : `v5-${componentName}`; -}); - -export {}; diff --git a/packages/theme/src/unified/UnifiedThemeProvider.tsx b/packages/theme/src/unified/UnifiedThemeProvider.tsx index 678be82209..69d843ed3e 100644 --- a/packages/theme/src/unified/UnifiedThemeProvider.tsx +++ b/packages/theme/src/unified/UnifiedThemeProvider.tsx @@ -14,7 +14,6 @@ * limitations under the License. */ -import './MuiClassNameSetup'; import { ReactNode } from 'react'; import { ThemeProvider, @@ -28,6 +27,7 @@ import { Theme as Mui5Theme, } from '@mui/material/styles'; import { UnifiedTheme } from './types'; +import { unstable_ClassNameGenerator as ClassNameGenerator } from '@mui/material/className'; /** * Props for {@link UnifiedThemeProvider}. @@ -41,6 +41,15 @@ export interface UnifiedThemeProviderProps { themeName?: string; } +/** + * This API is introduced in @mui/material (v5.0.5) as a replacement of deprecated createGenerateClassName & only affects v5 Material UI components from `@mui/*`. + * + * This call needs to be in the same module as the `UnifiedThemeProvider` to ensure that it doesn't get removed by tree shaking + */ +ClassNameGenerator.configure(componentName => { + return `v5-${componentName}`; +}); + // Background at https://mui.com/x/migration/migration-data-grid-v4/#using-mui-core-v4-with-v5 // Rather than disabling globals and custom seed, we instead only set a production prefix that // won't collide with Material UI 5 styles. We've already got the separate class name generator From 2c541a782be76d41c6dde057257c0ab15d58a104 Mon Sep 17 00:00:00 2001 From: Rajib Quayum Date: Fri, 3 Apr 2026 09:29:06 -0400 Subject: [PATCH 11/14] fix: prevent occasional duplication of the MUI v5 prefix Signed-off-by: Rajib Quayum --- packages/theme/src/unified/UnifiedThemeProvider.tsx | 3 +++ 1 file changed, 3 insertions(+) diff --git a/packages/theme/src/unified/UnifiedThemeProvider.tsx b/packages/theme/src/unified/UnifiedThemeProvider.tsx index 69d843ed3e..f10320393d 100644 --- a/packages/theme/src/unified/UnifiedThemeProvider.tsx +++ b/packages/theme/src/unified/UnifiedThemeProvider.tsx @@ -47,6 +47,9 @@ export interface UnifiedThemeProviderProps { * This call needs to be in the same module as the `UnifiedThemeProvider` to ensure that it doesn't get removed by tree shaking */ ClassNameGenerator.configure(componentName => { + if ((componentName ?? '').startsWith('v5-')) { + return componentName; + } return `v5-${componentName}`; }); From e22fc0af9c7fc094cdc3797d7df7927d8118ce37 Mon Sep 17 00:00:00 2001 From: Rajib Quayum Date: Fri, 3 Apr 2026 10:01:25 -0400 Subject: [PATCH 12/14] chore: update docs for MUI v5 class name prefix issue Signed-off-by: Rajib Quayum --- docs/conf/user-interface/index.md | 50 +++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) diff --git a/docs/conf/user-interface/index.md b/docs/conf/user-interface/index.md index 107fde3d57..b9eda5151c 100644 --- a/docs/conf/user-interface/index.md +++ b/docs/conf/user-interface/index.md @@ -634,3 +634,53 @@ export const myTheme = createUnifiedTheme({ ``` + +
+ Missing v5 prefix for MUI 5 class names + +If you are using MUI 5 components in the main app, you may notice that the rendered elements have a `v5-` prefix in front of the MUI class names, but not when you try to use the class name props in code. + +Example: + +```html +