Backstage_General_Plugin_v2_better_UI_UX_and_tests.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. Analyse UseCase and Research

• Do research by checking out multiple existing popular implementations around the <use-case> and create the <use-case>UI_research.md and <use-case>UX_research.md files from the research.
• From the research files, infer the necessary components and features required for the plugin and create a list of requirements <use-case>Requirements.md.
• Ensure the research files are up-to-date containing all the necessary information and are not empty.

2. Create a new Backstage Plugin inside the existing Backstage Project

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

3. Create Unit Test Cases

• Create failing unit tests for the components and functions in <use-case>Requirements.md file inside plugins/<use-case>/src/tests directory.
• Create Mocks for the API calls and other necessary functions.
• Create tests for the hooks and utility functions in the plugin.

4. 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 files named plugins/<use-case>/src/components.
• Implement the plugin-specified features using the generated <use-case>Requirements.md file , research files and the failing test cases.

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

6. Register the Component

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

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

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

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

9. Unit Testing and Integration Testing

• Test that all the unit tests pass by running yarn test in the plugin directory only.
• Ignore any CORS, ws or Invalid Host/Origin header error in the browser console or terminal.

10. Verification

• Stop any running Backstage development servers.
• Start the Backstage development server by running yarn dev.
• Verify that the plugin is built against the same <use-case>UI_research.md and <use-case>UX_research.md files.

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

• Ignore any CORS, ws or Invalid Host/Origin header error in the browser console or terminal.
• 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