graphql-js — The Reference GraphQL Implementation for JavaScript

Introduction

graphql-js is the official JavaScript reference implementation of the GraphQL specification, maintained by the GraphQL Foundation. It provides the core engine that parses GraphQL query strings, validates them against a schema, and executes them to produce results. Nearly every major JavaScript GraphQL server — including Apollo Server, GraphQL Yoga, and Mercurius — builds on top of graphql-js as its foundational layer.

What graphql-js Does

• Parses GraphQL query strings into an abstract syntax tree (AST) for programmatic analysis
• Validates queries against a defined schema, catching errors before execution
• Executes queries by resolving each field through user-defined resolver functions
• Provides a complete type system API for building schemas programmatically
• Supports subscriptions, custom directives, and schema introspection out of the box

Architecture Overview

graphql-js is structured as a pipeline of composable modules. The language module handles lexing and parsing of GraphQL documents into ASTs. The type module defines the GraphQL type system (scalars, objects, interfaces, unions, enums, input types). The validation module checks parsed documents against a schema using a set of rules that mirror the GraphQL specification. The execution module walks the validated AST, calls resolver functions for each field, and assembles the response. Each module can be used independently, making graphql-js both a complete runtime and a toolkit for building custom GraphQL tooling.

Self-Hosting & Configuration

• Install via npm or yarn: npm install graphql — no native dependencies required
• Zero configuration needed; import individual functions like graphql, buildSchema, or execute
• Works in Node.js, Deno, Bun, and modern browsers without polyfills
• Schema can be built programmatically with GraphQLSchema or from SDL strings with buildSchema
• Customize execution behavior by providing custom field resolvers, type resolvers, and middleware

Key Features

• Spec-compliant reference implementation kept in sync with the latest GraphQL specification drafts
• Modular architecture allows importing only the pieces you need (parsing, validation, execution)
• Full introspection support enables tools like GraphiQL and GraphQL Voyager to explore schemas
• Built-in support for abstract types (interfaces and unions) with automatic type resolution
• Stream and defer experimental support for incremental delivery of query results

Comparison with Similar Tools

• Apollo Server — a full HTTP server layer built on top of graphql-js; graphql-js is the engine underneath
• GraphQL Yoga — another server framework that uses graphql-js for parsing and execution but adds HTTP handling and plugins
• graphql-go — the equivalent reference-quality implementation for Go; graphql-js targets the JavaScript ecosystem
• Juniper — Rust GraphQL library with a macro-based API; graphql-js uses a dynamic type system approach
• graphql-java — the JVM counterpart; graphql-js is generally the first to implement new spec features

FAQ

Q: Is graphql-js a full GraphQL server? A: No. graphql-js is the core engine for parsing, validating, and executing GraphQL. You pair it with an HTTP framework (Express, Fastify, Koa) or use a server library like Apollo Server or GraphQL Yoga that wraps it.

Q: Does graphql-js support TypeScript? A: Yes. The library ships with built-in TypeScript type definitions and is itself written in TypeScript as of version 16+.

Q: How does schema-first vs code-first work with graphql-js? A: You can define schemas using SDL strings via buildSchema (schema-first) or construct them programmatically using GraphQLObjectType and related classes (code-first). Both approaches produce the same internal schema representation.

Q: What is the performance overhead of graphql-js? A: For most applications, graphql-js execution time is negligible compared to resolver I/O. For hot paths, you can pre-parse and cache document ASTs, and use DataLoader to batch resolver calls.

Sources

• https://github.com/graphql/graphql-js
• https://graphql.org/graphql-js/