Cheat notes · Module 01 · The portal and its catalog

Create the app and find your way around

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

The generated app is small: one file wires the backend, one wires the frontend, one YAML file configures both, and everything else is npm packages. Learn to go from "I see this in the UI" to "this line adds it".

Remember

The monorepo: packages/app (React frontend), packages/backend (Node backend), plugins/ (your plugins), app-config.yaml (config for both), tied together by Yarn workspaces.
Backend plugins: one process. packages/backend/src/index.ts adds each plugin with backend.add(import(...)); each serves its API under /api/<pluginId>.
Frontend extensions: the app is built from extensions (pages, nav items, entity tabs). Installed plugin packages are discovered (app.packages: all); App.tsx adds the rest. The Visualizer lists them, e.g. page:catalog.
Ports: yarn start runs the frontend on 3000 and the backend on 7007.
Every request is authenticated: curl without a token gets 401, even on your laptop.
Pinned: create-app 0.9.3 generates Backstage 1.56.0, recorded in backstage.json.

Pitfalls

Commenting out a backend.add line that "looks unused": the portal starts fine, but the feature behind it answers 404 (here: templates list, but Choose fails, because the list comes from the catalog and running comes from the scaffolder).
Expecting data to survive a restart: the generated app uses in-memory SQLite and example data until module 02.

Commands

`npx @backstage/[email protected] --path portal`	Generate the app
`yarn start`	Start frontend (3000) and backend (7007). Leave this terminal running
`grep -n "target:" app-config.yaml`	Where the catalog reads from (`catalog.locations`)
`grep -n "scaffolder" packages/backend/src/index.ts`	Which backend plugins are added
`curl -s -o /dev/null -w "%{http_code}\n" localhost:7007/api/catalog/entities`	`401` = alive, wants a token; `404` = plugin missing

Test yourself

Answer in your head first, then open the answer.

Where is a backend plugin turned on?

A backend.add(import(...)) line in packages/backend/src/index.ts.

Why does curl localhost:7007/api/catalog/entities return 401?

Every backend request needs a token: from a user, another plugin or a configured script.

The template list shows, but Choose fails with 404. Where is the problem?

The backend: the plugin serving /api/scaffolder is not loaded.

Your fastest debugging habit for a failing page?

Open the browser's network tab: /api/<pluginId>/... names the plugin, and 401, 403, 404 each point somewhere different.

Where module 01 leaves you: A portal repo on GitHub with the generated app, running on your laptop at http://localhost:3000 with example data and guest sign-in.