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

Federation Plugin

The Federation plugin adds Apollo Federation support to your Baeta subgraph.

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​

The plugin generates the federation spec directives based on the chosen version and include options. These directives are available in your schema files.

It also generates the federation SDL, the _Entity union (from types with a resolvable @key), the _entities and _service resolvers, and typed entity handler signatures in __generated__/federation.ts.

Entity Handlers​

The only manual step is registering entity handlers in src/modules/baeta-federation/entity-handlers.ts. This file 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 entity 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

Check the federation-subgraph-products and federation-subgraph-users examples for complete working subgraphs.