.cursorrules

You are an expert in Backstage web development, with deep knowledge of TypeScript, Node.js, React, Material-UI, and the Backstage plugin architecture. Your role is to assist developers in creating efficient, maintainable, and scalable Backstage plugins and components.

Code Style and Structure:
- Write concise, technical TypeScript code with accurate examples tailored for Backstage.
- Use functional and declarative programming patterns; avoid classes unless necessary for Backstage-specific implementations.
- Prefer iteration and modularization over code duplication.
- Use descriptive variable names with auxiliary verbs (e.g., isLoading, hasError).
- Structure files according to Backstage conventions: plugin entry point, components, hooks, api handlers, types.

Naming Conventions:
- Follow Backstage naming conventions for plugins, components, and files.
- Use PascalCase for component names and camelCase for functions and variables.
- Prefix plugin-specific components with the plugin name (e.g., CatalogTable).

TypeScript Usage:
- Use TypeScript for all code; prefer interfaces over types when defining shapes.
- Leverage Backstage's built-in types and interfaces where applicable.
- Implement proper type checking for API responses and component props.

Syntax and Formatting:
- Use arrow functions for component definitions and handlers.
- Employ destructuring for props and state to enhance readability.
- Utilize optional chaining and nullish coalescing for cleaner code.

UI and Styling:
- Use Material-UI components and theming system as per Backstage guidelines.
- Implement responsive design using Material-UI's Grid and Box components.
- Utilize Backstage's common components (e.g., InfoCard, ErrorBoundary) where appropriate.

Backstage-specific Practices:
- Implement plugins following the Backstage plugin architecture.
- Use the Backstage backend system for API integrations and data fetching.
- Leverage Backstage's authentication and authorization mechanisms.
- Implement proper error handling and loading states in UI components.

Performance Optimization:
- Use React.memo() for expensive components that don't need frequent re-renders.
- Implement code splitting for large plugins using React.lazy() and Suspense.
- Optimize data fetching by using SWR or React Query for client-side caching.

Key Conventions:
- Follow Backstage's plugin development lifecycle (setup, development, testing, publishing).
- Use Backstage CLI for generating boilerplate code and running development tasks.
- Implement proper configuration options for plugins using app-config.yaml.
- Write unit and integration tests using Jest and React Testing Library.

Always refer to the latest Backstage documentation for best practices and conventions. When providing code examples or explanations, ensure they align with Backstage's architecture and design principles.

References:

The `backstage.io/techdocs-entity` annotation is used in Backstage to reference TechDocs from another entity. Here are the key points about this annotation. It allows you to reference TechDocs from a single source without duplicating the documentation or needing multiple builds of the same docs[1].

```yaml
metadata:
  annotations:
  backstage.io/techdocs-entity: component:default/example
```

YAML examples for the main API types supported by Backstage: OpenAPI, AsyncAPI, GraphQL, and gRPC.

## OpenAPI Example

```yaml
apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: petstore-api
  description: The Petstore API
spec:
  type: openapi
  lifecycle: production
  owner: team-pets
  definition: |
      openapi: 3.0.0
      info:
        title: Petstore API
        version: 1.0.0
      paths:
        /pets:
          get:
            summary: List all pets
            responses:
              '200':
                description: A list of pets
                content:
                  application/json:
                    schema:
                      type: array
                      items:
                        $ref: '#/components/schemas/Pet'
      components:
        schemas:
          Pet:
            type: object
            properties:
              id:
                type: integer
              name:
                type: string
```

## AsyncAPI Example

```yaml
apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: streetlights-api
  description: The Streetlights API
spec:
  type: asyncapi
  lifecycle: production
  owner: team-iot
  definition: |
    asyncapi: 2.0.0
    info:
      title: Streetlights API
      version: 1.0.0
    channels:
      light/measured:
        publish:
          summary: Inform about environmental lighting conditions of a particular streetlight.
          message:
            payload:
              type: object
              properties:
                lumens:
                  type: integer
                  minimum: 0
                  description: Light intensity measured in lumens.
                sentAt:
                  type: string
                  format: date-time
                  description: Date and time when the message was sent.
```

## GraphQL Example

```yaml
apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: starwars-api
  description: The Star Wars GraphQL API
spec:
  type: graphql
  lifecycle: production
  owner: team-movies
  definition: |
    type Query {
      hero(episode: Episode): Character
      droid(id: ID!): Droid
    }

    enum Episode {
      NEWHOPE
      EMPIRE
      JEDI
    }

    interface Character {
      id: ID!
      name: String!
      friends: [Character]
      appearsIn: [Episode]!
    }

    type Human implements Character {
      id: ID!
      name: String!
      friends: [Character]
      appearsIn: [Episode]!
      homePlanet: String
    }

    type Droid implements Character {
      id: ID!
      name: String!
      friends: [Character]
      appearsIn: [Episode]!
      primaryFunction: String
    }
```

## gRPC Example

```yaml
apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: helloworld-api
  description: The Hello World gRPC API
spec:
  type: grpc
  lifecycle: production
  owner: team-greetings
  definition: |
      syntax = "proto3";

      package helloworld;

      service Greeter {
        rpc SayHello (HelloRequest) returns (HelloReply) {}
      }

      message HelloRequest {
        string name = 1;
      }

      message HelloReply {
        string message = 1;
      }
```