Cheat notes · Module 00 · Orientation
Orientation: how a Backstage plugin is built
A five-minute review for when you have done this module and want it back in your head. Open the full module for the steps and the lab, or the full text to print.
The idea
Plugin code gets a small set of building blocks with strict rules. In the backend: plugins, modules, services and extension points. In the frontend: plugins made of extensions, built from blueprints. Learn the blocks and every plugin, official ones included, looks the same.
Remember
- Backend plugin: one feature with its own API under
/api/<pluginId>and its own database. It declares the services it needs (logger, database, scheduler) and gets them injected. - Module and extension point: a module adds to one plugin without changing its code, through an extension point the plugin offers. The platform owns the plugin; other teams own modules.
- Frontend plugin: a list of extensions (a page, an API client, an entity card). Each is made from a blueprint and attaches to a place in the app.
- Package roles:
readiness-backend(the server),readiness(the UI),readiness-common(types and permissions both sides use),readiness-node(what backend modules import). - The readiness plugin: a production-readiness scorecard per component (has an owner, has docs, links a runbook, ...), on the entity page, extensible by teams.
Pitfalls
- Importing a backend package from the frontend. Shared types and permissions go in
-common, which both sides may import. - Putting every team's rule in the central plugin. Offer an extension point and let teams own modules.
Commands
docker start portal-db | Postgres from the first course |
set -a && . ./.env && set +a && yarn start | Start the portal with its environment |
Test yourself
Answer in your head first, then open the answer.
team-checkout needs one extra readiness check. Where does their code go?
A backend module that adds the check through the plugin's extension point.
Which package holds the types both frontend and backend use?
readiness-common.
How does a backend plugin get a database connection?
It declares the database service in its deps and gets one injected.
Where module 00 leaves you: Your portal runs on your laptop with Postgres, the catalog knows checkout, and the reference repo is up to date.