Backstage Project Assistant
Expert assistant for working with Backstage applications - open platforms for building developer portals. Specializes in monorepo structure, GitHub catalog integration, and the modern backend plugin system.
What This Skill Does
This skill provides comprehensive guidance for developing and maintaining Backstage applications, including:
Understanding the monorepo architecture with Yarn Berry workspacesWorking with the new backend plugin systemManaging GitHub integration for catalog discovery and authenticationHandling development, build, and deployment workflowsConfiguring environment-specific settingsEnvironment Context
When working with Backstage projects:
**Requirements:**
Node.js: 20 or 22Package manager: Yarn 4.4.1 (Berry)Database (dev): SQLite with in-memory storageDatabase (prod): PostgreSQL**Architecture:**
Monorepo with two package locations: `packages/` (core app) and `plugins/` (custom plugins)Backend uses modular plugin system with `backend.add()` pattern in `packages/backend/src/index.ts`Frontend is React SPA with Material-UIConfiguration uses layered approach with environment variable substitutionInstructions
1. Initial Project Setup and Dependency Management
When starting work or after checkout:
Always run `yarn install` to ensure dependencies are currentCheck Node.js version is 20 or 22Verify Yarn version is 4.4.1 (Berry)Look for `app-config.local.yaml` for local overrides (git-ignored)2. Development Workflow
For local development:
Start both frontend (port 3000) and backend (port 7007) with `yarn start`Run `yarn tsc` to type-check before committingUse `yarn test` for changed packages or `yarn test:all` for comprehensive testingRun `yarn lint` to check code qualityUse `yarn fix` to auto-fix linting issues3. Working with the Backend Plugin System
When modifying backend plugins:
All plugins register in `packages/backend/src/index.ts` using `backend.add()`Available plugins include: App, Proxy, Scaffolder, TechDocs, Auth, Catalog, Permission, Search, Kubernetes, NotificationsBackend runs on port 7007 in both dev and productionNode option `--no-node-snapshot` is required for Scaffolder compatibility (Node 20+)4. GitHub Integration
For catalog and authentication configuration:
Catalog auto-discovers repos in the configured organizationLooks for `catalog-info.yaml` files on `master` branchDiscovery runs every 30 minutesSupports Components, Systems, APIs, Resources, and LocationsRequires `GITHUB_TOKEN`, `GITHUB_CLIENT_ID`, and `GITHUB_CLIENT_SECRET` environment variables5. Configuration Management
When editing configuration:
Base dev config: `app-config.yaml`Local overrides: `app-config.local.yaml` (create if needed, git-ignored)Production config: `app-config.production.yaml`Use environment variable substitution for secretsProduction requires PostgreSQL variables: `POSTGRES_HOST`, `POSTGRES_PORT`, `POSTGRES_USER`, `POSTGRES_PASSWORD`6. Building and Testing
For builds:
Use `yarn build:backend` for backend onlyUse `yarn build:all` for all packagesRun `yarn tsc:full` for complete type checking without skipLibCheckExecute `yarn test:e2e` for Playwright end-to-end testsUse `yarn prettier:check` to verify code formatting7. Docker Deployment
When building Docker images:
Build from repository root: `docker build ../.. -f Dockerfile --tag backstage` (from `packages/backend`)Or use npm script: `yarn workspace backend build-image`Multi-stage build: dependency skeleton → install/build → minimal runtimeRuntime expects config files and environment variablesTechDocs uses Docker for local document generation8. Adding New Features
For scaffolding new components:
Run `yarn new` for interactive CLI to create plugins/packagesCustom plugins go in `plugins/` directoryRegister backend plugins in `packages/backend/src/index.ts`Follow existing patterns for consistency9. Production Considerations
Before production deployment:
Switch from SQLite to PostgreSQLCustomize permission model (currently allow-all)Set external URLs in `app-config.production.yaml`Configure all required environment variablesReview security settings for GitHub OAuth10. Troubleshooting Common Issues
When encountering problems:
Run `yarn clean` to remove build artifactsVerify Node.js and Yarn versions match requirementsCheck that `GITHUB_TOKEN` has proper permissionsEnsure database connection details are correct for environmentReview backend logs on port 7007Confirm frontend is accessing correct backend URLImportant Notes
**Branch Strategy**: Main branch may be `main` or `master` depending on repository**Ports**: Backend always on 7007, frontend on 3000 (dev only)**Permission Model**: Currently allow-all - must customize before production**TechDocs**: Requires Docker for local generation**Monorepo**: Use workspace commands like `yarn workspace backend [command]`Example Usage
**Starting development:**
```bash
yarn install
yarn start
Frontend: http://localhost:3000
Backend: http://localhost:7007
```
**Type checking before commit:**
```bash
yarn tsc
yarn lint
yarn test
```
**Building Docker image:**
```bash
cd packages/backend
docker build ../.. -f Dockerfile --tag backstage
```
**Creating new plugin:**
```bash
yarn new
Follow interactive prompts
```