Apollo Subgraph

Apollo Subgraph provides utilities for creating GraphQL microservices (subgraphs) that can be combined into a single endpoint through Apollo Federation. This package enables developers to build distributed GraphQL architectures where different teams can independently develop and deploy their own GraphQL services while maintaining schema consistency and type safety across the federated graph.

Package Information

• Package Name: @apollo/subgraph
• Package Type: npm
• Language: TypeScript
• Installation: npm install @apollo/subgraph

Core Imports

import { buildSubgraphSchema, printSubgraphSchema } from "@apollo/subgraph";

For CommonJS:

const { buildSubgraphSchema, printSubgraphSchema } = require("@apollo/subgraph");

Basic Usage

import { buildSubgraphSchema } from "@apollo/subgraph";
import { gql } from "graphql-tag";

// Define federated schema with entity
const typeDefs = gql`
  type Query {
    me: User
  }

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

const resolvers = {
  Query: {
    me() {
      return { id: "1", username: "@ava" };
    }
  },
  User: {
    __resolveReference(user, { fetchUserById }) {
      return fetchUserById(user.id);
    }
  }
};

// Build federation-aware schema
const schema = buildSubgraphSchema([{ typeDefs, resolvers }]);

Architecture

Apollo Subgraph is built around several key components:

• Schema Building: buildSubgraphSchema transforms regular GraphQL schemas into federation-aware subgraph schemas
• Entity System: Automatic handling of federated entities with @key directive and reference resolution
• Federation Directives: Complete set of federation directives for schema composition (@key, @external, @requires, etc.)
• Print Utilities: Functions to output federation-aware schema SDL representations
• Type System: Full TypeScript integration with federation-specific extensions

Capabilities

Schema Building

Core functionality for transforming regular GraphQL schemas into federation-aware subgraph schemas with automatic entity resolution and service introspection.

function buildSubgraphSchema(
  modulesOrSDL: (GraphQLSchemaModule | DocumentNode)[] | DocumentNode | LegacySchemaModule
): GraphQLSchema;

interface GraphQLSchemaModule {
  typeDefs: DocumentNode;
  resolvers?: GraphQLResolverMap<any>;
}

interface LegacySchemaModule {
  typeDefs: DocumentNode | DocumentNode[];
  resolvers?: GraphQLResolverMap<unknown>;
}

Schema Building

Schema Printing

Utilities for outputting federation-aware schema representations as SDL (Schema Definition Language) strings, preserving federation directives and metadata.

function printSubgraphSchema(schema: GraphQLSchema): string;

Schema Printing

Federation Directives

Complete set of GraphQL directives for Apollo Federation schema composition, enabling distributed schema architecture with entity relationships and field resolution control. These directives are automatically processed by buildSubgraphSchema.

Core directives: @key, @external, @requires, @provides
Schema composition directives: @shareable, @override, @tag, @inaccessible
Legacy and utility directives: @extends, @link

Federation Directives

Federation Types

Built-in GraphQL types and resolvers that provide federation infrastructure, including entity resolution, service introspection, and type unions for federated entities. These are automatically handled by buildSubgraphSchema.

Federation infrastructure types: _Entity, _Service, _Any scalars and entity resolution system are automatically added to schemas built with buildSubgraphSchema.

Federation Types

Types

Core Type Definitions

import { DocumentNode, GraphQLSchema } from "graphql";

interface GraphQLResolverMap<TContext = {}> {
  [typeName: string]:
    | {
        [fieldName: string]:
          | GraphQLFieldResolver<any, TContext>
          | {
              requires?: string;
              resolve?: GraphQLFieldResolver<any, TContext>;
              subscribe?: GraphQLFieldResolver<any, TContext>;
            };
      }
    | GraphQLScalarType
    | {
        [enumValue: string]: string | number;
      };
}

type Maybe<T> = null | undefined | T;

type GraphQLReferenceResolver<TContext> = (
  reference: object,
  context: TContext,
  info: GraphQLResolveInfo,
) => any;