diff --git a/.changeset/polite-turkeys-happen.md b/.changeset/polite-turkeys-happen.md new file mode 100644 index 0000000000..7356c59c90 --- /dev/null +++ b/.changeset/polite-turkeys-happen.md @@ -0,0 +1,6 @@ +--- +'@frontside/backstage-plugin-graphql-backend-module-catalog': patch +'@frontside/backstage-plugin-graphql-backend': patch +--- + +Export `createCatalogLoader` function diff --git a/plugins/graphql-backend-module-catalog/README.md b/plugins/graphql-backend-module-catalog/README.md index 53c1d80c24..03704d76a0 100644 --- a/plugins/graphql-backend-module-catalog/README.md +++ b/plugins/graphql-backend-module-catalog/README.md @@ -31,10 +31,24 @@ This package provides two GraphQL modules: ### Backstage Plugins For the [Backstage plugin system](https://backstage.io/docs/plugins/backend-plugin), -you can learn how to add GraphQL modules by checking out [GraphQL Modules](../graphql-backend/README.md#graphql-modules) -section in `@frontside/backstage-plugin-graphql-backend` package. +you have to pass `Catalog` or `Relation` GraphQL module to the `modules` option and +create catalog `DataLoader`: -This package exports `Catalog` and `Relation` modules +```ts +import { createRouter } from '@frontside/backstage-plugin-graphql-backend'; +import { Catalog } from '@frontside/backstage-plugin-graphql-backend-module-catalog'; + +// packages/backend/src/plugins/graphql.ts +export default async function createPlugin( + env: PluginEnvironment, +): Promise { + return await createRouter({ + logger: env.logger, + modules: [Catalog], + loaders: { ...createCatalogLoader(env.catalogClient) }, + }); +} +``` ### Experimental Backend System @@ -108,19 +122,9 @@ type System { } ``` -## 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][custom-loader] or [rolling your own GraphQL Server -implementation][roll-your-own] you will need to provide the Catalog -loader yourself. This plugin provides the `createLoader` helper to do -just that. - [graphql-backend]: ../graphql-backend/README.md [graphql-modules]: https://the-guild.dev/graphql/modules [relay]: https://relay.dev/docs/guides/graphql-server-specification [custom-loader]: ../graphql-backend/README.md#custom-data-loaders-advanced -[roll-your-own]: ../graphql-common/README.md#getting-started [catalog]: https://backstage.io/docs/features/software-catalog/software-catalog-overview -[directives-api]: ../graphql-common/README.md#directives-api +[directives-api]: https://github.com/thefrontside/HydraphQL/blob/main/README.md#directives-api diff --git a/plugins/graphql-backend-module-catalog/src/catalogModule.ts b/plugins/graphql-backend-module-catalog/src/catalogModule.ts index 9c137ed7b5..681f8a99c9 100644 --- a/plugins/graphql-backend-module-catalog/src/catalogModule.ts +++ b/plugins/graphql-backend-module-catalog/src/catalogModule.ts @@ -4,8 +4,7 @@ import { graphqlLoadersExtensionPoint, graphqlModulesExtensionPoint, } from '@frontside/backstage-plugin-graphql-backend'; -import { createEntitiesLoadFn } from './entitiesLoadFn'; -import { CATALOG_SOURCE } from './constants'; +import { createCatalogLoader } from './entitiesLoadFn'; import { Catalog } from './catalog/catalog'; /** @public */ @@ -21,7 +20,7 @@ export const graphqlModuleCatalog = createBackendModule({ }, async init({ catalog, modules, loaders }) { modules.addModules([Catalog]); - loaders.addLoaders({ [CATALOG_SOURCE]: createEntitiesLoadFn(catalog) }); + loaders.addLoaders(createCatalogLoader(catalog)); }, }); }, diff --git a/plugins/graphql-backend-module-catalog/src/entitiesLoadFn.ts b/plugins/graphql-backend-module-catalog/src/entitiesLoadFn.ts index 7ce345e393..21666606ed 100644 --- a/plugins/graphql-backend-module-catalog/src/entitiesLoadFn.ts +++ b/plugins/graphql-backend-module-catalog/src/entitiesLoadFn.ts @@ -2,10 +2,10 @@ import type { CatalogApi } from '@backstage/catalog-client'; import { Entity } from '@backstage/catalog-model'; import { NodeQuery } from '@frontside/hydraphql'; import { GraphQLError } from 'graphql'; +import { CATALOG_SOURCE } from './constants'; -export const createEntitiesLoadFn = - (catalog: CatalogApi) => - async ( +export const createCatalogLoader = (catalog: CatalogApi) => ({ + [CATALOG_SOURCE]: async ( queries: readonly (NodeQuery | undefined)[], ): Promise> => { // TODO: Support fields @@ -27,4 +27,5 @@ export const createEntitiesLoadFn = new GraphQLError(`no such entity with ref: '${queries[index]}'`)), ); return entities; - }; + }, +}); diff --git a/plugins/graphql-backend-module-catalog/src/index.ts b/plugins/graphql-backend-module-catalog/src/index.ts index 71a1c8c3c6..0e70e46ee1 100644 --- a/plugins/graphql-backend-module-catalog/src/index.ts +++ b/plugins/graphql-backend-module-catalog/src/index.ts @@ -2,3 +2,4 @@ export * from './catalog'; export * from './relation'; export * from './catalogModule'; export * from './relationModule'; +export * from './entitiesLoadFn'; diff --git a/plugins/graphql-backend-module-catalog/src/relationModule.ts b/plugins/graphql-backend-module-catalog/src/relationModule.ts index 7d662fea27..9e53826f9a 100644 --- a/plugins/graphql-backend-module-catalog/src/relationModule.ts +++ b/plugins/graphql-backend-module-catalog/src/relationModule.ts @@ -4,8 +4,7 @@ import { graphqlLoadersExtensionPoint, graphqlModulesExtensionPoint, } from '@frontside/backstage-plugin-graphql-backend'; -import { createEntitiesLoadFn } from './entitiesLoadFn'; -import { CATALOG_SOURCE } from './constants'; +import { createCatalogLoader } from './entitiesLoadFn'; import { Relation } from './relation/relation'; /** @public */ @@ -21,7 +20,7 @@ export const graphqlModuleRelationResolver = createBackendModule({ }, async init({ catalog, modules, loaders }) { modules.addModules([Relation]); - loaders.addLoaders({ [CATALOG_SOURCE]: createEntitiesLoadFn(catalog) }); + loaders.addLoaders(createCatalogLoader(catalog)); }, }); }, diff --git a/plugins/graphql-backend/docs/backend-plugins.md b/plugins/graphql-backend/docs/backend-plugins.md index 2615c8afd1..2724fb7cb0 100644 --- a/plugins/graphql-backend/docs/backend-plugins.md +++ b/plugins/graphql-backend/docs/backend-plugins.md @@ -56,10 +56,10 @@ installed, you won't be able to do much with it. The way to add new types and new resolvers to your GraphQL backend is with [GraphQL Modules][graphql-modules]. These are portable little bundles of schema that you can drop into place and have them extend -your GraphQL server. The most important of these that is maintained by -the Backstage team is the [graphql-backend-module-catalog][] module that makes your -Catalog accessible via GraphQL. To add this module to your GraphQL server, -add it to the `modules` array in your backend config: +your GraphQL server. The most important of these that is the +[graphql-backend-module-catalog][] module that makes your +Catalog accessible via GraphQL. To add this module and catalog loader to your GraphQL server, +add it to the `modules` array in your backend config and create a catalog `DataLoader`: ```ts import { createRouter } from '@frontside/backstage-plugin-graphql-backend'; @@ -72,6 +72,7 @@ export default async function createPlugin( return await createRouter({ logger: env.logger, modules: [Catalog], + loaders: { ...createCatalogLoader(env.catalogClient) }, }); } ```