Skip to main content
Version: Next (2.x)

Federation Plugin

The federation plugin makes a Baeta module a valid Apollo Federation subgraph: it generates the federation spec directives, the _Entity union, the _entities/_service resolvers, and typed handler signatures.

Installation​

Runtime dependency:

yarn add @baeta/federation

Development dependency:

yarn add @baeta/plugin-federation -D

Configuration​

Enable the federation plugin in your baeta.ts:

import { defineConfig } from "@baeta/cli";
import { federationPlugin } from "@baeta/plugin-federation";

export default defineConfig({
  graphql: {
    schemas: ["src/**/*.gql"],
  },
  plugins: [
    federationPlugin({
      // Federation version to target (default: '2.9')
      version: "2.9",

      // Additional directives to include, or 'all' for every directive in the version
      // Default: ['@key', '@external', '@requires', '@provides', '@extends']
      include: "all",

      // Custom name for the generated federation module (default: 'baeta-federation')
      moduleName: "baeta-federation",
    }),
  ],
});

For the full configuration interface, see the FederationPluginOptions API reference.

How it works​

Based on version and include, the plugin makes the federation directives available in your schema files. It also writes __generated__/federation.ts with the SDL, the _Entity union (from types with a resolvable @key), the _entities/_service resolvers, and typed handler signatures.

Entity handlers​

The only manual step is registering entity handlers. src/modules/baeta-federation/entity-handlers.ts is generated once and never overwritten:

src/modules/baeta-federation/entity-handlers.ts
import type { EntityHandlerMap } from "../../__generated__/federation.ts";
import { handleProductEntity } from "../product/product.entity.ts";

const entityHandlersMap: EntityHandlerMap = {
  Product: handleProductEntity,
};

export default entityHandlersMap;

Each handler receives the federation representation and returns the resolved entity:

src/modules/product/product.entity.ts
import type { ProductEntityHandler } from "../../__generated__/federation.ts";

export const handleProductEntity: ProductEntityHandler = async (
  representation,
) => {
  return {
    __typename: "Product",
    id: representation.id,
    name: `Product ${representation.id}`,
    price: 9.99,
    owner: {
      id: "1",
    },
  };
};
tip

The federation-subgraph-products and federation-subgraph-users examples are complete working subgraphs you can run locally.