GitHub Copilot Instructions for Backstage

copilot-instructions.md

Tone Of Voice

Minimalist and concise. It's a conversation among senior software architects. I'll explicitly ask for deep explanations.

Tech Stack

• This is a Spotify's Backstage instance (v1.38.0)
• Monorepo managed with Yarn Workspaces
• Postgres 17 via Docker container

Libraries

This section contains relevant libraries that are added to the project.

• React
• TypeScript
• Material UI
• Node.js
• ESLint
• Prettier
• Playwright
• Backstage Core: @backstage/cli, @backstage/core-app-api, @backstage/core-components, @backstage/core-plugin-api, @backstage/theme
• Backstage Frontend Plugins: @backstage/plugin-catalog, @backstage/plugin-techdocs, @backstage/plugin-scaffolder, @backstage/plugin-search, @backstage/plugin-user-settings, @backstage/plugin-catalog-graph, @backstage/plugin-catalog-import, @backstage-community/plugin-tech-radar
• Backstage Backend Plugins: catalog, scaffolder, auth, search, techdocs, proxy, app (as configured in packages/backend/src/index.ts)

Coding Style & React

• adopt code styling defaults from eslintrc.js and .vscode/settings.json
• prefer arrow functions const a = () => {} over function a () {}
• always split hooks, pure ui components, and containers in separated files
• avoid importing React if not strictly required by the specific implementation
• avoid long files: when a component or file reaches ~80 lines of code, reason how to break it down into sub-components, custom hooks, or utility functions

A React Component Folder structure:

• ComponentName/
  • ComponentName.tsx // the high level component where ui and state are linked
  • ComponentNameUI.tsx // handle all presentational stuff in small components
  • useComponentName.ts // handle all state & behaviors in small custom hooks
  • index.ts // export the main symbols

Project Folders Layout:

• ./packages:
  • app: Frontend application (React, TypeScript)
  • backend: Backend service (Node.js, TypeScript)
• ./plugins: Custom or third-party Backstage plugins

Core Rules

You have two modes of operation:

1. Plan mode - You will work with the user to define a plan, you will gather all the information you need to make the changes but will not make any changes
2. Act mode - You will make changes to the codebase based on the plan

• You start in plan mode and will not move to act mode until the plan is approved by the user.
• You will print # Mode: PLAN when in plan mode and # Mode: ACT when in act mode at the beginning of each response.
• Unless the user explicity asks you to move to act mode, by typing ACT you will stay in plan mode.
• You will move back to plan mode after every response and when the user types PLAN.
• If the user asks you to take an action while in plan mode you will remind them that you are in plan mode and that they need to approve the plan first.
• When in plan mode always output the full updated plan in every response.

Memory Bank

This file (.github/copilot-instructions.md) serves as your memory bank to keep an active documentation on the project. The goal is to facilitate your agentic approach on new tasks.

When prompted by update memory or update memory bank skip the plan/act flow and act directly.

Do:

1. review the current content of the Memory Bank from .github/copilot-instructions.md
2. review the current chat context for new relevant information (run to each section and reason if there are new information to merge in)
3. update the Memory Bank accordingly to .github/copilot-instructions.md

Features

Information about features existing in this project

• Standard Backstage developer portal setup.
• Frontend application (packages/app) serving the UI.
• Backend service (packages/backend) providing APIs and integrating plugins.
• Catalog integration for managing software components, APIs, resources, etc.
• TechDocs integration for displaying documentation alongside code.
• Scaffolder integration for creating new components from templates.
• Search functionality across the portal.
• User settings customization.
• Catalog import functionality.
• Visual dependency graph for catalog entities.
• Tech Radar plugin integration (@backstage-community/plugin-tech-radar).
• Custom themes (vapor-light, vapor-dark) implemented with a tech blue (#007bff) primary color.
  • Themes defined in packages/app/src/theme/.
  • Applied in packages/app/src/App.tsx.
  • Logo components (LogoFull.tsx, LogoIcon.tsx) updated to use the theme's primary color.
• Example entities, org structure, and a scaffolder template provided.
• Configuration managed via app-config.yaml files (including DB setup for SQLite/PostgreSQL and GitHub integration).
• Local development database setup using PostgreSQL 17 via Docker Compose (docker-compose.yml), configured in app-config.local.yaml.
• Dockerfile for containerizing the backend.
• E2E testing setup with Playwright.
• Custom homepage implementation using the Backstage home plugin (@backstage/plugin-home).
  • Configured in packages/app/src/components/home/HomePage.tsx.
  • Set as the default route in packages/app/src/App.tsx using HomepageCompositionRoot.
  • Updated sidebar navigation in packages/app/src/components/Root/Root.tsx to include separate "Home" and "Catalog" entries.

Backlog

Information about features that are planned to be implemented

• next task
• next task

Last Feature

Customized the Backstage sidebar in the vapor-light theme to match the main content background color with a visible right border. Implemented hover effects that change link color to primary blue with subtle background changes. Styled horizontal dividers to match the border color. All changes were implemented using theme component overrides targeting specific elements within the sidebar structure.

Current Focus

Describe what is the focus of the current task (if any task is still open): None.

Struggles

Describe what are the problems that seem to be difficult to solve (if any): None.

Tech Debt

Describe what technical debt we are building (if any): None.