# graphql-js — The Reference GraphQL Implementation for JavaScript

> The official reference implementation of the GraphQL specification in JavaScript, providing the core engine for parsing, validating, and executing GraphQL queries used by most JavaScript GraphQL servers and tools.

## Install

Save as a script file and run:

# graphql-js — The Reference GraphQL Implementation for JavaScript

## Quick Use
```bash
npm install graphql

# Run a simple query
node -e "
const { graphql, buildSchema } = require('graphql');
const schema = buildSchema('type Query { hello: String }');
const root = { hello: () => 'Hello, world!' };
graphql({ schema, source: '{ hello }', rootValue: root }).then(r => console.log(r));
"
```

## 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/

---
Source: https://tokrepo.com/en/workflows/asset-618e3d56
Author: Script Depot