common

General

• This is a NodeJS project
• The project mainly provides a customized version of https://github.com/backstage/backstage
• The application is deployed as Giant Swarm's developer portal both for Giant Swarm customers as well as Giant Swarm's internal use

Project Structure

• Monorepo: Uses Yarn workspaces with packages in packages/ and plugins in plugins/
• Packages:

- packages/app - Frontend application (React) - packages/backend - Main backend service - packages/backend-headless-service - Headless backend service - packages/backend-common - Shared backend utilities

• Custom Plugins:

- plugins/gs - Main Giant Swarm frontend plugin (largest plugin with 375+ files) - plugins/gs-backend - Backend plugin for GS functionality - plugins/flux & plugins/flux-react - Flux CD integration - plugins/kubernetes-react - Kubernetes utilities and hooks - plugins/ui-react - Shared UI component library - plugins/gs-common - Shared constants and utilities - Backend modules: auth-backend-module-gs, scaffolder-backend-module-gs, techdocs-backend-module-gs

Technology Stack

• Runtime: Node.js 20, 22, or 24 (recommended: 24)
• Package Manager: Yarn 4.10.3
• Language: TypeScript ~5.9.0
• Frontend: React 18, Material-UI v4, React Router v6
• Backend: Express 5, Backstage backend framework
• Database: PostgreSQL (production), SQLite (local dev)
• Testing: Jest, Playwright (E2E), Testing Library
• Build Tools: Backstage CLI, TypeScript compiler

Development Setup

• Devcontainer: Recommended development environment (VS Code devcontainer support)
• Environment Variables:

- Requires .env file (not checked in) - Secrets stored in 1Password secure notes - Uses env-cmd for loading environment variables - GitHub OAuth credentials in github-app-development-credentials.yaml (not checked in)

• Local Config: Copy app-config.local.yaml.example to app-config.local.yaml
• Database: Run PostgreSQL via Docker (see docs/development.md)
• HTTPS Support: Configure via certificate.yaml (see certificate.yaml.example)
• Prettier: Run yarn prettier:fix before committing code changes.

Code Organization & Naming Conventions

• Components: PascalCase (e.g., GSClustersPage, EntityGSDeploymentsContent)
• Hooks: camelCase with use prefix (e.g., useDeploymentStatusDetails, useFluxResources)
• Utilities: camelCase (e.g., generateUID, parseDate, toTitleCase)
• Plugins: lowercase with hyphens (e.g., gs, flux-react, kubernetes-react)
• Exports: Components exported with GS prefix for Giant Swarm customizations
• File Structure:

- Components organized by feature/domain in subdirectories - Each component directory typically contains: component file, index.ts, and sometimes tests - Hooks in hooks/ subdirectories - Utilities in utils/ subdirectories

Testing

• Unit Tests: Jest with .test.ts or .test.tsx naming convention
• E2E Tests: Playwright tests in e2e-tests/ directories
• Test Commands:

- yarn test - Run tests - yarn test:all - Run tests with coverage - yarn test:e2e - Run Playwright E2E tests

• Coverage: Reports generated in coverage/ directory
• Test Files: Located alongside source files or in setupTests.ts files

Code Quality & Linting

• Linting: ESLint with Backstage configuration
• Formatting: Prettier (Backstage config)
• Lint Commands:

- yarn lint - Lint changed files since origin/main - yarn lint:all - Lint all files - yarn fix - Auto-fix linting issues

• Pre-commit: lint-staged configured for automatic linting/formatting
• Type Checking:

- yarn tsc - Type check with incremental mode - yarn tsc:full - Full type check without skipping lib checks

Build & Deployment

• Build Commands:

- yarn build:all - Build all packages - yarn build:backend - Build backend only - yarn build:backend-headless-service - Build headless service

• Docker: Backend Dockerfile in packages/backend/Dockerfile
• Helm: Charts in helm/backstage/ directory
• CI/CD: CircleCI configuration (see .circleci/config.yml)
• Release Process: Two axes. The app (image + Helm chart) is released automatically by git-cliff from conventional-commit PR titles on merge to main; the @giantswarm/backstage-plugin- packages are published to npm via Changesets (add a .changeset/.md entry).

Dependencies & Patches

• Backstage Packages: Uses backstage:^ version specifier (managed by Backstage CLI)
• Patch Package: Uses patch-package for dependency patches (applied in postinstall)
• Resolutions: Custom resolutions for React types, CodeMirror versions, and other dependencies
• Dependency Updates: Renovate configured with grouped updates for Backstage packages

Configuration Files

• App Config: app-config.yaml (base), app-config.local.yaml (local overrides), app-config.production.yaml (production)
• TypeScript: tsconfig.json extends Backstage CLI config
• Prettier: Uses Backstage CLI Prettier config
• Package Manager: Yarn 4 with PnP support

Key Features & Integrations

• Authentication: GitHub OAuth, custom GS auth module
• Kubernetes: Full Kubernetes integration with custom React hooks and components
• Flux: Flux CD integration for GitOps workflows
• Scaffolder: Custom scaffolder templates and field extensions
• TechDocs: Custom TechDocs backend module
• Catalog: Custom catalog pages and entity cards
• Notifications: Backstage notifications integration
• Search: Backstage search with catalog and TechDocs modules
• Monitoring: Sentry integration, TelemetryDeck integration

Important Notes

• Secrets: Never commit .env, *-credentials.yaml, or certificate.yaml files
• Local Files: *.local.yaml files are gitignored
• Database: Uses in-memory SQLite for local dev, PostgreSQL for production
• Ports: Frontend on 3000, Backend on 7007
• Devcontainer: Includes Docker support for TechDocs generation
• Code Owners: Team Honeybadger (@giantswarm/team-honeybadger) owns all files