Procedure

1. Make sure the required plugins are enabled in your RHDH my-rhdh-app-config file or the Backstage custom resource (CR):

   global:
     dynamic:
       plugins:
         - package: ./dynamic-plugins/dist/backstage-community-plugin-catalog-backend-module-scaffolder-relation-processor-dynamic
           disabled: false
         - package: ./dynamic-plugins/dist/backstage-plugin-notifications
           disabled: false
         - package: ./dynamic-plugins/dist/backstage-plugin-notifications-backend-dynamic
           disabled: false

2. Modify the Software Template that you want to update.
3. Complete one or both of the following tasks:
4. Include the annotation in your template: Add the backstage.io/template-version annotation in your template metadata. When this annotation is present, it is automatically used to annotate your catalog entity and display a default version value.

5. Pass the annotation as input to the action: This method takes precedence over the annotation in the template itself and allows the user running the template to specify the version.

   # ...
   - id: version-templateRef
     name: Append the version of this template to the entityRef
     action: catalog:template:version
     input:
       annotations:
         backstage.io/template-version: ${{ parameters.version }}
   # ...

Verification

1. Create a catalog component using the updated Software Template. This step creates a new component in Backstage and optionally, pushes files to an external repository (for example, GitHub, GitLab).

2. Check the component in the Catalog UI.

   1. On the Catalog page, locate the newly created catalog component.
   2. Verify that the backstage.io/template-version annotation is present in the entity. You can use INSPECT ENTITY and select YAML Raw or JSON Raw view to find the annotation in the component definition.

3. Only if you have published the catalog component: Check the component file in the repository.

   1. If VIEW SOURCE is present in your UI: Click VIEW SOURCE to open the stored component file in the repository.
   2. Locate the file manually and verify that the backstage.io/template-version annotation is present.

Procedure

1. Open your RHDH app-config.yaml file.
2. Add the following configuration to the scaffolder section to enable Software Template update notifications

3. Optional: To customize the notification title and description, add the message block:

   scaffolder:
     notifications:
       templateUpdate:
         enabled: true
         message:
           title: 'Custom title for $ENTITY_DISPLAY_NAME'
           description: 'Custom description'

   where:

   enabled

   Set to true to enable the notification. Default value is false.

   message:title

   Enter the notification title.

   message:description

   Enter the notification description.

   Note

   The message:title and message:description fields support the $ENTITY_DISPLAY_NAME variable. The system replaces this variable with the title (or the name, if the title is missing) of the scaffolded entity.

Verification

1. Log in to your Red Hat Developer Hub instance.
2. In the left navigation menu, verify that the Notifications item is displayed.
3. Update the version of a Software Template and verify that the owner of a component scaffolded from that template receives a notification.

Procedure

1. Locate the Software Template object YAML file where you want to add the provenance information and add a step that uses the catalog:scaffolded-from action. This action links the resulting catalog entity back to the source template.

2. Optional: To track the template version (for example, v1.0 versus v1.5), include the catalog:template:version action in the steps section. The following code block is an example to adding versioning action to the steps section:

   steps:
     - id: create-provenance-annotation
       name: Append the entityRef of this template to the entityRef
       action: catalog:scaffolded-from
     - id: create-version-annotation
       name: Create Template Version Annotation
       action: catalog:template:version
       input:
         templateVersion: ${{ parameters.version }}
     - ... other steps ...

   where:

   steps:input:templateVersion

   Reads the version parameter

   Note

   The catalog:template:version action reads a version parameter defined in the template and applies it as an annotation to the resulting catalog entity.

3. In your Red Hat Developer Hub app-config.yaml file, configure the catalog.locations section to point to the Software Template that you want to add. You might need to add Template to the global catalog.rules.allow list or add a granular rule to the location to allow for Software Templates ingestion, as shown in the following example:

   # ...
   catalog:
     locations:
       - type: url
         target: https://<repository_url>/example-template.yaml
         rules:
           - allow: [Template]
   # ...

   where:

   catalog.locations.type

   Enter the url type if you are importing templates from a repository, such as GitHub or GitLab.

   catalog.locations.target

   Enter the URL for the template.

   catalog.locations.rules.allow

   Enter the Template rule to allow new Software Templates to be added to the catalog.

1. In the Red Hat Developer Hub navigation menu, go to Catalog and locate the newly created catalog component.
2. To view the underlying data that links the entity to the template, select the INSPECT ENTITY option.

3. To verify provenance annotations, complete the following steps:

   1. Select the YAML Raw or JSON Raw view and verify the presence of the data item for the scaffoldedFrom link.

   2. Optional: If versioning was included, verify the presence of the backstage.io/template-version annotation.

      Note

      If you publish the catalog component to an external repository (such as Git), the component file in that repository must also contain the backstage.io/template-version annotation.

Procedure

1. In the Red Hat Developer Hub navigation menu, click Catalog, use the filters to find and select the Software Template you want to inspect.
2. In the Software Template detail page, click the Dependencies tab. This view lists all catalog entities such as components, resources, and systems that reference this template, including any version information if configured.

Procedure

1. Enable the template sync and notification plugins in your RHDH dynamic-plugins.yaml file:

   plugins:
   # Enables the core template synchronization logic
     - package: './dynamic-plugins/dist/backstage-community-plugin-scaffolder-backend-module-scaffolder-relation-processor'
       disabled: false
   # Required only if you want to receive notifications for new pull requests
     - package: './dynamic-plugins/dist/backstage-plugin-notifications'
       disabled: false

2. Open your RHDH app-config.yaml file.

3. Configure the pull request (PR) feature by adding the following configuration:

   scaffolder:
     pullRequests:
       templateUpdate:
         enabled: true

4. Optional: Enable notifications to alert entity owners when a PR is created:

   scaffolder:
     notifications:
       templateUpdate:
         enabled: true

5. Restart the Red Hat Developer Hub instance to apply the changes.

Verification

1. Update the version of a source template in its repository.
2. Navigate to a repository scaffolded from that template.
3. Confirm that a new pull request named [component-name]/template-upgrade-v[version] exists.

Procedure

1. Create a directory in your Git repository for the Software Template.
2. Create a file named template.yaml in that directory.
3. In the template.yaml file, define the apiVersion, kind, and metadata to identify the starter kit in the software catalog.
4. Add a spec section to define the parameters that a developer must provide when they use the Software Template.

5. Define the steps required to generate the project, which can include fetch:template to retrieve the skeleton and publish:github to create the new repository.

   Important

   You must include TechDocs in your Software Templates to ensure that documentation is automatically generated for every new project created from the Software Template.

Verification

1. Inspect the template.yaml file to ensure the YAML syntax is valid.
2. Confirm that the name and action fields are defined so the template is correctly recognized as a Scaffolder task.
3. Check that the defined parameters match the variables used in your Software Template skeleton files.
4. Navigate to the form playground at <instance_url>/create/template-form and test the Software Template configuration to confirm the fields and logic render as intended.

Procedure

