This playbook outlines the steps to create a plugin for Backstage that integrates with GitHub to do user specified tasks.
- GitHub repository URL.
- Access token with appropriate permissions for accessing the repository.
- 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>
. - Ask user to provide the
GitHub repository URL
andaccess token
if not already provided. - Update the
app-config.yml
file with the GitHub access token by adding the following:
integrations:
github:
- host: github.com
token: <github-access-token>
- 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 existing components inside the
plugins/<use-case>/src/components
directory. - Create a new component folder inside components
components/<use-case>
. - create a new component
index.tsx
insidecomponents/<use-case>
. - Use
api.github.com/repos/<owner>/<repo>/<use-case>
to fetch data from the GitHub API. - Implement the plugin-specified features using the generated
<use-case>Requirements.md
file, ui-ux research files and the failing test cases. - Implement the plugin-specified features using React without
githubAuthApi
orgithub oAuth
use github token directly. - Add necessary hooks for fetching data from the GitHub API in the
plugins/<use-case>/src/hooks
directory. - Add necessary utility funtions in the
plugins/<use-case>/src/utils
directory.
- 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:
- 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.
- Do not change port 3000 and port 7007 in the app-config.yaml file.
- Never Create a fresh Backstage project for the plugin.
- Do not change the ports in the
app-config.yml
file of 3000 and 7007. - Ignore the Invalid Host/Origin header error in the browser console.
- Ignore the 101 ws error on the ngrok backend terminal.
- No need for github oAuth app clientID and client secret for the plugin use github token directly.
- No need for a backend Secret
- 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
- Ensure that the access token used for GitHub integration has appropriate permissions.
- Do not use React.FC for any components.
- Do not push anything on Git Hub.
- Keep the plugin structure organized and follow best practices.
- Utilize TypeScript for type safety and better development experience.
- Document any additional features or configurations provided by the plugin.
- Never Create a fresh Backstage project for the plugin.