or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

alpha-features.mdapi-integration.mdentity-display.mdentity-filters.mdentity-hooks.mdindex.mdpicker-components.mdutilities.md
tile.json

tessl/npm-backstage--plugin-catalog-react

A frontend library that helps other Backstage plugins interact with the catalog through React components, hooks, and utilities.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@backstage/plugin-catalog-react@1.9.x

To install, run

npx @tessl/cli install tessl/npm-backstage--plugin-catalog-react@1.9.0

index.mddocs/

Backstage Plugin Catalog React

A frontend library that helps other Backstage plugins interact with the catalog through React components, hooks, and utilities. This package provides a comprehensive set of React components and hooks for building catalog-aware user interfaces within the Backstage platform.

Package Information

  • Package Name: @backstage/plugin-catalog-react
  • Package Type: npm
  • Language: TypeScript
  • Installation: yarn add @backstage/plugin-catalog-react

Core Imports

import { 
  EntityTable,
  EntityRefLink,
  useEntity,
  useEntityList,
  catalogApiRef,
  EntityKindFilter 
} from "@backstage/plugin-catalog-react";

For alpha features:

import { 
  createEntityCardExtension,
  createEntityContentExtension 
} from "@backstage/plugin-catalog-react/alpha";

Basic Usage

import React from 'react';
import { 
  useEntityList,
  EntityTable,
  EntityKindFilter,
  EntitySearchBar,
  EntityTypeFilter
} from '@backstage/plugin-catalog-react';
import { Entity } from '@backstage/catalog-model';

// Basic entity listing with filtering
function CatalogList() {
  const { entities, filters, updateFilters, loading } = useEntityList();
  
  return (
    <div>
      <EntitySearchBar />
      <EntityTable
        title="Software Catalog"
        entities={entities}
        columns={[
          { title: 'Name', field: 'metadata.name' },
          { title: 'Kind', field: 'kind' },
          { title: 'Owner', field: 'spec.owner' }
        ]}
      />
    </div>
  );
}

// Using entity context
function EntityDetails() {
  const { entity } = useEntity();
  
  return (
    <div>
      <h2>{entity.metadata.name}</h2>
      <p>Owner: {entity.spec?.owner}</p>
    </div>
  );
}

Architecture

The plugin is organized around several key architectural patterns:

  • Component System: Reusable React components for entity display, navigation, and interaction
  • Hook System: Custom React hooks for entity data management and API interactions
  • Filter System: Composable filters for entity searching and categorization
  • API Integration: Standardized interfaces for catalog backend communication
  • Context Providers: React context for entity and entity list state management
  • Route Management: Integrated routing for entity navigation within Backstage

Capabilities

Entity Display Components

Core React components for displaying and linking to entities in various formats, including tables, links, and display names.

function EntityTable<T extends Entity>(props: EntityTableProps<T>): JSX.Element;
function EntityRefLink(props: EntityRefLinkProps): JSX.Element;
function EntityDisplayName(props: EntityDisplayNameProps): JSX.Element;

Entity Display Components

Entity Management Hooks

React hooks for accessing and managing entity data, including current entity context and async loading patterns.

function useEntity<TEntity extends Entity = Entity>(): { entity: TEntity };
function useAsyncEntity<TEntity extends Entity = Entity>(): EntityLoadingStatus<TEntity>;
function useEntityList<EntityFilters extends DefaultEntityFilters = DefaultEntityFilters>(): EntityListContextProps<EntityFilters>;

Entity Management Hooks

Entity Filtering System

Comprehensive filtering system for entity search and categorization, supporting backend and frontend filtering patterns.

class EntityKindFilter implements EntityFilter {
  constructor(value: string);
  getCatalogFilters(): Record<string, string | symbol | (string | symbol)[]>;
  toQueryValue(): string;
}

class EntityTypeFilter implements EntityFilter {
  constructor(value: string | string[]);
  getCatalogFilters(): Record<string, string | symbol | (string | symbol)[]>;
  toQueryValue(): string | string[];
}

Entity Filtering System

Picker Components

Interactive components for selecting and filtering entities by various criteria like kind, type, owner, and tags.

function EntityKindPicker(): JSX.Element;
function EntityTypePicker(): JSX.Element; 
function EntityOwnerPicker(): JSX.Element;
function EntityTagPicker(): JSX.Element;

Picker Components

API Integration

API references and utilities for integrating with the Backstage catalog backend and related services.

const catalogApiRef: ApiRef<CatalogApi>;
const starredEntitiesApiRef: ApiRef<StarredEntitiesApi>;
const entityPresentationApiRef: ApiRef<EntityPresentationApi>;

API Integration

Utility Functions

Helper functions for entity relationships, source location, ownership checks, and route management.

function getEntityRelations(
  entity: Entity | undefined, 
  relationType: string, 
  filter?: { kind: string }
): CompoundEntityRef[];

function getEntitySourceLocation(
  entity: Entity, 
  scmIntegrationsApi: ScmIntegrationsApi
): EntitySourceLocation | undefined;

function isOwnerOf(owner: Entity, entity: Entity): boolean;

Utility Functions

Alpha Features

Extension system for creating custom entity cards and content extensions in the new Backstage frontend system.

function createEntityCardExtension<TInputs extends AnyExtensionInputMap>(
  options: EntityCardExtensionOptions<TInputs>
): Extension<any>;

function createEntityContentExtension<TInputs extends AnyExtensionInputMap>(
  options: EntityContentExtensionOptions<TInputs>
): Extension<any>;

Alpha Features

Types

Core Types

interface EntityFilter {
  getCatalogFilters?: () => Record<string, string | symbol | (string | symbol)[]>;
  filterEntity?: (entity: Entity) => boolean;
  toQueryValue?: () => string | string[];
}

type UserListFilterKind = 'owned' | 'starred' | 'all';

interface EntityLoadingStatus<TEntity extends Entity = Entity> {
  entity?: TEntity;
  loading: boolean;
  error?: Error;
  refresh?: VoidFunction;
}

interface EntitySourceLocation {
  locationTargetUrl: string;
  integrationType?: string;
}