Backstage_plugin_dev.playbook.md

Playbook: Creating a New Plugin with Backstage

Overview

This playbook outlines the steps to create a plugin using Backstage.

What's Needed From User

• Repository for the Backstage project.

Procedure

1. Setup Backstage Plugin

• Infer the name of the plugin from the task or feature request from the provided prompt as <use-case>
• Navigate to the root directory of the Backstage project already set up and present in the home directory or provided by the user.
• Run yarn new --select plugin command to create a new plugin named <use-case>.

2. Implement Component

• Navigate to the created directory inside plugins (plugins/<use-case>).
• Remove the example components inside the plugins/<use-case>/src/components directory.
• Create a new component file named <use-case>.tsx.
• Implement the plugin-specified features in the <use-case>.tsx file using React.

3. Update the Plugin

• Update the src/routes.ts with plugin-id
• Update the src/plugin.ts with the component import and plugin-id.
• Update the src/index.ts with the plugin import.
• Update the src/types.ts directory with the necessary components.

4. Register the Component

• Open the dev/index.ts file in the plugin directory.
• Import and register the <use-case> component as a route:

5. Update the Backend

• Add necessary changes in the packages/backend/src/plugins/catalog.ts file .
• Update other necessary files in the backend to support the plugin.

6. Update Main App File

• Update the App.tsx file in the packages/app/src directory.
• Import the <use-case> component and add it to the App.tsx file.
• Create a new route for the <use-case> component in the routes function.

7. Import the plugin and update packages

• Import and update the plugin in the packages/app/src/components/catalog/EntityPage.tsx file.
• Import and update the plugin in the packages/app/src/components/Root/Root.tsx file.
• Import and update the plugin in the packages/app/src/components/Search/SearchPage.tsx file.

8. Test the Plugin

• Stop any running Backstage development servers.
• Start the Backstage development server by running yarn dev.
• Check for the plugin on the catalog page.
• Navigate to the <ngrok-frontend-url>/<use-case> endpoint in the browser to test the plugin.

9. Readme for User

• Update the README.md file in the plugin directory with the following steps:
  • Instructions to create a new plugin.
  • Details on implementing the component.
  • Any other necessary steps or changes needed by the user.

Advice and Pointers

• Do not change port 3000 and port 7007 in the app-config.yaml file.
• Do not change the ports in the app-config.yml file of 3000 and 7007.
• Never Create a fresh Backstage project for the plugin.
• Ignore the Invalid Host/Origin header error in the console while testing the plugin.
• Ignore the 101 ws error on the ngrok backend terminal.
• Never restart currently running ngrok tunnels.
• Follow the latest react and backstage conventions for creating components https://react.dev/blog/2023/03/16/introducing-react-dev
• Do not use React.FC for any components.
• Do not push anything on GitHub.
• Keep the plugin structure organized and follow best practices.
• Utilize TypeScript for type safety and better development experience.
• Test the plugin thoroughly in a development environment before deploying it to production.
• Document any additional features or configurations provided by the plugin.
• Infer the name of the plugin from the task or feature request prompt provided.
• No need for a backend Secret