This playbook outlines the steps to create a plugin using Backstage.
- Repository for the Backstage project.
- 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.
- 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>
.
- Create failing unit tests for the components and functions in
<use-case>Requirements.md
file insideplugins/<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.
- 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.
- 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.
- Open the
dev/index.ts
file in the plugin directory. - Import and register the
<use-case>
component as a route:
- Add necessary changes in the
packages/backend/src/plugins/catalog.ts
file. - Update other necessary files in the backend to support the plugin.
- Update the
App.tsx
file in thepackages/app/src
directory. - Import the
<use-case>
component and add it to theApp.tsx
file. - Create a new route for the
<use-case>
component in the routes function.
- 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.
- 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.
- 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.
- 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.
- 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