1. Navigate to the Create page in the RHDH interface.
2. Select Register Component.
3. Enter the full URL to your template.yaml file in the Repository URL field.
4. Click Analyze and then Import.

Verification

1. Navigate to the Create page.
2. Confirm that your new template is displayed in the list of available options.

Procedure

1. Publish the JSON file containing your Learning Paths data to a web server, such as GitHub or GitLab. You can find an example at https://raw.githubusercontent.com/redhat-developer/rhdh/release-1.9/packages/app/public/learning-paths/data.json.

2. Configure the Developer Hub proxy to access the Learning Paths data from the hosted JSON file, by adding the following to the app-config.yaml file:

   proxy:
     endpoints:
       '/developer-hub':
         target: <target>
         pathRewrite:
           '^/api/proxy/developer-hub/learning-paths': '<learning_path.json>'
         changeOrigin: true
         secure: true

   <target>

   Enter the hosted JSON file base URL, such as https://raw.githubusercontent.com.

   <learning_path.json>

   Enter the hosted JSON file path without the base URL, such as '/redhat-developer/rhdh/main/packages/app/public/learning-paths/data.json'

   Tip

   When also configuring the home page, due to the use of overlapping pathRewrites for both the learning-path and homepage quick access proxies, create the learning-paths configuration (^api/proxy/developer-hub/learning-paths) before you create the homepage configuration (^/api/proxy/developer-hub). For example:

   proxy:
     endpoints:
       '/developer-hub':
         target: https://raw.githubusercontent.com/
         pathRewrite:
           '^/api/proxy/developer-hub/learning-paths': '/redhat-developer/rhdh/main/packages/app/public/learning-paths/data.json'
           '^/api/proxy/developer-hub/tech-radar': '/redhat-developer/rhdh/main/packages/app/public/tech-radar/data-default.json'
           '^/api/proxy/developer-hub': '/redhat-developer/rhdh/main/packages/app/public/homepage/data.json'
         changeOrigin: true
         secure: true

Procedure

1. Deploy your Developer Hub customization service on the same OpenShift Container Platform cluster as your Developer Hub instance. You can find an example at red-hat-developer-hub-customization-provider, that provides the same data as default Developer Hub data. The customization service provides a Learning Paths data URL such as: http://<rhdh-customization-provider>/learning-paths.

2. Configure the Developer Hub proxy to use your dedicated service to provide the Learning Path data, add the following to the app-config.yaml file:

   proxy:
     endpoints:
       '/developer-hub/learning-paths':
         target: <learning_path_data_url>
         changeOrigin: true
         qsecure: true # Change to "false" in case of using self hosted cluster with a self-signed certificate

Prerequisites

1. You can log in to developers.redhat.com
2. Your platform engineer has granted you access to the Learning Paths plugin.

Procedure

1. In your Red Hat Developer Hub navigation menu, click Learning Paths.

2. Select the tile for the course you want to begin.

   Note

   This action redirects you to the main page of the course in the Red Hat Developers site.

Procedure

1. Copy the default configuration and modify the field values to suit your needs. You can adjust the priority value of each header component to control its position. Additionally, you can enable or disable components by adding or removing them from the configuration. To ensure that the remaining header buttons align with the end of the header before the profile dropdown button, set config.props.growFactor to 1 in the Spacer mount point to enable the Spacer component. For example:

   - mountPoint: global.header/component
     importName: Spacer
     config:
       priority: 100
       props:
         growFactor: 1

2. To use your custom header, you must install it as a dynamic plugin by adding your plugin configuration to your app-config-dynamic.yaml file. For example:

   - package: <npm_or_oci_package_reference>
     disabled: false
     pluginConfig:
       dynamicPlugins:
         frontend:
           <package_name>:
             mountPoints:
               - mountPoint: application/header
                 importName: <application_header_name>
                 config:
                   position: above-main-content
               - mountPoint: global.header/component
                 importName: <header_component_name>
                 config:
                   priority: 100
               - mountPoint: global.header/component
                 importName: <header_component_name>
                 config:
                   priority: 90

   where:

   <npm_or_oci_package_reference>

   Specifies the package name.

   <application_header_name>

   Specifies the name of the application header. For example: MyHeader

   <header_component_name>

   Specifies the name of the header component. For example: MyHeaderComponent

   Note

   importName is an optional name referencing the value returned by the scaffolder field extension API.

3. Optional: To disable the global header, set the value of the disabled field to true in your dynamic-plugins.yaml file. For example:

   - package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-global-header
     disabled: true

Procedure

1. To display a custom company logo in the global header, update the configuration with a mount point for CompanyLogo:

   # ...rest of the global header configuration
   red-hat-developer-hub.backstage-plugin-global-header:
     mountPoints:
       - mountPoint: application/header
         importName: GlobalHeader
         config:
           # Supported values: above-main-content | above-sidebar
           position: above-main-content
   
       - mountPoint: global.header/component
         importName: CompanyLogo
         config:
           priority: 200
           props:
             # Path to navigate when users click the logo:
             to: '/catalog'
             width: 300
             height: 200
             logo: <string> or <object> # Logo can be a base64 string or theme-specific object
               # Example 1: Single logo for all themes
               # logo: "<base64_encoded_images>"
   
               # Example 2: Theme-specific logos
               # logo:
                   dark: 'data:image/png;base64,...' # Used in dark theme
                   light: 'data:image/png;base64,...' # Used in light theme

2. (Optional) If you do not provide logo props to the CompanyLogo component, the component instead uses values defined under app.branding in your app-config.yaml file. You can configure the CompanyLogo as shown in the following configuration:

   app:
     branding:
       fullLogoWidth: 220  # Fallback width
       fullLogo: <string> or <object> #fullLogo can be a base64 string or theme-specific object
   
       # Example 1: Single logo for all themes
       #fullLogo: "<base64_encoded_image>
       # Example 2: Theme-specific logos
       #fullLogo:
           dark: 'data:image/png;base64,...' # Used in dark theme
           light: 'data:image/png;base64,...' # Used in light theme

   CompanyLogo uses the following configuration elements to control fallback and sizing behavior:

   • Logo source priority

     • The component selects the logo source in the following order:

       First, CompanyLogo props (logo, logo.light, logo.dark), then, app.branding.fullLogo. If you do not provide a logo through either, the component displays the default Developer Hub theme-specific logo.

   • Logo width priority

     • The component applies the first available value from props.width, then app.branding.fullLogoWidth from app-config.yaml. If you do not specify the width using either, the component applies a default width (150px).

       Note

       CompanyLogo preserves the images aspect ratio and never crops or distorts it. If the configured width results in a height greater than the maximum allowed (default: 40px), the image is automatically scaled down. As a result, adjusting only the width might not visibly change the logo unless the height is also configured.

       Increasing the logo height increases the height of the global header. The component first applies the value from props.height. If you do not specify the height, the component applies a default height (40px).

Verification

