GraphQL.js for JavaScript (Node.js): Complete Guide

\n\n

1. What is it and why is it needed?

\n\n

GraphQL.js is the reference implementation of the GraphQL specification in JavaScript. It provides a complete set of tools for creating, executing, and validating GraphQL queries on the server side (Node.js) and in the browser. Unlike REST API, where each endpoint returns a fixed data structure, GraphQL allows the client to precisely request only the data it needs, and nothing extra. This solves the problem of over-fetching (receiving excessive data) and under-fetching (insufficient data), which is critical for the performance of mobile applications and complex web interfaces.

\n\n

The GraphQL.js library is the foundation for all popular GraphQL frameworks in the JavaScript ecosystem, such as Apollo Server, Express-GraphQL, Yoga, and others. It handles the heavy lifting of parsing queries, validating them, executing resolvers, and forming a response in strict accordance with the specification. By using GraphQL.js directly, you gain maximum control over the query processing flow, which is especially important when creating custom middleware, testing tools, or integrating with non-standard data sources.

\n\n

The main advantages of using GraphQL.js include: strict schema typing, automatic documentation generation (via Introspection Query), the ability to efficiently combine data from multiple sources (databases, REST APIs, microservices) in a single query, as well as built-in mechanisms for error handling and pagination. This makes the library indispensable for building modern, scalable, and flexible APIs.

\n\n

2. Installation

\n\n

The library is installed via the npm (Node Package Manager) package manager. Make sure you have Node.js version 12 or higher installed.

\n\n

npm install graphql

\n\n

To use in a project with ES module support (type: "module" in package.json), import the functions as follows:

\n\n

import { graphql, buildSchema } from 'graphql';

\n\n

For CommonJS (standard approach in Node.js):

\n\n

const { graphql, buildSchema } = require('graphql');

\n\n

3. Quick Start — Minimal Working Example

\n\n

Below is a simple server that accepts a GraphQL query and returns a greeting. This example demonstrates the core of the library: schema definition, resolvers, and query execution.

\n\n

const { graphql, buildSchema } = require('graphql');\n\n// 1. Define the schema (Schema Definition Language - SDL)\nconst schema = buildSchema(`\n  type Query {\n    hello: String\n  }\n`);\n\n// 2. Define the root resolver\nconst rootValue = {\n  hello: () => {\n    return 'Hello, GraphQL.js!';\n  },\n};\n\n// 3. Execute the query\nconst query = '{ hello }';\n\ngraphql({\n  schema,\n  source: query,\n  rootValue,\n}).then((response) => {\n  console.log(JSON.stringify(response, null, 2));\n  // Output: { "data": { "hello": "Hello, GraphQL.js!" } }\n});\n

\n\n

4. Main Methods/Functions/Classes

\n\n

4.1. `buildSchema(schemaString: string): GraphQLSchema`

What it does: Parses a string written in the GraphQL Schema Definition Language (SDL) and creates a GraphQLSchema object. This is the fastest way to define a schema without using a programmatic constructor.

const { buildSchema } = require('graphql');\n\nconst schema = buildSchema(`\n  type Query {\n    user(id: ID!): User\n  }\n  type User {\n    id: ID\n    name: String\n  }\n`);\n

\n\n