You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
//include::../modules/dynamic-plugins/proc-obtaining-integrity-checksum.adoc[leveloffset=+3] //from tkral:This is documented in a better way in "= Installing third-party plugins in {product}" we can remove this module. It is not even placed correctly here as this is not specific to helm chart in anyway
//include::../modules/dynamic-plugins/proc-rhdh-example-external-dynamic-plugins.adoc[leveloffset=+3] assemblies/dynamic-plugins/assembly-third-party-plugins-installation.adoc replaces this
In {product}, third-party dynamic plugins can be integrated seamlessly, enabling the use of external plugins alongside native ones. This flexibility allows you to enhance the platform functionality without modifying its core structure. To add third-party dynamic plugins, you can either export them as standalone packages or wrap them in custom wrappers, especially if you want to adjust the dependencies or configurations of a plugin for compatibility.
5
+
In {product}, third-party dynamic plugins can be integrated seamlessly, enabling the use of external plugins. This flexibility allows you to enhance the platform functionality without modifying its source code and rebuilding. To add third-party dynamic plugins, you need to export them as derived package.
6
6
7
-
The third-party plugins are typically packaged as dynamic plugins, which means they can be loaded at runtime, enabling you to easily manage external modules without rebuilding the entire application. The process involves creating a wrapper that exports the plugin code, ensuring that dependencies are correctly bundled or marked as shared, depending on their relationship to the {product-short} environment.
7
+
The third-party plugins are typically packaged as dynamic plugin derived package, enabling you to manage external modules without rebuilding the entire application. The process involves exporting the plugin package, ensuring that dependencies are correctly bundled or marked as shared, depending on their relationship to the {product-short} environment.
8
8
9
9
To integrate a third-party plugin into {product-short}:
10
10
@@ -13,102 +13,15 @@ To integrate a third-party plugin into {product-short}:
13
13
. Package and publish the dynamic plugin. See xref:proc-package-third-party-dynamic-plugin_{context}[].
14
14
. Install the plugin in the {product-short} environment. See xref:proc-install-third-party-plugins-rhdh_{context}[].
15
15
16
-
The third-party plugins include:
17
-
18
-
Backend plugins::
19
-
+
20
-
--
21
-
To ensure compatibility with the dynamic plugin support and enable their use as dynamic plugins, existing backend plugins must be compatible with, the new backend system. Additionally, these plugins must be rebuilt using a dedicated CLI command.
22
-
23
-
The new backend system is created using `createBackendPlugin()` or `createBackendModule()`. You must export the new backend system as the default export from either the main package or an alpha package (if support exists in alpha). The dynamic export mechanism automatically identifies private dependencies, and adds them to the `bundleDependencies` field in the `package.json` file. This mechanism ensures that the dynamic plugin package is self-contained, with private dependencies bundled within a private `node_modules` folder.
24
-
25
-
The backend plugins contains two types of dependencies, including:
26
-
27
-
* *Shared dependencies* are provided by an application and listed as `peerDependencies` in `package.json` file, not bundled in the dynamic plugin package. For example, by default, all `@backstage` packages are shared.
28
-
+
29
-
You can use the `--shared-package` flag to specify shared dependencies. To treat a `@backstage` package as private, use the negation prefix (`!`).
30
-
31
-
* *Embedded dependencies* are bundled into the dynamic plugin package with their dependencies hoisted to the top level. By default, packages with `-node` or `-common` suffixes are embedded.
32
-
+
33
-
You can use the `--embed-package` flag to specify additional embedded packages, including those in the same repository that do not follow the default naming convention.
34
-
35
-
The following is an example of exporting a dynamic plugin with shared and embedded packages:
36
-
37
-
.Example dynamic plugin export with shared and embedded packages
<1> `@backstage/plugin-notifications` package is treated as a private dependency and is bundled in the dynamic plugin package, despite being in the `@backstage` scope.
44
-
<2> `@backstage/plugin-notifications-backend` package is marked as an embedded dependency and is bundled in the dynamic plugin package.
45
-
--
46
-
47
-
Front-end plugins::
48
-
+
49
-
--
50
-
Front-end plugins can use `scalprum` for configuration, which the CLI can generate automatically during the export process. The generated default configuration is logged when running the following command:
51
-
52
-
.Example command to log the default configuration
53
-
[source,bash]
54
-
----
55
-
npx @janus-idp/cli@latest export-dynamic
56
-
----
57
-
58
-
The following is an example of default `scalprum` configuration:
59
-
60
-
.Default `scalprum` configuration
61
-
[source,json]
62
-
----
63
-
"scalprum": {
64
-
"name": "<package_name>", // The Webpack container name matches the NPM package name, with "@" replaced by "." and "/" removed.
65
-
"exposedModules": {
66
-
"PluginRoot": "./src/index.ts" // The default module name is "PluginRoot" and doesn't need explicit specification in the app-config.yaml file.
67
-
}
68
-
}
69
-
----
70
-
71
-
You can add a `scalprum` section to the `package.json` file. For example:
72
-
73
-
.Example `scalprum` customization
74
-
[source,json]
75
-
----
76
-
"scalprum": {
77
-
"name": "custom-package-name",
78
-
"exposedModules": {
79
-
"FooModuleName": "./src/foo.ts",
80
-
"BarModuleName": "./src/bar.ts"
81
-
// Define multiple modules here, with each exposed as a separate entry point in the Webpack container.
82
-
}
83
-
}
84
-
----
85
-
86
-
Dynamic plugins might need adjustments for {product-short} needs, such as static JSX for mountpoints or dynamic routes. These changes are optional but might be incompatible with static plugins.
87
-
88
-
To include static JSX, define an additional export and use it as the dynamic plugin's `importName`. For example:
To use dynamic plugins in {product}, the plugins must be exported as separate packages. These packages contain the plugin code and dependencies, ready for dynamic plugin integration into {product-short}.
4
+
To use plugins in {product}, the plugins must be exported as derived dynamic plugin package. These packages contain the plugin code and dependencies, ready for dynamic plugin integration into {product-short}.
5
+
6
+
The third-party plugins include:
7
+
8
+
Backend plugins::
9
+
+
10
+
--
11
+
To ensure compatibility with the dynamic plugin support and enable their use as dynamic plugins, existing backend plugins must be compatible with the plugin instance. Additionally, these plugins must be rebuilt using a dedicated CLI command.
12
+
13
+
The plugin instance is created using `createBackendPlugin()` or `createBackendModule()`. You must export the plugin instance as the default export from either the main package or an `alpha` package (if the plugin instance support is still provided using `alpha` APIs). This doesn't add any additional requirement on top of the standard plugin development guidelines of the plugin instance.
14
+
15
+
Certain plugin dependencies require specific handling in the derived packages, such as:
16
+
17
+
* *Shared dependencies* are provided by the {product-very-short} application and listed as `peerDependencies` in `package.json` file, not bundled in the dynamic plugin package. For example, by default, all `@backstage` scoped packages are shared.
18
+
+
19
+
You can use the `--shared-package` flag to specify shared dependencies. To treat a `@backstage` package as private, use the negation prefix (`!`).
20
+
21
+
* *Embedded dependencies* are bundled into the dynamic plugin package with their dependencies hoisted to the top level. By default, packages with `-node` or `-common` suffixes are embedded.
22
+
+
23
+
You can use the `--embed-package` flag to specify additional embedded packages, including those in the same repository that do not follow the default naming convention.
24
+
25
+
The following is an example of exporting a dynamic plugin with shared and embedded packages:
26
+
27
+
.Example dynamic plugin export with shared and embedded packages
<1> `@backstage/plugin-notifications` package is treated as a private dependency and is bundled in the dynamic plugin package, despite being in the `@backstage` scope.
34
+
<2> `@backstage/plugin-notifications-backend` package is marked as an embedded dependency and is bundled in the dynamic plugin package.
35
+
--
36
+
37
+
Front-end plugins::
38
+
+
39
+
--
40
+
Front-end plugins can use `scalprum` for configuration, which the CLI can generate automatically during the export process. The generated default configuration is logged when running the following command:
41
+
42
+
.Example command to log the default configuration
43
+
[source,bash]
44
+
----
45
+
npx @janus-idp/cli@latest export-dynamic
46
+
----
47
+
48
+
The following is an example of default `scalprum` configuration:
49
+
50
+
.Default `scalprum` configuration
51
+
[source,json]
52
+
----
53
+
"scalprum": {
54
+
"name": "<package_name>", // The Webpack container name matches the NPM package name, with "@" replaced by "." and "/" removed.
55
+
"exposedModules": {
56
+
"PluginRoot": "./src/index.ts" // The default module name is "PluginRoot" and doesn't need explicit specification in the app-config.yaml file.
57
+
}
58
+
}
59
+
----
60
+
61
+
You can add a `scalprum` section to the `package.json` file. For example:
62
+
63
+
.Example `scalprum` customization
64
+
[source,json]
65
+
----
66
+
"scalprum": {
67
+
"name": "custom-package-name",
68
+
"exposedModules": {
69
+
"FooModuleName": "./src/foo.ts",
70
+
"BarModuleName": "./src/bar.ts"
71
+
// Define multiple modules here, with each exposed as a separate entry point in the Webpack container.
72
+
}
73
+
}
74
+
----
75
+
76
+
Dynamic plugins might need adjustments for {product-short} needs, such as static JSX for mountpoints or dynamic routes. These changes are optional but might be incompatible with static plugins.
77
+
78
+
To include static JSX, define an additional export and use it as the dynamic plugin's `importName`. For example:
79
+
80
+
.Example static and dynamic plugin export
81
+
[source,tsx]
82
+
----
83
+
// For a static plugin
84
+
export const EntityTechdocsContent = () => {...}
85
+
86
+
// For a dynamic plugin
87
+
export const DynamicEntityTechdocsContent = {
88
+
element: EntityTechdocsContent,
89
+
staticJSXContent: (
90
+
<TechDocsAddons>
91
+
<ReportIssue />
92
+
</TechDocsAddons>
93
+
),
94
+
};
95
+
----
96
+
--
5
97
6
98
.Prerequisites
7
99
* The `@janus-idp/cli` package is installed. Use the latest version (`@latest` tag) for compatibility with the most recent features and fixes.
@@ -11,25 +103,14 @@ To use dynamic plugins in {product}, the plugins must be exported as separate pa
11
103
* The third-party plugin is compatible with your {product} version. For more information, see link:https://github.com/janus-idp/backstage-showcase/blob/main/docs/dynamic-plugins/versions.md[Version compatibility matrix].
12
104
13
105
.Procedure
14
-
. Use the `package export-dynamic-plugin` command from the `@janus-idp/cli` package to export the plugin:
15
-
+
16
-
--
106
+
Use the `package export-dynamic-plugin` command from the `@janus-idp/cli` package to export the plugin:
Ensure that you execute the previous command in the root directory of the plugin's JavaScript package (containing `package.json` file).
24
-
--
25
115
26
-
. Located the exported package in the `dist-dynamic` sub-folder.
27
-
. Use `npm pack` or a private NPM registry to package or distribute the plugin. For more information, see xref:proc-package-third-party-dynamic-plugin_{context}[].
28
-
+
29
-
--
30
-
[IMPORTANT]
31
-
====
32
-
Ensure that you do not push derived dynamic plugin packages to a public NPM registry. Use a private NPM registry only.
Copy file name to clipboardExpand all lines: modules/dynamic-plugins/proc-package-third-party-dynamic-plugin.adoc
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,7 +3,7 @@
3
3
4
4
To package a third-party plugin as a dynamic plugin, you need to access to its source code and must export a plugin using the `@janus-idp/cli`. For more information, see xref:proc-export-third-party-plugins-rhdh_{context}[].
5
5
6
-
After exporting a third-party plugin, you can convert the package into one of the following supported formats:
6
+
After exporting a third-party plugin, you can package the derived package into one of the following supported formats:
7
7
8
8
* Open Container Initiative (OCI) image (recommended)
0 commit comments