Backstage plugins: printable course notes
Build a Backstage plugin end to end: the backend and frontend systems, a backend plugin with an API, a database, config and a schedule, tests, an extension point and a module, a frontend plugin with a utility API, an entity card and tab, permissions, and a capstone.
These pages are the same content as the interactive course, on one page per module, for reading and printing.
Four pieces
| Piece | What it is |
|---|---|
| See the end result | Not the first step: a 20-minute run of the finished plugins from the reference repo. Useful to know where you are heading. |
| Full course | 10 modules from yarn new to a permissioned plugin: backend, database, scheduler, tests, an extension point, a frontend plugin, entity cards, permissions and a capstone. |
| Reference repo | The finished plugins in portal/plugins, at tag course-2-done. You copy a few files from it. |
| Your portal repo | The portal repo from the first course. Every plugin goes in its plugins/ folder. |
Your setup
Commands in these notes use these values (shared with the interactive course, stored only in this browser).
Outline
| Module | Part | Time | You are | You will |
|---|---|---|---|---|
| 00 Orientation: how a Backstage plugin is built | Orientation | 20 min | Platform and product | Know the pieces of the backend and frontend systems, the packages a full plugin is split into, and the readiness plugin you will build. Get your portal from the first course running again. |
| 01 A backend plugin with an API | The backend plugin | 45 min | Platform team | Generate a backend plugin and a common package, write an HTTP API that reads the catalog as the caller, and call it with a token. |
| 02 Database, config and a schedule | The backend plugin | 60 min | Platform team | Store scorecards in the plugin's own Postgres database, make the plugin configurable with a schema, and evaluate every component on a schedule. |
| 03 Test the backend plugin | The backend plugin | 30 min | Platform team | Start the real plugin in a test backend with mocked services and test it over HTTP. |
| 04 An extension point and a module | The backend plugin | 45 min | Platform and product | Let other teams add checks without touching the plugin: an extension point in a -node package, and team-checkout's first module. |
| 05 A frontend plugin in the new frontend system | The frontend plugin | 40 min | Platform team | Generate a frontend plugin, give it a page with a blueprint, find it in the app, and move it with config alone. |
| 06 Talk to the backend: a utility API | The frontend plugin | 40 min | Platform team | Write an API client, provide it to the app with ApiBlueprint, and show every scorecard on the page. |
| 07 On the entity page: a card and a tab | The frontend plugin | 45 min | Platform and product | Put the scorecard where teams look: a card on each component's overview and a Readiness tab, with a pass score set in config. |
| 08 Permissions: who may evaluate | Secure and extend | 60 min | Platform team | Define permissions in the common package, enforce them in the backend, write a policy, and hide the button for people who may not use it. |
| 09 Capstone: team-checkout's ownership check | Secure and extend | 60 min | Platform and product | Without the steps: team-checkout adds a check that uses the catalog, gets checkout to 100, and the platform team proves it all works. |
Where the portal runs
Everything runs on your laptop with Node, Yarn and Docker, in the portal from the first course.
Between you and production
- Publish or own the packages: Decide per package: stays in the portal repo, or published to a private registry with its own versioning.
- CODEOWNERS per plugin folder: The platform team reviews the plugin; each team reviews its own modules.
- API reports: `yarn build:api-reports` on every pull request, so public API changes are reviewed on purpose.
- Tests against Postgres: `TestDatabases` from `@backstage/backend-test-utils` runs the store tests on the database you use in production.
- Conditional permissions: Rules such as "owners may evaluate their own components", instead of one group.
- Notifications: Tell the owning team when a score drops, with the notifications plugin.
- Paging: Page `/scorecards` in the API and the table once the catalog has thousands of components.
- Metrics and alerts: Count evaluations and failed checks, and alert when the scheduled job fails.
- Frontend tests in CI: Render the card, tab and page with fake APIs on every pull request.
- Monthly upgrades: `versions:bump` keeps the plugin packages on the same Backstage release as the app.