From 9d8f3456f1751aabf827ddf2592206c424bbe5af Mon Sep 17 00:00:00 2001 From: Vojtech Szocs Date: Mon, 26 Feb 2024 19:21:34 +0000 Subject: [PATCH] Improve dynamic plugin docs --- .../console-dynamic-plugin-sdk/README.md | 30 ++++++++++- .../scripts/package-definitions.ts | 9 +++- .../upgrade-PatternFly.md | 51 +++++++++++++++++++ 3 files changed, 87 insertions(+), 3 deletions(-) create mode 100644 frontend/packages/console-dynamic-plugin-sdk/upgrade-PatternFly.md diff --git a/frontend/packages/console-dynamic-plugin-sdk/README.md b/frontend/packages/console-dynamic-plugin-sdk/README.md index 410b2d04b755..1fbe58396e7f 100644 --- a/frontend/packages/console-dynamic-plugin-sdk/README.md +++ b/frontend/packages/console-dynamic-plugin-sdk/README.md @@ -63,7 +63,7 @@ Note: this table includes Console versions which currently receive technical sup ## OpenShift Console Versions vs PatternFly Versions -Each Console version supports specific versions of [PatternFly](https://www.patternfly.org/) in terms +Each Console version supports specific version(s) of [PatternFly](https://www.patternfly.org/) in terms of CSS styling. This table will help align compatible versions of PatternFly to versions of the OpenShift Console. @@ -75,6 +75,8 @@ Console. | 4.13.x | 4.x | | | 4.12.x | 4.x | | +Refer to [PatternFly Upgrade Notes](./upgrade-PatternFly.md) containing links to PatternFly documentation. + ## Shared modules Console is [configured](./src/shared-modules.ts) to share specific modules with its dynamic plugins. @@ -266,6 +268,32 @@ It provides access to specific modules exposed by the plugin. It's loaded right `exposed-barUtils-chunk.js` is the generated webpack chunk for `barUtils` exposed module. It's loaded via the plugin entry chunk (`plugin-entry.js`) when needed. +Plugins may also include other assets, such as JSON localization files that follow the general pattern +`locales//plugin__.json` or static images referenced from the plugin code. + +## Serving plugin assets + +Dynamic plugins are deployed on a cluster via OLM operators. Each plugin deployment should include a web +server that hosts the [generated assets](#generated-assets) of the given plugin. + +**Important!** Make sure to configure your plugin web server to use MIME type `text/javascript` for all +JS assets to avoid any issues with the `X-Content-Type-Options: nosniff` security header used by Console +when fetching plugin assets via Bridge URL `/api/plugins/`. + +Requests for JS assets not served with the correct MIME type can be blocked by the browser, breaking your +plugin's functionality. + +### Caching + +The following table lists important plugin assets that must NOT be cached by the plugin web server. + +| Asset | Notes | +| ---------------------- | -------------------------------------------------------------- | +| `plugin-manifest.json` | | +| `plugin-entry.js` | Applies only to Console plugin SDK versions 0.0.x | + +We generally recommend disabling caching of any JSON resources hosted by the plugin web server. + ## Plugin development Run Bridge locally and instruct it to proxy e.g. `/api/plugins/console-demo-plugin` requests directly diff --git a/frontend/packages/console-dynamic-plugin-sdk/scripts/package-definitions.ts b/frontend/packages/console-dynamic-plugin-sdk/scripts/package-definitions.ts index 730a770c3003..547e808a465a 100644 --- a/frontend/packages/console-dynamic-plugin-sdk/scripts/package-definitions.ts +++ b/frontend/packages/console-dynamic-plugin-sdk/scripts/package-definitions.ts @@ -11,7 +11,7 @@ type GeneratedPackage = { outDir: string; /** Package manifest. Note: `version` is updated via the publish script. */ manifest: readPkg.PackageJson; - /** Additional files to copy to the package output directory. */ + /** Additional files or directories to copy to the package output directory. */ filesToCopy: Record; }; @@ -35,6 +35,11 @@ const commonFiles: Record = { 'README.md': 'README.md', }; +const docFiles: Record = { + docs: 'docs', + 'upgrade-PatternFly.md': 'upgrade-PatternFly.md', +}; + const getReferencedAssets = (outDir: string) => { const baseDir = resolvePath(`${outDir}/lib`); const jsFiles = glob.sync('**/*.js', { cwd: baseDir, absolute: true }); @@ -113,7 +118,7 @@ export const getCorePackage: GetPackageDefinition = ( }, filesToCopy: { ...commonFiles, - docs: 'docs', + ...docFiles, ...getReferencedAssets('dist/core'), }, }); diff --git a/frontend/packages/console-dynamic-plugin-sdk/upgrade-PatternFly.md b/frontend/packages/console-dynamic-plugin-sdk/upgrade-PatternFly.md new file mode 100644 index 000000000000..5513b96b89b8 --- /dev/null +++ b/frontend/packages/console-dynamic-plugin-sdk/upgrade-PatternFly.md @@ -0,0 +1,51 @@ +# PatternFly Upgrade Notes + +A dynamic plugin targets one or more versions of OpenShift Console. Each Console version supports +specific version(s) of [PatternFly](https://www.patternfly.org/) in terms of CSS styling. + +Check the [OpenShift Console Versions vs PatternFly Versions][console-pf-versions] table +for compatibility before upgrading to a newer version of PatternFly. + +## Console 4.14 and below + +Console provides the following PatternFly 4.x [shared modules][console-shared-modules] to plugins: + +- `@patternfly/react-core` +- `@patternfly/react-table` +- `@patternfly/quickstarts` + +When using code from these packages, make sure to import directly from the package index: + +```ts +// Do _not_ do this: +import { Button } from '@patternfly/react-core/dist/esm/components/Button'; +// Instead, do this: +import { Button } from '@patternfly/react-core'; +``` + +## Console 4.15 + +All plugins that target OpenShift Console 4.15 should upgrade to PatternFly 5.x to take advantage +of [PatternFly dynamic modules][console-pf-dynamic-modules]. + +Any PatternFly related code should be imported via the corresponding package index: + +```ts +// Do _not_ do this: +import { MonitoringIcon } from '@patternfly/react-icons/dist/esm/icons/monitoring-icon'; +// Instead, do this: +import { MonitoringIcon } from '@patternfly/react-icons'; +``` + +## PatternFly resources + +- [Major release highlights providing an overview of changes][pf-release-highlights] +- [Upgrade guide with information about codemods and other resources][pf-upgrade-guide] +- [Release notes change log that can be searched and filtered][pf-upgrade-release-notes] + +[console-shared-modules]: ./README.md#shared-modules +[console-pf-versions]: ./README.md#openshift-console-versions-vs-patternfly-versions +[console-pf-dynamic-modules]: ./README.md#patternfly-dynamic-modules +[pf-release-highlights]: https://www.patternfly.org/get-started/release-highlights/ +[pf-upgrade-guide]: https://www.patternfly.org/get-started/upgrade +[pf-upgrade-release-notes]: https://www.patternfly.org/get-started/upgrade/release-notes