@apollo/subgraph

Apollo Federation subgraph utilities for the graphql-js ecosystem.

@apollo/subgraph is built on top of graphql-js and provides transformation logic to make your GraphQL schemas Federation compatible. buildSubgraphSchema adds common Federation type definition (e.g. Any scalar, _Entity union, Federation directives, etc) and allows you to easily specify your Federated entity resolvers.

Installation

Requires Node.js 22 or later.

npm install @apollo/subgraph graphql

Usage

import { ApolloServer } from '@apollo/server';
import { startStandaloneServer } from '@apollo/server/standalone';
import { buildSubgraphSchema } from '@apollo/subgraph';
import gql from 'graphql-tag';

const typeDefs = gql`
  extend schema
    @link(url: "https://specs.apollo.dev/federation/v2.9", import: ["@key"])

  type Query {
    product(id: ID!): Product
  }

  type Product @key(fields: "id") {
    id: ID!
    name: String
  }
`;

const resolvers = {
  Query: {
    product: (_source, { id }) => products.find((product) => product.id === id),
  },
  Product: {
    // Called for each entity representation the router sends to `_entities`.
    __resolveReference: (reference) =>
      products.find((product) => product.id === reference.id),
  },
};

const server = new ApolloServer({
  schema: buildSubgraphSchema([{ typeDefs, resolvers }]),
});

await startStandaloneServer(server, { listen: { port: 4001 } });

API

• buildSubgraphSchema(modulesOrSDL) — builds the executable subgraph schema. Accepts a DocumentNode, or an array of documents or { typeDefs, resolvers } modules.
• printSubgraphSchema(schema) — prints the complete subgraph schema, federation directives and types included.
• addResolversToSchema(schema, resolvers) — attaches a resolver map to an existing schema, understanding __resolveReference alongside the usual __resolveType / __isTypeOf.
• entitiesResolver({ representations, context, info }) — the _entities resolver, exported for libraries that assemble their own root fields.

Entity references are resolved through __resolveReference, either from a resolver map or from extensions.apollo.subgraph.resolveReference on the type.

Development

npm install
npm run build
npm test

The compatibility/ workspace runs the Apollo Federation subgraph compatibility suite against this library, using docker compose for the router and reference subgraphs. See its README.

npm run compatibility --workspace @apollo/subgraph-compatibility

Contact

If you have a specific question about the library or code, please start a discussion in the Apollo community forums.

Contributing

See CONTRIBUTING.md for details.

After you have your local branch set up, take a look at our open issues to see where you can contribute.

Security

For more info on how to contact the team for security issues, see our Security Policy.

License

This library is licensed under The MIT License (MIT).