@pawells/nestjs-graphql

@pawells/nestjs-graphql

Description

Pre-configured NestJS GraphQL module using the Apollo driver with org-standard schema options and environment-controlled introspection and playground.

The module eliminates per-service GraphQL boilerplate by encoding the following org defaults once: code-first in-memory schema generation (autoSchemaFile: true), deterministic field ordering (sortSchema: true), and HTTP request context propagation to resolvers (context: ({ req }) => ({ req })). Playground and introspection are enabled by default and disabled automatically in NODE_ENV=production — both can be overridden via environment variables or the forRoot() options argument.

Requirements

• Node.js >=22.0.0
• NestJS peer dependencies (installed separately):
  • @nestjs/common ^11.0.1
  • @nestjs/apollo ^13.0.0
  • @nestjs/graphql ^13.0.0
• Apollo Server runtime (installed separately):
  • @apollo/server ^4.11.3
  • graphql ^16.14.0

Installation

Install the package and its required peers:

yarn add @pawells/nestjs-graphql @nestjs/apollo @nestjs/graphql @nestjs/common @apollo/server graphql

@nestjs/apollo is tested against ~13.1.x. If your lockfile resolves a different patch, pin it explicitly:

yarn add @nestjs/apollo@~13.1.0

Quick Start

Set the environment variables, then import and use the module:

import { Module } from '@nestjs/common';
import { GraphQLModule } from '@pawells/nestjs-graphql';

@Module({
	imports: [GraphQLModule.forRoot()],
})
export class AppModule {}

Then create the NestJS app:

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module.js';

const app = await NestFactory.create(AppModule);
await app.listen(3000);

Environment variables are read directly at bootstrap time to determine GraphQL security defaults.

Environment Variables

Variable	Type	Default	Description
GRAPHQL_PLAYGROUND	boolean	true (non-production)	Enables the Apollo Sandbox UI
GRAPHQL_INTROSPECTION	boolean	true (non-production)	Enables GraphQL schema introspection
GRAPHQL_MAX_DEPTH	integer	10	Maximum allowed query depth; prevents resource exhaustion from deeply nested queries

Defaults for GRAPHQL_PLAYGROUND and GRAPHQL_INTROSPECTION are true when NODE_ENV is not production, and false when NODE_ENV=production. The NODE_ENV check is evaluated at bootstrap time; set variables before the process starts.

Override playground or introspection explicitly regardless of NODE_ENV:

GRAPHQL_PLAYGROUND=false
GRAPHQL_INTROSPECTION=false

Or pass options directly to forRoot() to override at the module level:

GraphQLModule.forRoot({
	introspection: true,
	autoSchemaFile: '/custom/path/schema.graphql',
})

API Reference

Exports

Export	Kind	Description
GraphQLModule	class	Pre-configured NestJS GraphQL module with static forRoot() factory
GraphQLModule.forRoot	static method	Returns a DynamicModule configured for GraphQL with Apollo; accepts optional ApolloDriverConfig overrides
GraphQLConfig	config object	Registered @pawells/config schema for the GRAPHQL_ env var prefix; exposes Get() to retrieve validated values
GRAPHQL_SCHEMA	Zod schema	Raw Zod schema defining PLAYGROUND and INTROSPECTION boolean fields

GraphQLModule.forRoot(options?)

static forRoot(options?: Partial<ApolloDriverConfig>): DynamicModule

Creates a NestJS DynamicModule backed by @nestjs/graphql's forRootAsync. The following options are hardcoded and cannot be overridden via the options argument:

Option	Hardcoded value
driver	ApolloDriver
sortSchema	true
context	({ req }) => ({ req })

All other ApolloDriverConfig options — including autoSchemaFile, introspection, playground, and formatError — can be customized via the options argument and will override the defaults.

GraphQLConfig

A registered configuration object produced by @pawells/config's RegisterConfigSchema. Reads environment variables prefixed with GRAPHQL_ that were loaded by the registered provider.

Method	Description
GraphQLConfig.Get(key)	Returns the parsed, validated value for 'PLAYGROUND' or 'INTROSPECTION'; throws if the key is unset or invalid

Environment Variables

Variable	Type	Default	Description
GRAPHQL_PLAYGROUND	boolean	true when NODE_ENV !== 'production'	Enables Apollo Sandbox UI
GRAPHQL_INTROSPECTION	boolean	true when NODE_ENV !== 'production'	Enables schema introspection queries
GRAPHQL_MAX_DEPTH	integer	10	Maximum allowed query depth

License

MIT — Copyright (c) Phillip Aaron Wells. See LICENSE for details.