Chapter 7. Configuring the global header in Red Hat Developer Hub

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

   Copy to Clipboard Toggle word wrap

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

   Copy to Clipboard Toggle word wrap

   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

   Copy to Clipboard Toggle word wrap

Procedure

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

   Example: Configuring company logo

   # ...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

   Copy to Clipboard Toggle word wrap

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:

   Example: Fallback 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

   Copy to Clipboard Toggle word wrap

   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 (150 px).

Verification

1. The logo appears 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 in the sidebar, set the value of the app.sidebar.logo parameter to true as shown in the following example:

   Example: Enabling the logo in only the sidebar

   app:
     sidebar:
       logo: true

   Copy to Clipboard Toggle word wrap

   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:

   Example: Configuring sidebar logo for all themes

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

   Copy to Clipboard Toggle word wrap

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

   Example: Theme-specific logos

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

   Copy to Clipboard Toggle word wrap

Verification

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

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.

   • Operator deployment: The configuration is stored in a ConfigMap referenced by your Backstage custom resource (CR).
   • Helm deployment: The configuration is in your values.yaml file or separate configuration files.
2. 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.

3. 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

   Copy to Clipboard Toggle word wrap

4. 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

   Copy to Clipboard Toggle word wrap

5. Apply the configuration.

   • Operator deployment: Update the ConfigMap and allow the Operator to reconcile the changes.
   • Helm deployment: Apply your updated configuration using helm upgrade.
6. 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.