Skip to content

Commit 12be867

Browse files
docs: add known issues doc with some workarounds (#2331)
* docs: add known issues doc with some workarounds Signed-off-by: Christoph Jerolimov <[email protected]> * docs: update or remove outdated links Signed-off-by: Christoph Jerolimov <[email protected]> --------- Signed-off-by: Christoph Jerolimov <[email protected]> Co-authored-by: Tomas Kral <[email protected]>
1 parent 1a25be7 commit 12be867

File tree

4 files changed

+63
-2
lines changed

4 files changed

+63
-2
lines changed

docs/dynamic-plugins/export-derived-package.md

+2
Original file line numberDiff line numberDiff line change
@@ -43,8 +43,10 @@ If you are developing your own plugin that is going to be used as a dynamic plug
4343
To be compatible with the showcase dynamic plugin support, and used as dynamic plugins, existing plugins must be based on, or compatible with, the new backend system, as well as rebuilt with a dedicated CLI command.
4444

4545
The new backend system standard entry point (created using `createBackendPlugin()` or `createBackendModule()`) should be exported as the default export of either the main package or of an `alpha` package (if the new backend support is still provided as `alpha` APIs). This doesn't add any additional requirement on top of the standard plugin development guidelines of the new backend system.
46+
4647
For a practical example of a dynamic plugin entry point built upon the new backend system, please refer to the [Backstage community plugins repository](https://github.com/backstage/community-plugins/blob/main/workspaces/3scale/plugins/3scale-backend/src/module.ts).
4748

49+
4850
The dynamic export mechanism identifies private, non-backstage dependencies, and sets the `bundleDependencies` field in the `package.json` file for them, so that the dynamic plugin package can be published as a self-contained package, along with its private dependencies bundled in a private `node_modules` folder.
4951

5052
### Shared dependencies

docs/dynamic-plugins/known-issues.md

+59
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# Known Issues
2+
3+
## MUI Version 5 releated issues
4+
5+
### Styles are missing
6+
7+
When your plugin uses MUI v5 and is loaded as a dynamic plugin, it will miss some of the default CSS declations from MUI and Backstage/RHDH.
8+
9+
**Workaround:**
10+
11+
Add the following source code to your `<plugin>/src/index.ts` before your plugin is exported:
12+
13+
```tsx
14+
import { unstable_ClassNameGenerator as ClassNameGenerator } from '@mui/material/className';
15+
16+
ClassNameGenerator.configure(componentName => {
17+
return componentName.startsWith('v5-')
18+
? componentName
19+
: `v5-${componentName}`;
20+
});
21+
22+
export * from './plugin';
23+
```
24+
25+
**Alternatives:**
26+
27+
* Use Backstage Core Components or Material UI v4 components from `@material-ui/core/*`.
28+
29+
**Related issues:**
30+
31+
* [RHIDP-5170 - Dynamic plugin loaded plugins that uses MUI v5 looks different then static loaded plugins](https://issues.redhat.com/browse/RHIDP-5170)
32+
* [RHIDP-5847 - Narrow the accepted versions in the scalprum webpack federated module configuration](https://issues.redhat.com/browse/RHIDP-5847)
33+
34+
### Grid cards/component misses the default spacing from Backstage
35+
36+
When your plugin is using the Grid component from `@mui/material/Grid` the default spacing from the Backstage/RHDH theme is missing.
37+
38+
**Workaround:**
39+
40+
Manually apply the prop `spacing={2}` to the `Grid container`s:
41+
42+
```tsx
43+
<Grid container spacing={2} ...>
44+
<Grid item ...>
45+
...
46+
</Grid>
47+
<Grid item ...>
48+
...
49+
</Grid>
50+
</Grid>
51+
```
52+
53+
**Alternatives:**
54+
55+
* Use Material UI v4 Grid from `@material-ui/core/Grid`.
56+
57+
**Related issues:**
58+
59+
* [RHIDP-5170 - Dynamic plugin loaded plugins that uses MUI v5 looks different then static loaded plugins](https://issues.redhat.com/browse/RHIDP-5170)

docs/index.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ The telemetry data collection feature is used to enhance your experience with th
88

99
**Telemetry data collection is enabled by default.**
1010

11-
To disable telemetry data collection, you need to disable the [`@janus-idp/backstage-plugin-analytics-provider-segment`](https://github.com/janus-idp/backstage-plugins/tree/main/plugins/analytics-provider-segment) plugin as documented below.
11+
To disable telemetry data collection, you need to disable the [`@backstage-community/plugin-analytics-provider-segment`](https://github.com/backstage/community-plugins/tree/main/workspaces/analytics/plugins/analytics-provider-segment) plugin as documented below.
1212

1313
- **Anonymous configuration**:
1414

packages/app/CHANGELOG.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -164,7 +164,7 @@
164164
generator:
165165
```
166166

167-
- cb6c541: The [Jfrog Artifactory plugin](https://github.com/janus-idp/backstage-plugins/tree/main/plugins/jfrog-artifactory) has been added with the `JfrogArtifactoryPage` in the Entity Page image registry tab.
167+
- cb6c541: The [Jfrog Artifactory plugin](https://github.com/backstage/community-plugins/tree/main/workspaces/jfrog-artifactory/plugins/jfrog-artifactory) has been added with the `JfrogArtifactoryPage` in the Entity Page image registry tab.
168168

169169
These changes are **required** to `app-config.yaml` if you want to add the JFrog Artifactory plugin. Please read the [README](https://github.com/redhat-developer/rhdh/blob/main/README.md) and [Getting Started](https://github.com/redhat-developer/rhdh/blob/main/showcase-docs/getting-started.md) for more details.
170170

0 commit comments

Comments
 (0)