graphql

A Query Language and Runtime which can target any service.

weekly downloads25.2M

versionv16.12.0

licenseMIT

categorybackend

graphqlgraphql-js

Overview

The graphql package is the reference JavaScript implementation of the GraphQL specification maintained by the GraphQL Foundation. It provides the core runtime for building type-safe schemas and executing queries, mutations, and subscriptions against any data source. With over 25 million weekly downloads, it serves as the foundational layer for nearly all GraphQL servers and tooling in the JavaScript ecosystem.

This package gives you low-level primitives for schema construction using either Schema Definition Language (SDL) or programmatic APIs like GraphQLSchema, GraphQLObjectType, and scalar types. The runtime handles parsing, validation, and execution of GraphQL operations, reporting detailed errors with source locations when queries fail. Unlike opinionated frameworks, graphql-js remains transport-agnostic and data-source-agnostic, making it suitable for custom server implementations, edge functions, or embedding GraphQL capabilities into existing applications.

Developers typically use this package in two scenarios: building GraphQL servers from scratch with fine-grained control over resolvers and execution context, or as a dependency for higher-level frameworks like Apollo Server, Yoga, or Mercurius. The library enforces GraphQL's hierarchical type system, enabling clients to request exact data shapes through a single endpoint rather than managing multiple REST routes. Production deployments benefit from setting NODE_ENV=production to disable development-time validation checks.

The package has remained stable since reaching maturity, with incremental improvements to TypeScript definitions, performance optimizations, and spec compliance. It represents the canonical implementation that other GraphQL tools across languages reference for behavior and validation rules.

Quick Start

typescript

import { graphql, buildSchema } from 'graphql';

const schema = buildSchema(`
  type User {
    id: ID!
    name: String!
    email: String!
  }

  type Query {
    user(id: ID!): User
    users: [User!]!
  }

  type Mutation {
    createUser(name: String!, email: String!): User!
  }
`);

const users = [
  { id: '1', name: 'Alice', email: 'alice@example.com' },
  { id: '2', name: 'Bob', email: 'bob@example.com' }
];

const root = {
  user: ({ id }) => users.find(u => u.id === id),
  users: () => users,
  createUser: ({ name, email }) => {
    const user = { id: String(users.length + 1), name, email };
    users.push(user);
    return user;
  }
};

const query = '{ users { id name } }';

graphql({ schema, source: query, rootValue: root })
  .then(result => console.log(JSON.stringify(result, null, 2)));

const mutation = 'mutation { createUser(name: "Charlie", email: "charlie@example.com") { id name } }';

graphql({ schema, source: mutation, rootValue: root })
  .then(result => console.log(JSON.stringify(result, null, 2)));

Use Cases

Building custom GraphQL servers: Implement a GraphQL API over existing databases, microservices, or REST APIs using Express, Fastify, or serverless functions. You control resolver logic, authentication middleware, and data fetching strategies without framework constraints.

Schema-first API development: Define your API contract using SDL syntax, generate TypeScript types from the schema, and implement resolvers that enforce exact response shapes. Teams can iterate on schemas independently of client code.

Backend-for-frontend (BFF) layers: Aggregate data from multiple services into a unified GraphQL interface tailored to frontend needs. Resolvers orchestrate parallel requests, transform data formats, and handle authorization logic per field.

Real-time applications with subscriptions: Implement WebSocket-based subscriptions for live updates like chat messages, notifications, or collaborative editing. The package handles subscription lifecycle alongside queries and mutations in a single schema.

Embedded GraphQL execution: Run GraphQL queries within build tools, CLI applications, or testing frameworks to provide structured data querying without HTTP transport. Useful for static site generators or administrative scripts that need flexible data access patterns.

Pros & Cons

Pros

+Reference implementation ensures spec compliance and compatibility with the entire GraphQL ecosystem
+Framework-agnostic design allows integration with any HTTP server, serverless platform, or custom transport layer
+Strong type system with introspection enables automatic documentation, validation, and code generation
+Fine-grained control over resolvers, execution context, and error handling without abstraction overhead
+Supports synchronous and asynchronous resolvers with Promise-based execution flow

Cons

−Low-level API requires significant boilerplate compared to frameworks like Apollo Server or TypeGraphQL
−No built-in solutions for common production needs like caching, rate limiting, or DataLoader integration
−Programmatic schema construction with `GraphQLObjectType` is verbose for large schemas compared to SDL-first tools
−Error messages for schema construction mistakes can be cryptic without understanding the internal type system
−Performance tuning requires manual optimization of resolver batching and query complexity analysis

Alternatives

graphql-yogav5.18.0

backendgraphqlserver

759K / week

Install

bash

npm install graphql

bash

pnpm add graphql

bash

bun add graphql

Overview

Quick Start

typescript

import { graphql, buildSchema } from 'graphql';

const schema = buildSchema(`
  type User {
    id: ID!
    name: String!
    email: String!
  }

  type Query {
    user(id: ID!): User
    users: [User!]!
  }

  type Mutation {
    createUser(name: String!, email: String!): User!
  }
`);

const users = [
  { id: '1', name: 'Alice', email: 'alice@example.com' },
  { id: '2', name: 'Bob', email: 'bob@example.com' }
];

const root = {
  user: ({ id }) => users.find(u => u.id === id),
  users: () => users,
  createUser: ({ name, email }) => {
    const user = { id: String(users.length + 1), name, email };
    users.push(user);
    return user;
  }
};

const query = '{ users { id name } }';

graphql({ schema, source: query, rootValue: root })
  .then(result => console.log(JSON.stringify(result, null, 2)));

const mutation = 'mutation { createUser(name: "Charlie", email: "charlie@example.com") { id name } }';

graphql({ schema, source: mutation, rootValue: root })
  .then(result => console.log(JSON.stringify(result, null, 2)));

Use Cases

Pros & Cons

Pros

+Reference implementation ensures spec compliance and compatibility with the entire GraphQL ecosystem
+Framework-agnostic design allows integration with any HTTP server, serverless platform, or custom transport layer
+Strong type system with introspection enables automatic documentation, validation, and code generation
+Fine-grained control over resolvers, execution context, and error handling without abstraction overhead
+Supports synchronous and asynchronous resolvers with Promise-based execution flow

Cons

−Low-level API requires significant boilerplate compared to frameworks like Apollo Server or TypeGraphQL
−No built-in solutions for common production needs like caching, rate limiting, or DataLoader integration
−Programmatic schema construction with `GraphQLObjectType` is verbose for large schemas compared to SDL-first tools
−Error messages for schema construction mistakes can be cryptic without understanding the internal type system
−Performance tuning requires manual optimization of resolver batching and query complexity analysis