@apollo/subgraph

What is @apollo/subgraph?

@apollo/subgraph is a package that allows you to create a subgraph for Apollo Federation. It enables you to build a federated GraphQL architecture by defining and managing subgraphs that can be composed into a single federated schema.

What are @apollo/subgraph's main functionalities?

Define a Subgraph Schema

This feature allows you to define a subgraph schema using GraphQL type definitions and resolvers. The `buildSubgraphSchema` function is used to create the schema for the subgraph.

const { buildSubgraphSchema } = require('@apollo/subgraph');
const { gql } = require('apollo-server');

const typeDefs = gql`
  type Query {
    hello: String
  }
`;

const resolvers = {
  Query: {
    hello: () => 'Hello world!',
  },
};

const schema = buildSubgraphSchema({ typeDefs, resolvers });

Extend Types from Other Subgraphs

This feature allows you to extend types from other subgraphs using the `@key` directive. This is useful for creating relationships between entities managed by different subgraphs.

const { buildSubgraphSchema } = require('@apollo/subgraph');
const { gql } = require('apollo-server');

const typeDefs = gql`
  extend type User @key(fields: "id") {
    id: ID! @external
    posts: [Post]
  }

  type Post @key(fields: "id") {
    id: ID!
    title: String
    content: String
  }
`;

const resolvers = {
  User: {
    posts(user) {
      return getPostsByUserId(user.id);
    },
  },
};

const schema = buildSubgraphSchema({ typeDefs, resolvers });

Federation Directives

This feature allows you to use federation directives like `@key` and `@external` to define how types are shared and resolved across subgraphs. The `__resolveReference` resolver is used to fetch the complete object when only a reference is provided.

const { buildSubgraphSchema } = require('@apollo/subgraph');
const { gql } = require('apollo-server');

const typeDefs = gql`
  type Product @key(fields: "id") {
    id: ID!
    name: String
    price: Float
  }
`;

const resolvers = {
  Product: {
    __resolveReference(product) {
      return getProductById(product.id);
    },
  },
};

const schema = buildSubgraphSchema({ typeDefs, resolvers });

Other packages similar to @apollo/subgraph

graphql-tools

graphql-tools is a set of utilities from Apollo that helps in building and maintaining GraphQL schemas. It provides schema stitching capabilities, which can be used to combine multiple schemas into one, similar to how Apollo Federation combines subgraphs. However, it does not provide the same level of built-in support for federated schemas as @apollo/subgraph.

graphql-modules

graphql-modules is a package that allows you to create modular and reusable GraphQL schemas. It provides a way to organize your schema and resolvers into modules, which can then be combined into a single schema. While it offers a modular approach to building GraphQL schemas, it does not provide the same level of support for federated schemas as @apollo/subgraph.

README

Apollo Subgraph

This package provides utilities for creating GraphQL microservices, which can be combined into a single endpoint through tools like Apollo Gateway.

For complete documentation, see the Apollo Subgraph API reference.

Usage

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

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)
    }
  }
};

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

// Note the top-level await!
const { url } = await startStandaloneServer(server);
console.log(`🚀  Server ready at ${url}`);