@frontside/backstage-plugin-graphql-backend-module-catalog v0.3.3

GraphQL Backend Catalog Module

A GraphQL Module providing access to the Backstage Software Catalog

The plugin provides basic Catalog types, such as Entity, User, Component, System, etc... and extends the Directives API with @relation directive.

You will almost always want to start by adding this plugin to your Graphql Backend

Some key features are currently missing. These features may change the schema in backward-incompatible ways.

1. filter query for filtering nodes/entities.
2. viewer query for retrieving data for the current user.

• GraphQL modules
  • Catalog module
  • Relation module
• Directives API
  • @relation directive
• Catalog Data loader

GraphQL modules

Catalog module

The Catalog module is installed just as any other Backstage Module: @frontside/backstage-plugin-graphql-backend

// packages/backend/src/index.ts
import { graphqlModuleCatalog } from '@frontside/backstage-plugin-graphql-backend-module-catalog';

const backend = createBackend();

// GraphQL
backend.use(graphqlPlugin());
backend.use(graphqlModuleCatalog());

Relation module

If you don't want to use basic Catalog types for some reason, but still want to use @relation directive, you can install Relation module

// packages/backend/src/index.ts
import { graphqlModuleRelationResolver } from '@frontside/backstage-plugin-graphql-backend-module-catalog';

const backend = createBackend();

// GraphQL
backend.use(graphqlPlugin());
backend.use(graphqlModuleRelationResolver());

Directives API

@relation

@relation directive allows you to resolve relationships between entities. Similar to @field directive, it writes a resolver for you so you do not have to write a resolver yourself. It assumes that relationships are defined as standard Entity relationships. The name argument allows you to specify the type of the relationship. It will automatically look up the entity in the catalog.

1. To define a User that is the owner of a Component:

type Component {
  owner: User @relation(name: "ownedBy")
}

2. The GraphQL server has baked in support for Relay. By default, collections defined by a @relation directive are modeled as arrays. However, if the relationship is large, and should be paginated, you can specify it with Connection as the field type and use the nodeType argument to specify what the target of the collection should be.

type Repository {
  contributors: Connection @relation(name: "contributedBy", nodeType: "User")

  # Or you can just use an array of entities
  contributors: [User] @relation(name: "contributedBy")
}

3. If you have different kinds of relationships with the same type you can filter them by kind argument:

type System {
  components: Connection
    @relation(name: "hasPart", nodeType: "Component", kind: "component")
  resources: Connection
    @relation(name: "hasPart", nodeType: "Resource", kind: "resource")
}

Catalog Data Loader (Advanced)

In most use cases, you will not need to create a Catalog dataloader by hand. However, when writing custom data loaders for accessing 3rd party sources or rolling your own GraphQL Server implementation you will need to provide the Catalog loader yourself. This plugin provides the createLoader helper to do just that.