# @apollo/subgraph

> Apollo Federation subgraph utilities built on graphql-js

Latest version **2.15.1** (published 2026-09-14) · MIT license · 0 weekly downloads

## Install

```sh
npm install @apollo/subgraph
pnpm add @apollo/subgraph
yarn add @apollo/subgraph
bun add @apollo/subgraph
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 2.15.1 |
| Published | 2026-09-14 |
| First published | 2021-10-07 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=22.0.0 |
| Dependencies | 2 |
| Unpacked size | 94.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 1 |
| Author | Apollo |
| Maintainers | dkuc, apollo-bot, phryneas, abernix |
| Keywords | graphql, federation, apollo, subgraph |

## Links

- npm: https://www.npmjs.com/package/@apollo/subgraph
- Repository: https://github.com/apollographql/subgraph-js
- Homepage: https://github.com/apollographql/subgraph-js#readme
- Issues: https://github.com/apollographql/subgraph-js/issues
- npm.io page: https://npm.io/package/@apollo/subgraph

## Dependencies (2)

- [@graphql-tools/utils](https://npm.io/package/@graphql-tools/utils.md) ^12.0.0
- [@apollo/cache-control-types](https://npm.io/package/@apollo/cache-control-types.md) ^1.0.3

## Alternatives

- [apollo-link-http-common](https://npm.io/package/apollo-link-http-common.md) — 879.0K weekly downloads
- [react-relay](https://npm.io/package/react-relay.md) — 336.8K weekly downloads
- [relay-test-utils](https://npm.io/package/relay-test-utils.md) — 181.6K weekly downloads
- [@vendure/core](https://npm.io/package/@vendure/core.md) — 14.8K weekly downloads
- [@pnpm/deps.graph-sequencer](https://npm.io/package/@pnpm/deps.graph-sequencer.md) — 13.4K weekly downloads

## Recent versions

- 2.15.1 (latest) — 2026-09-14
- 2.15.0-alpha.0 (alpha) — 2026-08-28
- 2.13.4 (version-2.13) — 2026-07-22
- 2.12.4 (version-2.12) — 2026-07-22
- 2.11.7 (version-2.11) — 2026-07-22
- 2.13.3 (next) — 2026-03-19
- 2.13.0-preview.2 (preview) — 2025-12-19
- 2.9.0-beta.0 (beta) — 2024-08-22
- 2.9.0-connectors.9 (connectors) — 2024-07-23
- 2.7.4-testing.1 (testing) — 2024-04-23
- 0.6.1 (latest-1) — 2022-11-11
- 2.15.0 — 2026-08-28
- 15.0.0-alpha.1 — 2026-08-28
- 2.14.4 — 2026-08-18
- 2.14.3 — 2026-07-22
- … 178 more at https://npm.io/package/@apollo/subgraph/versions

## README

[![Continuous Integration](https://github.com/apollographql/subgraph-js/workflows/Continuous%20Integration/badge.svg)](https://github.com/apollographql/subgraph-js/actions?query=workflow%3A%22Continuous+Integration%22)
[![MIT License](https://img.shields.io/github/license/apollographql/subgraph-js.svg)](LICENSE)
[![NPM](https://img.shields.io/npm/v/%40apollo%2Fsubgraph)](https://www.npmjs.com/package/@apollo/subgraph)
[![Join the community forum](https://img.shields.io/badge/join%20the%20community-forum-blueviolet)](https://community.apollographql.com)

# @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.

```sh
npm install @apollo/subgraph graphql
```

## Usage

```ts
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

```sh
npm install
npm run build
npm test
```

The [`compatibility/`](./compatibility) workspace runs the
[Apollo Federation subgraph compatibility suite](https://github.com/apollographql/apollo-federation-subgraph-compatibility)
against this library, using docker compose for the router and reference subgraphs. 
See its [README](./compatibility/README.md).

```sh
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](https://community.apollographql.com/).

## Contributing

See [CONTRIBUTING.md](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](https://github.com/apollographql/federation-jvm/security/policy).

## License

This library is licensed under [The MIT License (MIT)](LICENSE).

---
_Source: https://npm.io/package/@apollo/subgraph · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._