1. The logo is displayed correctly in the global header.
2. Click the logo to confirm it redirects to the path you defined in props.to.
3. Toggle between light and dark themes to ensure the correct logo loads in each.
4. (Optional) Temporarily remove the CompanyLogo props to test the fallback to app.branding.fullLogo.

Procedure

1. To display the logo exclusively in the sidebar, set the value of the app.sidebar.logo parameter to true as shown in the following example:

   app:
     sidebar:
       logo: true

   Note

   To display the logo in only the sidebar, remove the CompanyLogo component from the configuration.

2. To display the same logo in the sidebar for all themes, update the configuration as shown in the following configuration:

   app:
     sidebar:
       logo: true
     branding:
       fullLogoWidth: 220
       fullLogo: 'data:image/svg+xml;base64,...'

3. For theme-specific logos, you can configure the sidebar logo as shown in the following configuration:

   app:
     sidebar:
       logo: true
     branding:
       fullLogoWidth: 220
       fullLogo:
         light: 'data:image/svg+xml;base64,...'
         dark: 'data:image/svg+xml;base64,...'

Verification

1. The logo is displayed correctly in the sidebar.
2. Toggle between light and dark themes to ensure the correct logo loads in each.

Procedure

1. To configure spec.profile.displayName, use the following code:

   apiVersion: backstage.io/v1alpha1
   kind: User
   metadata:
     # Required unique username
     name: <my_display_name>
     # Optional preferred title
     title: <display_name_title>
   spec:
     profile:
       # Optional preferred display name (highest priority)
       displayName: <my_display_name>
     memberOf: [janus-authors]

2. To configure metadata.title rather than spec.profile.displayname, use the following code:

   apiVersion: backstage.io/v1alpha1
   kind: User
   metadata:
     # Required unique username
     name: <my_display_name>
     # Optional preferred title
     title: <display_name_title>
   spec:
     memberOf: [janus-authors]

3. To configure neither spec.profile.displayname or metadata.title, use the following code:

   apiVersion: backstage.io/v1alpha1
   kind: User
   metadata:
     # Required unique username
     name: <my_display_name>
   spec:
     memberOf: [janus-authors]

   Note

   The application falls back to metadata.name when you do not register the user entity.

Prerequisites

1. You have access to your Red Hat Developer Hub configuration files.
2. You have administrative permissions to modify ConfigMaps (if using the Operator).

Procedure

1. Locate your dynamic-plugin configuration.
2. Operator deployment: The configuration is stored in a ConfigMap referenced by your Backstage custom resource (CR).
3. Helm deployment: The configuration is in your values.yaml file or separate configuration files.
4. Enable the global header plugin. Ensure that the red-hat-developer-hub-backstage-plugin-global-header entry exists under the plugins: list and that disabled is set to false.

5. Verify that you enabled the global header plugin. Confirm that you listed the red-hat-developer-hub-backstage-plugin-global-header plugin under plugins: with disabled: false (or without a disabled property):

     - package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-global-header
       disabled: false

6. Add the required components. Under the mountPoints section of the plugin, add the components as shown in the following example:

     mountPoints:
       - mountPoint: application/header
         importName: GlobalHeader
         config:
           position: above-sidebar
       - mountPoint: global.header/component
         importName: StarredDropdown
         config:
           priority: 85
       - mountPoint: global.header/component
         importName: ApplicationLauncherDropdown
         config:
           priority: 82
       - mountPoint: global.header/component
         importName: MenuItemLink
         config:
           section: Documentation
         priority: 150
         props:
             title: Developer Hub
             icon: developerHub
             link: https://docs.redhat.com/en/documentation/red_hat_developer_hub
       - mountPoint: global.header/application-launcher
       importName: MenuItemLink
       config:
         section: Developer Tools
         priority: 100
         props:
             title: "RHDH Local"
             icon: developerHub
             link: https://github.com/redhat-developer/rhdh-local

7. Apply the configuration.
8. Operator deployment: Update the ConfigMap and allow the Operator to reconcile the changes.
9. Helm deployment: Apply your updated configuration using helm upgrade.
10. Verify the features are enabled. After the Red Hat Developer Hub instance restarts, confirm that the star icon and Quicklinks matrix appear in the global header.

Procedure

1. Specify the global.floatingactionbutton/config mount point in your app-config-dynamic.yaml file. For example:

   - package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-bulk-import
     disabled: false
     pluginConfig:
       dynamicPlugins:
         frontend:
           red-hat-developer-hub.backstage-plugin-bulk-import:
             # Start of the floating action button configuration
             mountPoints:
               - mountPoint: global.floatingactionbutton/config
                 importName: BulkImportPage
                 config:
                   slot: 'page-end'
                   icon: <svg xmlns="http://www.w3.org/2000/svg" enable-background="new 0 0 24 24" height="24px" viewBox="0 0 24 24" width="24px" fill="#e8eaed"><g><rect fill="none" height="24" width="24"/></g><g><path d="M11,7L9.6,8.4l2.6,2.6H2v2h10.2l-2.6,2.6L11,17l5-5L11,7z M20,19h-8v2h8c1.1,0,2-0.9,2-2V5c0-1.1-0.9-2-2-2h-8v2h8V19z"/></g></svg>
                   label: 'Bulk import'
                   toolTip: 'Register multiple repositories in bulk'
                   to: /bulk-import/repositories
             # End of the floating action button configuration
             appIcons:
               - name: bulkImportIcon
                 importName: BulkImportIcon
             dynamicRoutes:
               - path: /bulk-import/repositories
                 importName: BulkImportPage
                 menuItem:
                   icon: bulkImportIcon
                   text: Bulk import

   frontend:mountPoints:importName

   (Required) The import name with an associated component to the mount point.

   frontend:mountPoints:importName:icon

   Use the svg value to display a black BulkImportPage icon.

2. To configure an action as a floating action button that opens an external link, specify the global.floatingactionbutton/config mount point in your dynamic-plugins.yaml file within the backstage-plugin-global-floating-action-button plugin. For example:

   - package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-global-floating-action-button
     disabled: false
     pluginConfig:
       dynamicPlugins:
         frontend:
           red-hat-developer-hub.backstage-plugin-global-floating-action-button:
             mountPoints:
                 - mountPoint: application/listener
                   importName: DynamicGlobalFloatingActionButton
                 - mountPoint: global.floatingactionbutton/config
                   importName: NullComponent
                   config:
                     icon: '<svg viewBox="0 0 250 300" xmlns="http://www.w3.org/2000/svg" preserveAspectRatio="xMidYMid"><path d="M200.134 0l55.555 117.514-55.555 117.518h-47.295l55.555-117.518L152.84 0h47.295zM110.08 99.836l20.056-38.092-2.29-8.868L102.847 0H55.552l48.647 102.898 5.881-3.062zm17.766 74.433l-17.333-39.034-6.314-3.101-48.647 102.898h47.295l25-52.88v-7.883z" fill="#40B4E5"/><path d="M152.842 235.032L97.287 117.514 152.842 0h47.295l-55.555 117.514 55.555 117.518h-47.295zm-97.287 0L0 117.514 55.555 0h47.296L47.295 117.514l55.556 117.518H55.555z" fill="#003764"/></svg>'
                     label: 'Quay'
                     showLabel: true
                     toolTip: 'Quay'
                     to: 'https://quay.io'
                 - mountPoint: global.floatingactionbutton/config
                   importName: NullComponent
                   config:
                     icon: github
                     label: 'Git'
                     toolTip: 'Github'
                     to: https://github.com/redhat-developer/rhdh-plugins

   frontend:mountPoints:importName

   Enter the import name with an associated component to the mount point.

   frontend:mountPoints:importName:icon

   (Optional) Enter the icon in Scalable Vector Graphics (SVG) format to display the Quay icon.

