Guide · Open source

How to use graphql-js: install, build a schema and run queries

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

graphql-js is the official JavaScript reference implementation of GraphQL, the query language for APIs created by Facebook. It lets you define a typed schema that maps to your code and run queries against it, with queries validated before they execute. This guide walks through installing the package, building a small schema, running queries, and deciding whether it fits your project.

GraphQL.jsgraphql/graphql-js · ★ 20.3k · MIT Install options & downloads

Quick start

1Install the package. Run npm install --save graphql, or use yarn add graphql or bun add graphql.
2Import the building blocks. Import graphql, GraphQLSchema, GraphQLObjectType and GraphQLString from the graphql package.
3Define a schema. Create a GraphQLSchema with a query root type and at least one field that has a type and a resolve function.
4Run a query. Call graphql with your schema and a query string, then read the data or errors from the result.
5Check the errors. Query a field that does not exist to see how validation errors are reported.

Install graphql-js with npm, yarn or bun

GraphQL.js is installed from npm. The README lists three package managers. Pick the one your project already uses. The package name is graphql.

npm: use the command below
yarn: yarn add graphql
bun: bun add graphql

npm install --save graphql

Build a GraphQL schema in JavaScript

GraphQL.js provides two core capabilities: building a type schema and serving queries against that schema. First, you build a schema that maps to your codebase. The example below defines one type with one field, hello, which resolves to a fixed value.

The resolve function can return a value, a promise, or an array of promises. A more complex example is included in the top-level tests directory of the repository.

import {
  graphql,
  GraphQLSchema,
  GraphQLObjectType,
  GraphQLString,
} from 'graphql';

var schema = new GraphQLSchema({
  query: new GraphQLObjectType({
    name: 'RootQueryType',
    fields: {
      hello: {
        type: GraphQLString,
        resolve() {
          return 'world';
        },
      },
    },
  }),
});

Run a query against your schema

Next, serve the result of a query against the schema using the graphql function. It returns a promise that resolves to a result object containing data.

The graphql function first checks that the query is syntactically and semantically valid before executing it, and reports errors otherwise.

var source = '{ hello }';

graphql({ schema, source }).then((result) => {
  // Prints
  // {
  //   data: { hello: "world" }
  // }
  console.log(result);
});

Understand query validation errors

If a query asks for a field the schema does not define, graphql-js does not run it. It returns an errors array with a message and the line and column location of the problem. The README's example queries a field called BoyHowdy, which does not exist on RootQueryType.

The result contains errors instead of data when validation fails.
Each error includes a message and locations with line and column.

var source = '{ BoyHowdy }';

graphql({ schema, source }).then((result) => {
  // Prints
  // {
  //   errors: [
  //     { message: 'Cannot query field BoyHowdy on RootQueryType',
  //       locations: [ { line: 1, column: 3 } ] }
  //   ]
  // }
  console.log(result);
});

Use graphql-js in the browser

GraphQL.js is a general-purpose library and can be used both in a Node server and in the browser. The README notes that GraphiQL, a GraphQL browser tool, is built with GraphQL.js.

Bundlers such as webpack or rollup should include only the parts of the library you use. The package ships both CommonJS (require()) and ES module (import) files, and the exports map in package.json directs runtimes and bundlers to the right file. Tools that do not support exports find the CommonJS build in .js files and the ES module build in .mjs files.

Choose a version and understand support

The project follows Semantic Versioning. The latest major version gets full support, including bug fixes and security updates. The previous major version gets feature support for 12 months after a newer major release, then bug and security fixes. The README states there is no Long-Term Support version, so the maintainers encourage upgrading to the latest stable release.

To try unreleased code, the README describes depending directly on the npm branch of the repository. It recommends using published npm builds for most projects.

Upgrade guides and migration docs are linked from the README.
Release notes are published as GitHub releases.
Community help is available through the GraphQL Discord, channel #graphql-js.

npm install graphql@git://github.com/graphql/graphql-js.git#npm

What people use it for

Building a GraphQL API server in Node.js with a typed schema that maps to your existing code.
Running queries against a schema inside a Node.js script or test suite.
Building browser-side tools that work with GraphQL schemas, as GraphiQL does.
Using graphql-js as the base that other GraphQL tools are built on.

Frequently asked questions

Is graphql-js free to use?

Yes. GraphQL.js is MIT-licensed, as stated in the README, and the LICENSE file is in the repository. Contributing to the project requires signing a free GraphQL Specification Membership agreement, but using the library does not.

What do I need to install graphql-js?

The listed prerequisite is Node.js. You install the graphql package from npm, using npm install --save graphql, yarn add graphql or bun add graphql.

Can graphql-js run in the browser?

Yes. The README says it is a general-purpose library that can be used in a Node server and in the browser. Bundlers like webpack and rollup should include only the parts you use.

Is graphql-js the same as GraphQL?

No. GraphQL is the query language for APIs, originally created by Facebook. GraphQL.js is the JavaScript reference implementation of it.

How does graphql-js compare with Apollo Server, express-graphql, Yoga or Mercurius?

Those are comparable projects that also work with GraphQL in JavaScript. This page does not benchmark them. graphql-js is the reference implementation that other GraphQL tools are built on, so choose it for the base library and compare the others on the features you need.

Does graphql-js have a Long-Term Support version?

No. The README says there is no LTS version, and users are encouraged to upgrade to the latest stable version for updates and security fixes.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

graphql-js suits JavaScript or TypeScript developers who are building a GraphQL API on Node.js, or who want the reference implementation that other tools depend on. If you only need to call an existing GraphQL API from a client, or you are not comfortable with JavaScript and schemas, a client library is a better fit.

Install options & downloads