NestJS GraphQL

@nestjs/graphql is the official integration between NestJS and GraphQL, letting you define resolvers, types, and schemas using the same decorator-driven, dependency-injection-friendly patterns NestJS uses for REST controllers. It supports both code-first (TypeScript classes + decorators generate the schema) and schema-first (SDL files generate TypeScript types) development styles.

The package is driver-agnostic: it plugs into either Apollo Server (@nestjs/apollo) or Mercurius (@nestjs/mercurius) as the underlying GraphQL execution engine, while @nestjs/graphql itself owns the schema-building, decorator, and resolver-wiring layer shared across both. This makes it the entry point most NestJS teams reach for first when adding GraphQL to an application, with the driver package chosen separately based on performance or ecosystem needs.

What You Get

• @Resolver, @Query, @Mutation, @Subscription, and @Field decorators that wire GraphQL operations to NestJS providers and DI
• Code-first schema generation from TypeScript classes, or schema-first generation of TypeScript types from .graphql SDL files
• A GraphQLModule.forRoot()/forRootAsync() entry point that plugs into either the Apollo or Mercurius driver package
• Built-in support for Apollo Federation for composing a distributed/federated GraphQL schema across services
• Subscription support for real-time GraphQL over WebSockets
• A CLI plugin that reduces decorator boilerplate by inferring GraphQL types from TypeScript types at build time

Common Use Cases

• Adding a GraphQL API layer to an existing NestJS REST application without abandoning its module/DI structure
• Building federated GraphQL architectures where multiple NestJS services contribute to one composed schema via Apollo Federation
• Schema-first teams that want SDL as the source of truth with generated TypeScript types for resolver safety
• Real-time GraphQL subscriptions layered onto an existing NestJS service

Under The Hood

Architecture — The repo is a Lerna-managed monorepo (packages/graphql, packages/apollo, packages/mercurius) where @nestjs/graphql owns schema construction and decorator metadata (lib/graphql-schema.builder.ts, lib/graphql.factory.ts, lib/decorators/, lib/type-factories/) while the driver packages (@nestjs/apollo, @nestjs/mercurius) implement a common driver interface that plugs the built schema into the chosen GraphQL server engine. GraphQLModule.forRoot() is the composition root: it accepts a driver instance, builds the schema from decorated resolver classes (code-first) or loaded SDL (schema-first) via lib/schema-builder/, and registers it with NestJS’s module/DI system so resolvers receive constructor-injected services exactly like REST controllers do.

Tech Stack — Built on TypeScript with graphql-js and @graphql-tools for schema construction/merging, type-graphql-inspired decorator metadata for the code-first path, and reflect-metadata for runtime type introspection. The monorepo uses Yarn workspaces and Lerna for versioning across the three published packages, with renovate.json automating dependency updates (visible as the top contributor by commit count in this repo’s history).

Code Quality — Extensive .spec.ts unit test coverage (41+ spec files) across decorators, schema builders, and type factories, reflecting the maturity expected of a first-party NestJS package maintained by the core team. The federation and subscription code paths in particular carry dedicated test suites given their complexity.

API Design — The decorator API (@Resolver(), @Query(), @Mutation(), @Args()) deliberately mirrors NestJS’s @Controller()/@Get()/@Param() REST conventions, so developers already familiar with NestJS controllers have almost no new mental model to learn for GraphQL resolvers. The code-first/schema-first duality is the one added decision point: code-first minimizes SDL authoring but requires decorator discipline, while schema-first requires a build step to regenerate types from .graphql files. The CLI plugin (which infers types from TypeScript signatures) further reduces code-first boilerplate once configured.