3. To configure a floating action button that contains a submenu, define the global.floatingactionbutton/config mount point in the same slot field in your dynamic-plugins.yaml file for multiple actions. The default slot is page-end when not specified. For example:

   - package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-bulk-import
     disabled: false
     pluginConfig:
       dynamicPlugins:
         frontend:
           red-hat-developer-hub.backstage-plugin-bulk-import:
             # Start of fab config
             mountPoints:
               - mountPoint: global.floatingactionbutton/config
                 importName: BulkImportPage
                 config:
                   slot: 'page-end'
                   icon: <svg xmlns="http://www.w3.org/2000/svg" enable-background="new 0 0 24 24" height="24px" viewBox="0 0 24 24" width="24px" fill="#e8eaed"><g><rect fill="none" height="24" width="24"/></g><g><path d="M11,7L9.6,8.4l2.6,2.6H2v2h10.2l-2.6,2.6L11,17l5-5L11,7z M20,19h-8v2h8c1.1,0,2-0.9,2-2V5c0-1.1-0.9-2-2-2h-8v2h8V19z"/></g></svg>
                   label: 'Bulk import'
                   toolTip: 'Register multiple repositories in bulk'
                   to: /bulk-import/repositories
             # end of fab config
             appIcons:
               - name: bulkImportIcon
                 importName: BulkImportIcon
             dynamicRoutes:
               - path: /bulk-import/repositories
                 importName: BulkImportPage
                 menuItem:
                   icon: bulkImportIcon
                   text: Bulk import
   
   - package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-global-floating-action-button
     disabled: false
     pluginConfig:
       dynamicPlugins:
         frontend:
           red-hat-developer-hub.backstage-plugin-global-floating-action-button:
             mountPoints:
               - mountPoint: application/listener
                 importName: DynamicGlobalFloatingActionButton
               - mountPoint: global.floatingactionbutton/config
                 importName: NullComponent
                 config:
                   icon: github
                   label: 'Git'
                   toolTip: 'Github'
                   to: https://github.com/redhat-developer/rhdh-plugins
               - mountPoint: global.floatingactionbutton/config
                 importName: NullComponent
                 config:
                   icon: '<svg viewBox="0 0 250 300" xmlns="http://www.w3.org/2000/svg" preserveAspectRatio="xMidYMid"><path d="M200.134 0l55.555 117.514-55.555 117.518h-47.295l55.555-117.518L152.84 0h47.295zM110.08 99.836l20.056-38.092-2.29-8.868L102.847 0H55.552l48.647 102.898 5.881-3.062zm17.766 74.433l-17.333-39.034-6.314-3.101-48.647 102.898h47.295l25-52.88v-7.883z" fill="#40B4E5"/><path d="M152.842 235.032L97.287 117.514 152.842 0h47.295l-55.555 117.514 55.555 117.518h-47.295zm-97.287 0L0 117.514 55.555 0h47.296L47.295 117.514l55.556 117.518H55.555z" fill="#003764"/></svg>'
                   label: 'Quay'
                   showLabel: true
                   toolTip: 'Quay'
                   to: 'https://quay.io'

   frontend:mountPoints:importName

   (Required) The import name with an associated component to the mount point.

4. To configure a floating action button to display only on specific pages, configure the global.floatingactionbutton/config mount point in the backstage-plugin-global-floating-action-button plugin and set the visibleOnPaths property as shown in the following example:

   - package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-bulk-import
     disabled: false
     pluginConfig:
       dynamicPlugins:
         frontend:
           red-hat-developer-hub.backstage-plugin-bulk-import:
             # start of fab config
             mountPoints:
               - mountPoint: global.floatingactionbutton/config
                 importName: BulkImportPage 1
                 config:
                   slot: 'page-end'
                   icon: <svg xmlns="http://www.w3.org/2000/svg" enable-background="new 0 0 24 24" height="24px" viewBox="0 0 24 24" width="24px" fill="#e8eaed"><g><rect fill="none" height="24" width="24"/></g><g><path d="M11,7L9.6,8.4l2.6,2.6H2v2h10.2l-2.6,2.6L11,17l5-5L11,7z M20,19h-8v2h8c1.1,0,2-0.9,2-2V5c0-1.1-0.9-2-2-2h-8v2h8V19z"/></g></svg>
                   label: 'Bulk import'
                   toolTip: 'Register multiple repositories in bulk'
                   to: /bulk-import/repositories
                   visibleOnPaths: ['/catalog', '/settings']
             # end of fab config
             appIcons:
               - name: bulkImportIcon
                 importName: BulkImportIcon
             dynamicRoutes:
               - path: /bulk-import/repositories
                 importName: BulkImportPage
                 menuItem:
                   icon: bulkImportIcon
                   text: Bulk import

   frontend:mountPoints:importName

   Enter the import name with an associated component to the mount point.

5. To hide a floating action button on specific pages, configure the global.floatingactionbutton/config mount point in the backstage-plugin-global-floating-action-button plugin and set the excludeOnPaths property as shown in the following example:

   - package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-bulk-import
     disabled: false
     pluginConfig:
       dynamicPlugins:
         frontend:
           red-hat-developer-hub.backstage-plugin-bulk-import:
             # start of fab config
             mountPoints:
               - mountPoint: global.floatingactionbutton/config
                 importName: BulkImportPage 1
                 config:
                   slot: 'page-end'
                   icon: <svg xmlns="http://www.w3.org/2000/svg" enable-background="new 0 0 24 24" height="24px" viewBox="0 0 24 24" width="24px" fill="#e8eaed"><g><rect fill="none" height="24" width="24"/></g><g><path d="M11,7L9.6,8.4l2.6,2.6H2v2h10.2l-2.6,2.6L11,17l5-5L11,7z M20,19h-8v2h8c1.1,0,2-0.9,2-2V5c0-1.1-0.9-2-2-2h-8v2h8V19z"/></g></svg>
                   label: 'Bulk import'
                   toolTip: 'Register multiple repositories in bulk'
                   to: /bulk-import/repositories
                   excludeOnPaths: ['/bulk-import']
             # end of fab config
             appIcons:
               - name: bulkImportIcon
                 importName: BulkImportIcon
             dynamicRoutes:
               - path: /bulk-import/repositories
                 importName: BulkImportPage
                 menuItem:
                   icon: bulkImportIcon
                   text: Bulk import

   frontend:mountPoints:importName

   Enter the import name with an associated component to the mount point.

