Certified Backstage Associate cheat sheet

Scaffold a new instance with npx @backstage/create-app@latest; the CLI prompts for an app name and creates a directory containing the frontend (packages/app), backend (packages/backend), and plugin packages.

Run the local dev environment with yarn dev from the repo root; this starts both the frontend (default port 3000) and backend (default port 7007) with hot reload.

Add a plugin dependency with yarn add --cwd packages/app <plugin-package> for frontend plugins or yarn add --cwd packages/backend <plugin-package> for backend plugins, then register it in the appropriate packages/*/src entry file.

The backend is composed in packages/backend/src/index.ts; each plugin is registered by calling its createRouter/createService factory and mounting it with apiRouter.use(...) or the newer backend system's addRouter.

Frontend plugins are typically exposed as createPlugin({ id, routes, apis }) and imported into the app's App.tsx via createApp({ plugins: [...] }) or by adding route elements.

Use yarn tsc (or yarn tsc:full) to type-check the whole workspace; yarn lint runs ESLint, and yarn test runs Jest across packages.

The backstage.json file at the repo root records the Backstage release version; use yarn backstage-cli versions:bump to update dependencies to a newer release.

New frontend plugins can be scaffolded with yarn new (or yarn backstage-cli new), which prompts for plugin type (frontend-plugin, backend-plugin, etc.) and generates boilerplate under plugins/.

The app-config.yaml at the repo root is the base configuration; environment-specific overrides live in app-config.local.yaml (git-ignored) or app-config.production.yaml.

Backstage's backend is a Node.js service (Express-based) that typically runs on port 7007; it must be reachable by the frontend for API calls and by the catalog for entity processing.

The catalog database is configured under backend.database in app-config.yaml; supported clients include better-sqlite3 (dev), pg (PostgreSQL), and mysql2 (MySQL).

For production, set backend.database.client to pg or mysql2 and supply connection details via environment variables (POSTGRES_HOST, POSTGRES_USER, POSTGRES_PASSWORD) referenced in config.

Authentication providers are configured under auth.providers; each provider (GitHub, Google, Okta, etc.) needs a client ID/secret and a redirect URL pointing at <frontend-url>/api/auth/<provider>/handler/frame.

The frontend is a static single-page app built with yarn build and served by any static host (e.g., Nginx, S3+CloudFront); it calls the backend via the backend.baseUrl config value.

backend.listen controls the host/port the backend binds to; set backend.listen.port and backend.listen.host explicitly in containerized deployments.

Secrets should be supplied through environment variables and referenced in app-config.yaml using ${ENV_VAR} syntax; never commit secrets to app-config.yaml.

The TechDocs builder can run locally (techdocs.builder: 'local') or in CI ('external'); external builds require a configured publisher such as awsS3, googleGcs, or azureBlobStorage.

Health and readiness endpoints are exposed by the backend at /healthcheck; use these for Kubernetes liveness/readiness probes.

Entities are described by YAML manifests with apiVersion: backstage.io/v1alpha1 (or backstage.io/v1beta1 for newer kinds) and a kind such as Component, API, System, Domain, Group, User, Resource, or Location.

Every entity requires metadata.name (unique within its kind and namespace) and metadata.namespace (defaults to default); metadata.uid is assigned by the catalog.

spec.type classifies a Component (e.g., service, website, library); spec.lifecycle records its stage (e.g., production, experimental, deprecated).

Ownership is expressed with spec.owner referencing a Group or User entity name; spec.system links a Component to a System, and spec.domain links a System to a Domain.

Relations are derived from fields such as spec.owner, spec.system, spec.dependsOn, spec.providesApis, and spec.consumesApis; they appear on the entity page as the relationship graph.

Entities are ingested via catalog.locations in app-config.yaml, each with a type (url, file, github, gitlab, bitbucket, etc.) and a target; the processor reads the target and registers discovered entities.

The catalog.rules array in app-config.yaml controls which entities are allowed; each rule matches on kind (and optionally spec.type) and sets allow: [Component, System, ...].

Entity processing runs through a pipeline of processors (e.g., catalogProcessorPlaceholder, builtin-entity-relations) defined under catalog.processors; custom processors can be added.

The catalog API exposes GET /api/catalog/entities for listing and GET /api/catalog/entities/by-name/<kind>/<namespace>/<name> for a single entity; the frontend uses catalogApiRef to query it.

The frontend theme is customized via createTheme from @backstage/theme; pass a theme object to createApp({ theme: [...] }) and optionally provide light/dark variants.

Override the app's sidebar and page layout by supplying a custom components object to createApp, e.g., SignInPage, Router, or Sidebar.

Entity pages can be extended with EntityLayout.Route entries inside packages/app/src/components/catalog/EntityPage.tsx; add custom tabs by importing your component and adding a route.

The entityPage customization uses EntityLayout, EntitySwitch, and isKind/isComponentType guards to render different layouts per entity kind or type.

Custom API clients are defined with createApiRef and provided to the app via apis in createApp or ApiProvider; components consume them with useApi.

Backend plugins can be customized by wrapping the default router or replacing it in packages/backend/src/index.ts; use createServiceFactory to override service implementations.

The app-config.yaml app section controls branding: app.title sets the browser title, and app.baseUrl sets the frontend base path.

Custom Scaffolder actions are registered by creating a createTemplateAction and adding it to the scaffolder backend plugin's actions list.

The @backstage/plugin-catalog-react package provides hooks like useEntity, useEntityOwnership, and useRelatedEntities for building custom entity page content.