4.4. Creating a TechDocs add-on

Procedure

1. In the terminal, navigate to the root folder of the repository where you want to create your new plugin.

2. To create a new front-end plugin, run the following command:

   yarn new

   Example output

   ? What do you want to create? plugin - A new frontend plugin
   ? Enter the ID of the plugin [required]

3. In the terminal prompt, type a name for the new plugin. For example:

   ? Enter the ID of the plugin [required] <new_plugin_for_techdocs_add-on>

   Example output

   Successfully created plugin

   Result

   In the plugins directory, a sub-directory with the same name that you gave to your plugin is automatically generated. The directory contains all of the files that you need to configure to create your new plugin.

4. In the terminal, navigate to your new plugin directory. For example:

   cd plugins/<new_techdocs_add-on_directory>

5. Add the`@backstage/plugin-techdocs-react` package to get frontend utilities for TechDocs add-ons. For example:

   yarn add @backstage/plugin-techdocs-react

6. In the directory containing the components of your custom TechDocs add-on, delete any default files or file components that are not required for your add-on, such as the routes.ts file or components of the index.tsx and plugins.ts files.

7. In the plugins.ts file, add the following code:

   import { createPlugin } from '@backstage/core-plugin-api';
   import { createTechDocsAddonExtension } from '@backstage/plugin-techdocs-react';
   
   export const <new_plugin_for_techdocs_add-on> = createPlugin({
     id: '<new_techdocs_add-on>',
    });
   
    /*
    *
    * @public
    */
   export const <new_techdocs_add-on> = <new_plugin_for_techdocs_add-on>.provide(
    createTechDocsAddonExtension<_<new_techdocs_addon_props>_>({
       name: '<new_techdocs_add-on>',
       location: TechDocsAddonLocations.Content,
       component: <new_techdocs_add-on_component>,
     }),
   );

   where

   <new_plugin_for_techdocs_add-on>

   Specifies the new plugin that you use to import the TechDocs add-on to your Red Hat Developer Hub instance.

   <new_techdocs_add-on>

   Specifies the custom TechDocs add-on that you want to create.

   <new_techdocs_addon_props> (Optional)

   Specifies the props for your new TechDocs add-on, as specified in your <new_techdocs_add-on>.tsx file, if applicable.

   <new_techdocs_add-on_component>

   Specifies the React component for the custom TechDocs add-on that you want to create. You will create this component in a .tsx file in a later step.

8. In the index.ts file, export the custom TechDocs add-on that you want to create by adding the following code:

   export { <new_plugin_for_techdocs_add-on>, <new_techdocs_add-on> } from './plugin';

9. Create a new <new_techdocs_add-on>.tsx file and add the code for your new TechDocs add-on component.

10. Create a new index.tsx file and use it to export your new TechDocs add-on component by adding the following code:

    export { <new_techdocs_add-on>, type <new_techdocs_addon_props>} from './<new_techdocs_add-on_directory>'

    where

    <new_techdocs_addon_props> (Optional)

    Specifies the props for your new TechDocs add-on, as specified in your <new_techdocs_add-on>.tsx file, if applicable.

11. In the plugins.ts file, import your new TechDocs add-on component.
12. Install and configure your new TechDocs add-on by following the steps in Installing and configuring a TechDocs add-on

Verification

1. Restart the RHDH application and verify that the plugin is successfully activated and configured.
2. Verify the application logs for confirmation and ensure the plugin is functioning as expected.