6. To configure translation support for the floating action button, use translation keys instead of static text. The Global Floating Action Button plugin supports internationalization (i18n) through the labelKey and toolTipKey properties.

   Example for using translation keys in dynamic configuration:

1. If the labelKey is provided, the plugin will attempt to resolve the translation key
2. If the translation key is found, it will be used as the label
3. If the translation key is not found, the plugin will fall back to the label property

Procedure

1. Enable RBAC in your app-config.yaml file:

   permission:
     enabled: true

   When RBAC is enabled, the system determines user roles based on permissions:

   • Users with policy.entity.create permission are assigned the admin role.

   • Users without this permission are assigned the developer role.

     Note

     If RBAC is disabled (permission.enabled: false) or not configured, users are assumed to be platform engineers setting up Red Hat Developer Hub (RHDH) and are assigned the admin role.

2. Configure quick start items with role assignments in your app-config.yaml file:

   app:
     quickstart:
       - title: 'Platform Configuration'
         titleKey: steps.platformConfiguration.title
         roles: ['admin']
         # Only admins see this
       - title: 'Getting Started as Developer'
         titleKey: steps.gettingStarted.title
         roles: ['developer']
         # Only developers see this
       - title: 'Universal Welcome Guide'
         titleKey: steps.universalWelcome.title
         roles: ['admin', 'developer']
         # Both user roles see this

   The following roles are supported:

   admin

   Platform engineers, administrators, and users with elevated permissions

   developer

   Regular developers and users with standard permissions

   Note

   Quick start items without a roles property default to the admin role. Items can specify multiple roles, and users see quick start items that match their assigned role.

Procedure

1. In your RHDH navigation menu, click the Help (?) icon.
2. In the dropdown menu, click Quick start.
3. Select the quick start step that you want to begin.

4. To close the quick start drawer, click Hide.

   
   Note

   Your overall progress is tracked and displayed as a progress bar and a progress percentage in the quick start footer.

Procedure

1. For all quick start steps (both existing and new) in your configuration file, you must define both the original text and the new localization keys. For example, in the quickstart section of your custom app-config.yaml file, add the titleKey, descriptionKey, and textKey values, as follows:

   app-config.yaml fragment

   app:
     quickstart:
       # Existing quick start steps should also be updated with keys
       - title: 'Setup Authentication'
         titleKey: steps.setupAuth.title
         description: 'Learn the basics of navigating the {product-short} interface'
         descriptionKey: steps.setupAuth.description
         icon: 'home'
         cta:
           text: 'Get Started'
           textKey: steps.setupAuth.ctaTitle
           link: '/catalog'
   # ...

   where:

   title

   (Mandatory) Fallback for the title.

   titleKey

   Key for the translated title.

   description

   (Mandatory) Fallback for the description.

   descriptionKey

   Key for the translated description.

   text

   (Mandatory) Fallback for the CTA text.

   textKey

   Key for the translated CTA text.

2. In your dynamic-plugins.yaml file, add the translationResources section to your red-hat-developer-hub-backstage-plugin-quickstart configuration, as follows:

   app-config.yaml fragment

   plugins:
     - package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-quickstart
         disabled: false
         pluginConfig:
           dynamicPlugins:
             frontend:
               red-hat-developer-hub.backstage-plugin-quickstart:
                 # translationResources definition is required for translations to work
                 translationResources:
                   - importName: quickstartTranslations
                     ref: quickstartTranslationRef
                 # ... other configurations like mountPoints ...

   where:

   importName

   Enter the name used to reference the import.

   ref

   Reference to the resource definition.

3. In your translation file, map the keys from the first step to the localized strings for each supported language.

   allTranslations.json fragment

   "plugin.quickstart": {
     "en": {
       "steps.setupAuth.title": "Manage plugins EN",
       "steps.setupAuth.description": "EN Browse and install extensions to add features, connect with external tools, and customize your experience.",
       "steps.setupAuth.ctaTitle": "Start"
     },
     "fr": {
       "steps.setupAuth.title": "Gérer les plugins FR",
       "steps.setupAuth.description": "FR Parcourez et installez des extensions pour ajouter des fonctionnalités, vous connecter à des outils externes et personnaliser votre expérience.",
       "steps.setupAuth.ctaTitle": "Commencer"
     }
   }

Procedure

1. Publish the JSON file containing your Tech Radar data to a web server, such as GitHub or GitLab. You can find an example at https://raw.githubusercontent.com/backstage/community-plugins/main/workspaces/tech-radar/plugins/tech-radar-common/src/sampleTechRadarResponse.json.

2. Configure Developer Hub to access the Tech Radar data from the hosted JSON files, by adding the following to the app-config.yaml file:

   techRadar:
     url: <tech_radar_data_url>

   <tech_radar_data_url>

   Enter the Tech Radar data hosted JSON URL.

Procedure

1. Deploy your Developer Hub customization service on the same OpenShift Container Platform cluster as your Developer Hub instance. You can find an example at red-hat-developer-hub-customization-provider, that provides the same data as default Developer Hub data. The customization service provides a Tech Radar data URL such as: http://<rhdh-customization-provider>/tech-radar.

2. Add the dedicated service as an allowed host by adding the following code to the app-config.yaml file:

   backend:
      reading:
           allow:
             - host: '<rhdh_customization_provider_base_url>'

   <rhdh_customization_provider_base_url>

   Enter the base URL of your Tech Radar data URL, such as: <rhdh-customization-provider>.

3. Add the following to the app-config.yaml file:

   techRadar:
       url: <tech_radar_data_url>

   <tech_radar_data_url>

   Enter your Tech Radar data URL, such as: http://<rhdh-customization-provider>/tech-radar.

Procedure

1. From the Developer Hub web console, click Settings.

2. From the Appearance panel, select Light, Dark, or Auto to change the theme mode.

   

Procedure

1. Export a theme provider function in your dynamic plugin, for example:

   Sample myTheme.ts fragment

   import { lightTheme } from './lightTheme'; // some custom theme
   import { UnifiedThemeProvider } from '@backstage/theme';
   export const lightThemeProvider = ({ children }: { children: ReactNode }) => (
     <UnifiedThemeProvider theme={lightTheme} children={children} />
   );

   For more information about creating a custom theme, see Backstage documentation - Creating a Custom Theme.

2. Configure Developer Hub to load the theme in the UI by using the themes configuration field:

   app-config.yaml fragment

   dynamicPlugins:
     frontend:
       example.my-custom-theme-plugin:
         themes:
           - id: light
             title: Light
             variant: light
             icon: someIconReference
             importName: lightThemeProvider

   id

   Enter your theme ID, such as my_theme. Enter dark to override the default Developer Hub dark theme. Enter light to override the default Developer Hub light theme.

Procedure

1. Configure your Developer Hub app-config.yaml configuration file by choosing one of the following options:

   1. Use the full space on smaller windows and half of the space on larger windows as follows:

      dynamicPlugins:
        frontend:
          red-hat-developer-hub.backstage-plugin-dynamic-home-page:
            mountPoints:
              - mountPoint: home.page/cards
                importName: Placeholder
                config:
                  layouts:
                    xl: { w: 6, h: 2 }
                    lg: { w: 6, h: 2 }
                    md: { w: 6, h: 2 }
                    sm: { w: 12, h: 2 }
                    xs: { w: 12, h: 2 }
                    xxs: { w: 12, h: 2 }
                  props:
                    showBorder: true
                    debugContent: a placeholder

   2. Show the cards side by side by defining the x parameter as shown in the following example:

      dynamicPlugins:
        frontend:
          red-hat-developer-hub.backstage-plugin-dynamic-home-page:
            mountPoints:
              - mountPoint: home.page/cards
                importName: Placeholder
                config:
                  layouts:
                    xl: { w: 6, h: 2 }
                    lg: { w: 6, h: 2 }
                    md: { w: 6, h: 2 }
                    sm: { w: 12, h: 2 }
                    xs: { w: 12, h: 2 }
                    xxs: { w: 12, h: 2 }
                  props:
                    showBorder: true
                    debugContent: left
              - mountPoint: home.page/cards
                importName: Placeholder
                config:
                  layouts:
                    xl: { w: 6, h: 2, x: 6 }
                    lg: { w: 6, h: 2, x: 6 }
                    md: { w: 6, h: 2, x: 6 }
                    sm: { w: 12, h: 2, x: 0 }
                    xs: { w: 12, h: 2, x: 0 }
                    xxs: { w: 12, h: 2, x: 0 }
                  props:
                    showBorder: true
                    debugContent: right

      However, you can see a second card below this card by default.

   3. Show the cards in three columns by defining the x parameter as shown in the following example:

      dynamicPlugins:
        frontend:
          red-hat-developer-hub.backstage-plugin-dynamic-home-page:
            mountPoints:
              - mountPoint: home.page/cards
                importName: Placeholder
                config:
                  layouts:
                    xl: { w: 4, h: 2 }
                    lg: { w: 4, h: 2 }
                    md: { w: 4, h: 2 }
                    sm: { w: 6, h: 2 }
                    xs: { w: 12, h: 2 }
                    xxs: { w: 12, h: 2 }
                  props:
                    showBorder: true
                    debugContent: left
              - mountPoint: home.page/cards
                importName: Placeholder
                config:
                  layouts:
                    xl: { w: 4, h: 2, x: 4 }
                    lg: { w: 4, h: 2, x: 4 }
                    md: { w: 4, h: 2, x: 4 }
                    sm: { w: 6, h: 2, x: 6 }
                    xs: { w: 12, h: 2 }
                    xxs: { w: 12, h: 2 }
                  props:
                    showBorder: true
                    debugContent: center
              - mountPoint: home.page/cards
                importName: Placeholder
                config:
                  layouts:
                    xl: { w: 4, h: 2, x: 8 }
                    lg: { w: 4, h: 2, x: 8 }
                    md: { w: 4, h: 2, x: 8 }
                    sm: { w: 6, h: 2 }
                    xs: { w: 12, h: 2 }
                    xxs: { w: 12, h: 2 }
                  props:
                    showBorder: true
                    debugContent: right

Procedure

1. You can arrange the cards and adjust their dimensions using the drag-and-drop and resize functionality. The following is an example of an interactive homepage where you can add, remove, move, and resize cards:

   dynamicPlugins:
     frontend:
       red-hat-developer-hub.backstage-plugin-dynamic-home-page:
         dynamicRoutes:
           - path: /
             importName: DynamicCustomizableHomePage
         mountPoints:
            - mountPoint: home.page/cards
              importName: OnboardingSection
              config:
               layouts:
                 xl: { w: 12, h: 6 }
                 lg: { w: 12, h: 6 }
                 md: { w: 12, h: 7 }
                 sm: { w: 12, h: 8 }
                 xs: { w: 12, h: 9 }
                 xxs: { w: 12, h: 14 }
           - mountPoint: home.page/cards
             importName: EntitySection
             config:
               layouts:
                 xl: { w: 12, h: 7 }
                 lg: { w: 12, h: 7 }
                 md: { w: 12, h: 8 }
                 sm: { w: 12, h: 9 }
                 xs: { w: 12, h: 11 }
                 xxs: { w: 12, h: 15 }
           - mountPoint: home.page/cards
             importName: TemplateSection
             config:
               layouts:
                 xl: { w: 12, h: 5 }
                 lg: { w: 12, h: 5 }
                 md: { w: 12, h: 5 }
                 sm: { w: 12, h: 5 }
                 xs: { w: 12, h: 7.5 }
                 xxs: { w: 12, h: 13.5 }
           # Additional cards available in "Add widget" dialog
           - mountPoint: home.page/cards
             importName: RecentlyVisitedCard
           - mountPoint: home.page/cards
             importName: TopVisitedCard

2. You can change the title by overriding the title property of the dynamic homepage plugin as shown in the following example:

   dynamicPlugins:
     frontend:
       red-hat-developer-hub.backstage-plugin-dynamic-home-page:
         dynamicRoutes:
           - path: /
             importName: DynamicHomePage # or DynamicCustomizableHomePage for customizable homepage
             config:
               props:
                 title: 'Howdy {{firstName}} or {{displayName}}'

   The title property supports two variables:

3. {{displayName}}: This contains the full displayName of the catalog entity.
4. {{firstName}}: This contains the first part (separated by a space) of the displayName.

5. You can use a subtitle property which is not used by default as shown in the following example:

   dynamicPlugins:
     frontend:
       red-hat-developer-hub.backstage-plugin-dynamic-home-page:
         dynamicRoutes:
           - path: /
             importName: DynamicHomePage # or DynamicCustomizableHomePage
             config:
               props:
                 title: Our custom RHDH instance
                  subtitle: 'Hello {{displayName}}'

Procedure

1. Add the JSON Data source. The QuickAccessCard card on the homepage supports loading data from a JSON file. This JSON file can be hosted in your GitHub repository or any accessible endpoint.

2. Configure the Proxy in your RHDH app-config.yaml file.

   To allow the homepage to fetch data from the hosted JSON file, add the following proxy configuration to your RHDH app-config.yaml file:

   proxy:
     endpoints:
     # customize your backstage instance
     '/developer-hub':
       target: https://raw.githubusercontent.com/ # For example, https://raw.githubusercontent.com/
       pathRewrite:
         '^/api/proxy/developer-hub$': <path_to_your>.json # For example, /redhat-developer/rhdh/main/packages/app/public/homepage/data.json
       changeOrigin: true
       secure: true

   The following table lists the supported icon types:

   Icon type	Example	Rendered as
   Backstage system icon	"catalog"	Uses Backstage system [icons](https://github.com/backstage/backstage/blob/master/packages/app-defaults/src/defaults/icons.tsx)
   SVG String	"<svg>…​</svg>"	Renders inline SVG
   Image URL	"https://example.com/icon.png"	Renders external image. External images might be restricted to Content Security Policy (CSP) which can be configured in your RHDH app-config.yaml file.
   Relative Path	"/homepage/icons/icon.png"	Loads the icon from the app public folder (if present)

   Note

   SVGs must be valid strings when stored inside JSON (use single quotes inside <svg>).

   The following is an example of a JSON file:

   [
    {
    "title": "Community",
    "isExpanded": true,
    "links": [
    {
    "iconUrl": "https://img.icons8.com/ios/50/globe--v1.png",
    "label": "Website",
    "url": "https://developers.redhat.com/"
    },
    {
    "iconUrl": "https://img.icons8.com/ios/50/link--v1.png",
    "label": "Blog",
    "url": "https://developers.redhat.com/blog"
    },
    {
    "iconUrl": "github",
    "label": "GitHub",
    "url": "https://github.com/redhat-developer"
    },
    {
    "iconUrl": "https://img.icons8.com/color/48/slack.png",
    "label": "Slack",
    "url": "https://join.slack.com/xyz"
    },
    {
    "iconUrl": "https://img.icons8.com/color/48/youtube-squared.png",
    "label": "Videos for developers",
    "url": "https://developers.redhat.com/videos"
    },
    {
    "iconUrl": "<svg xmlns='http://www.w3.org/2000/svg' xml:space='preserve' width='2048' height='2048' style='shape-rendering:geometricPrecision;text-rendering:geometricPrecision;image-rendering:optimizeQuality;fill-rule:evenodd;clip-rule:evenodd'><defs><style>.fil0{fill:none}.fil4{fill:#bdbdbd;fill-rule:nonzero}</style></defs><g id='Layer_x0020_1'><path class='fil0' d='M0 0h2048v2048H0z'/><path class='fil0' d='M255.999 255.999h1536v1536h-1536z'/><path class='fil0' d='M256 256h1536v1536H256z'/><g id='_342647616'><path id='_342648000' style='fill:#e53935;fill-rule:nonzero' d='m273.04 666.226 737.28-367.843 13.68-6.824 13.68 6.824 737.28 367.843 17.04 8.503v234.834L993.281 1418.52 255.999 909.563V674.729z'/><path id='_342647880' style='fill:#fff' d='M609.28 711.961h829.439V1541.4H609.28z'/><path id='_342647808' style='fill:#c62828;fill-rule:nonzero' d='m1024 1279.73 723.6-361.079 44.4-22.156v859.945H255.999V896.495l44.402 22.156z'/><path id='_342647736' class='fil4' d='M1331.2 896.285H716.716v-61.442H1331.2z'/><path id='_342647688' class='fil4' d='M1203.22 1049.88H844.698v-61.439h358.522z'/></g></g></svg>",
    "label": "Mailing List",
    "url": "https://groups.google.com/g/xyz"
    },
    ]
   }
   ]

Procedure

1. In the Red Hat OpenShift Container Platform web console, click +Add > Import from Git.

2. Enter the URL of your Git repository into the Git Repo URL field.

   To use the red-hat-developer-hub-customization-provider service, add the URL for the red-hat-developer-hub-customization-provider repository or your fork of the repository containing your customizations.

3. On the General tab, enter red-hat-developer-hub-customization-provider in the Name field and click Create.

4. On the Advanced Options tab, copy the value from Target Port.

   Note

   Target Port automatically generates a Kubernetes or OpenShift Container Platform service to communicate with.

5. Add the following code to the app-config.yaml file:

   proxy:
     endpoints:
       # Other Proxies
       # customize developer hub instance
       '/developer-hub':
         target: ${HOMEPAGE_DATA_URL} # For example: http://<SERVICE_NAME>:8080, such as http://rhdh-customization-provider:8080
         changeOrigin: true
         # Change to "false" in case of using self-hosted cluster with a self-signed certificate
         secure: true

   Note

   The red-hat-developer-hub-customization-provider service contains the 8080 port by default. If you are using a custom port, you can specify it with the 'PORT' environmental variable in the app-config.yaml file.

6. Replace the HOMEPAGE_DATA_URL by adding the URL to rhdh-secrets or by directly replacing it in your custom ConfigMap.
7. Delete the Developer Hub pod to ensure that the new configurations are loaded correctly.

Verification

1. To view the service, go to the OpenShift Container Platform web console and click Networking > Service.

   Note

   You can also view Service Resources in the Topology view.

2. Ensure that the provided API URL for the Home page returns the data in JSON format as shown in the following example:

   [
     {
       "title": "Dropdown 1",
       "isExpanded": false,
       "links": [
         {
           "iconUrl": "https://imagehost.com/image.png",
           "label": "Dropdown 1 Item 1",
           "url": "https://example.com/"
         },
         {
           "iconUrl": "https://imagehost2.org/icon.png",
           "label": "Dropdown 1 Item 2",
           "url": ""
         }
       ]
     },
     {
       "title": "Dropdown 2",
       "isExpanded": true,
       "links": [
         {
           "iconUrl": "http://imagehost3.edu/img.jpg",
           "label": "Dropdown 2 Item 1",
           "url": "http://example.com"
         }
       ]
     }
   ]

   Note

   If the request call fails or is not configured, the Developer Hub instance falls back to the default local data.

3. If the images or icons do not load, then allowlist them by adding your image or icon host URLs to the Content Security Policy (CSP) img-src in your custom ConfigMap as shown in the following example:

   kind: ConfigMap
   apiVersion: v1
   metadata:
     name: app-config.yaml
   data:
     app-config.yaml: |
       app:
         title: Red Hat Developer Hub
       backend:
         csp:
           connect-src:
             - "'self'"
             - 'http:'
             - 'https:'
           img-src:
             - "'self'"
             - 'data:'
             - <image host url 1>
             - <image host url 2>
             - <image host url 3>
       # Other Configurations

Procedure

1. From the Developer Hub web console, click the down arrow next to your profile name, then click Settings.

2. From the Appearance panel, click the language dropdown to select your language of choice.

   

Procedure

1. Create a JSON file containing the translation strings that you want to override, as shown in the following example:

   allTranslations.json fragment with translation string overrides

   {
     "plugin.global-floating-action-button": {
       "en": {
         "fab.quay.label": "QUAY EN JSON",
         "fab.rbac.label": "RBAC EN JSON",
         "fab.rbac.tooltip": "RBAC EN tooltip JSON"
       },
       "fr": {
         "fab.quay.label": "QUAY French JSON",
         "fab.quay.tooltip": "QUAY french tooltip JSON",
         "fab.rbac.label": "RBAC French JSON",
         "fab.rbac.tooltip": "RBAC french tooltip JSON"
       }
     },
     "plugin.global-header": {
       "en": {
         "applicationLauncher.developerHub": "{product-short} EN JSON"
       },
       "fr": {
         "applicationLauncher.developerHub": "{product-short} French JSON"
       }
     }
   }

2. Log in to your cluster and create a config map for your translations override strings:

   $ oc create configmap all-translations \
       --from-file=/<path_to>/allTranslations.json

3. Update your deployment configuration based on your installation method:

   Note

   As shown in the following examples, we recommend that you use the same mount path for your allTranslations.json file and any other override files that you create, for example /opt/app-root/src/translations.

   1. For an Operator-installed RHDH instance, update your Backstage custom resource (CR). For more information about configuring a CR, see Using the Red Hat Developer Hub Operator to run Developer Hub with your custom configuration.

      1. In the spec.application.extraFiles section, add the translations custom app configuration as shown in the following example:

         Backstage custom resource fragment

         apiVersion: rhdh.redhat.com/v1alpha5
         kind: {product-custom-resource-type}
         spec:
           application:
             extraFiles:
               mountPath: /opt/app-root/src/translations
               configMaps:
                 - name: all-translations

   2. For a Helm-installed RHDH instance, update your Developer Hub Backstage Helm chart to mount in the Developer Hub filesystem your files from the all-translations config map:

      1. In the Developer Hub Helm chart, go to Root Schema → Backstage chart schema → Backstage parameters → Backstage container additional volume mounts.

      2. Select Add Backstage container additional volume mounts and add the following values:

         mountPath

         /opt/app-root/src/translations

         name

         all-translations

      3. Add the translations to the Backstage container additional volumes in the Developer Hub Helm chart:

         name

         all-translations

         configMap

         defaultMode

         420

         name

         all-translations

4. Update the i18n section to your custom Developer Hub app-config.yaml configuration file to include the following translation override file:

   app-config.yaml fragment with localization i18n fields

   i18n:
     locales: # List of supported locales. Must include en, otherwise the translation framework will fail to load.
       - en
       - fr
       - it
       - ja
     defaultLocale: en # Optional. Defaults to en if not specified.
     overrides: # List of JSON translation files applied in order (last file wins).  Each file may override/add translations for one or more plugins/locales
       - /opt/app-root/src/translations/all-translations.json

Procedure

1. Create the following translation files in your plugin’s src/translations/ directory:

   src/translations/ref.ts English reference

   import { createTranslationRef } from "@backstage/core-plugin-api/alpha";
   
   export const myPluginMessages = {
    page: {
      title: "My Plugin",
      subtitle: "Plugin description",
    },
    common: {
      exportCSV: "Export CSV",
      noResults: "No results found",
    },
    table: {
      headers: {
        name: "Name",
        count: "Count",
      },
    },
   };
   
   export const myPluginTranslationRef = createTranslationRef({
    id: "plugin.my-plugin",
    messages: myPluginMessages,
   });

   src/translations/de.ts German translation

   import { createTranslationMessages } from "@backstage/core-plugin-api/alpha";
   import { myPluginTranslationRef } from "./ref";
   
   const myPluginTranslationDe = createTranslationMessages({
    ref: myPluginTranslationRef,
    messages: {
      "page.title": "Mein Plugin",
      "page.subtitle": "Plugin-Beschreibung",
      "common.exportCSV": "CSV exportieren",
      "common.noResults": "Keine Ergebnisse gefunden",
      "table.headers.name": "Name",
      "table.headers.count": "Anzahl",
    },
   });
   
   export default myPluginTranslationDe;

   src/translations/fr.ts French translation

   import { createTranslationMessages } from "@backstage/core-plugin-api/alpha";
   import { myPluginTranslationRef } from "./ref";
   
   const myPluginTranslationFr = createTranslationMessages({
    ref: myPluginTranslationRef,
    messages: {
      "page.title": "Mon Plugin",
      "page.subtitle": "Description du plugin",
      "common.exportCSV": "Exporter CSV",
      "common.noResults": "Aucun résultat trouvé",
      "table.headers.name": "Nom",
      "table.headers.count": "Nombre",
    },
   });
   
   export default myPluginTranslationFr;

   src/translations/index.ts Translation resource

   import { createTranslationResource } from "@backstage/core-plugin-api/alpha";
   import { myPluginTranslationRef } from "./ref";
   
   export const myPluginTranslations = createTranslationResource({
    ref: myPluginTranslationRef,
    translations: {
      de: () => import("./de"),
      fr: () => import("./fr"),
    },
   });
   
   export { myPluginTranslationRef };

2. Create translation hooks file, as follows:

   src/hooks/useTranslation.ts Translation hooks

   import { useTranslationRef } from "@backstage/core-plugin-api/alpha";
   import { myPluginTranslationRef } from "../translations";
   
   export const useTranslation = () => useTranslationRef(myPluginTranslationRef);

3. Update your plugin components to replace hard-coded strings with translation calls as shown in the following example:

   Before (hard-coded):

   const MyComponent = () => {
    return (
      <div>
        <h1>My Plugin</h1>
        <button>Export CSV</button>
      </div>
    );
   };

   After (translated):

   import { useTranslation } from '../hooks/useTranslation';
   
   const MyComponent = () => {
    const { t } = useTranslation();
   
    return (
      <div>
        <h1>{t('page.title')}</h1>
        <button>{t('common.exportCSV')}</button>
      </div>
    );
   };

4. (Optional) If your content contains variables, use interpolation:

   // In your translation files
   'table.pagination.topN': 'Top {{count}} items'
   
   // In your component
   const { t } = useTranslation();
   const message = t('table.pagination.topN', { count: '10' });

5. (Optional) If your content contains dynamic translation keys (for example, from your plugin configuration):

   // Configuration object with translation keys
   const CARD_CONFIGS = [
    { id: 'overview', titleKey: 'cards.overview.title' },
    { id: 'details', titleKey: 'cards.details.title' },
    { id: 'settings', titleKey: 'cards.settings.title' },
   ];
   
   // In your component
   const { t } = useTranslation();
   
   const CardComponent = ({ config }) => {
    return (
      <div>
        <h2>{t(config.titleKey as any)}</h2>
        {/* Use 'as any' for dynamic keys */}
      </div>
    );
   };

6. Export the translation resources

   src/alpha.ts file fragment

   // Export your plugin
   export { myPlugin } from "./plugin";
   
   // Export translation resources for the application
   export { myPluginTranslations, myPluginTranslationRef } from "./translations";

7. Update your dynamic-plugins.default.yaml file, as follows:

   dynamic-plugins.default.yaml file fragment

   backstage-community.plugin-my-plugin:
    translationResources:
      - importName: myPluginTranslations
        ref: myPluginTranslationRef
        module: Alpha

8. Update your package.json file as follows:

   package.json file fragment

   "exports": {
       ".": "./src/index.ts",
       "./alpha": "./src/alpha.ts",
       "./package.json": "./package.json"
     },
     "main": "src/index.ts",
     "types": "src/index.ts",
     "typesVersions": {
       "*": {
         "alpha": [
           "src/alpha.ts"
         ],
         "package.json": [
           "package.json"
         ]
       }
     }