1 | # GraphQL.js
|
2 |
|
3 | The JavaScript reference implementation for GraphQL, a query language for APIs created by Facebook.
|
4 |
|
5 | [![npm version](https://badge.fury.io/js/graphql.svg)](https://badge.fury.io/js/graphql)
|
6 | [![Build Status](https://travis-ci.org/graphql/graphql-js.svg?branch=master)](https://travis-ci.org/graphql/graphql-js?branch=master)
|
7 | [![Coverage Status](https://codecov.io/gh/graphql/graphql-js/branch/master/graph/badge.svg)](https://codecov.io/gh/graphql/graphql-js)
|
8 |
|
9 | See more complete documentation at https://graphql.org/ and
|
10 | https://graphql.org/graphql-js/.
|
11 |
|
12 | Looking for help? Find resources [from the community](https://graphql.org/community/).
|
13 |
|
14 | ## Getting Started
|
15 |
|
16 | An overview of GraphQL in general is available in the
|
17 | [README](https://github.com/graphql/graphql-spec/blob/master/README.md) for the
|
18 | [Specification for GraphQL](https://github.com/graphql/graphql-spec). That overview
|
19 | describes a simple set of GraphQL examples that exist as [tests](src/__tests__)
|
20 | in this repository. A good way to get started with this repository is to walk
|
21 | through that README and the corresponding tests in parallel.
|
22 |
|
23 | ### Using GraphQL.js
|
24 |
|
25 | Install GraphQL.js from npm
|
26 |
|
27 | With yarn:
|
28 |
|
29 | ```sh
|
30 | yarn add graphql
|
31 | ```
|
32 |
|
33 | or alternatively using npm:
|
34 |
|
35 | ```sh
|
36 | npm install --save graphql
|
37 | ```
|
38 |
|
39 | GraphQL.js provides two important capabilities: building a type schema, and
|
40 | serving queries against that type schema.
|
41 |
|
42 | First, build a GraphQL type schema which maps to your code base.
|
43 |
|
44 | ```js
|
45 | import {
|
46 | graphql,
|
47 | GraphQLSchema,
|
48 | GraphQLObjectType,
|
49 | GraphQLString,
|
50 | } from 'graphql';
|
51 |
|
52 | var schema = new GraphQLSchema({
|
53 | query: new GraphQLObjectType({
|
54 | name: 'RootQueryType',
|
55 | fields: {
|
56 | hello: {
|
57 | type: GraphQLString,
|
58 | resolve() {
|
59 | return 'world';
|
60 | },
|
61 | },
|
62 | },
|
63 | }),
|
64 | });
|
65 | ```
|
66 |
|
67 | This defines a simple schema with one type and one field, that resolves
|
68 | to a fixed value. The `resolve` function can return a value, a promise,
|
69 | or an array of promises. A more complex example is included in the top
|
70 | level [tests](src/__tests__) directory.
|
71 |
|
72 | Then, serve the result of a query against that type schema.
|
73 |
|
74 | ```js
|
75 | var query = '{ hello }';
|
76 |
|
77 | graphql(schema, query).then(result => {
|
78 | // Prints
|
79 | // {
|
80 | // data: { hello: "world" }
|
81 | // }
|
82 | console.log(result);
|
83 | });
|
84 | ```
|
85 |
|
86 | This runs a query fetching the one field defined. The `graphql` function will
|
87 | first ensure the query is syntactically and semantically valid before executing
|
88 | it, reporting errors otherwise.
|
89 |
|
90 | ```js
|
91 | var query = '{ boyhowdy }';
|
92 |
|
93 | graphql(schema, query).then(result => {
|
94 | // Prints
|
95 | // {
|
96 | // errors: [
|
97 | // { message: 'Cannot query field boyhowdy on RootQueryType',
|
98 | // locations: [ { line: 1, column: 3 } ] }
|
99 | // ]
|
100 | // }
|
101 | console.log(result);
|
102 | });
|
103 | ```
|
104 |
|
105 | ### Want to ride the bleeding edge?
|
106 |
|
107 | The `npm` branch in this repository is automatically maintained to be the last
|
108 | commit to `master` to pass all tests, in the same form found on npm. It is
|
109 | recommended to use builds deployed to npm for many reasons, but if you want to use
|
110 | the latest not-yet-released version of graphql-js, you can do so by depending
|
111 | directly on this branch:
|
112 |
|
113 | ```
|
114 | npm install graphql@git://github.com/graphql/graphql-js.git#npm
|
115 | ```
|
116 |
|
117 | ### Using in a Browser
|
118 |
|
119 | GraphQL.js is a general purpose library and can be used both in a Node server
|
120 | and in the browser. As an example, the [GraphiQL](https://github.com/graphql/graphiql/)
|
121 | tool is built with GraphQL.js!
|
122 |
|
123 | Building a project using GraphQL.js with [webpack](https://webpack.js.org) or
|
124 | [rollup](https://github.com/rollup/rollup) should just work and only include
|
125 | the portions of the library you use. This works because GraphQL.js is distributed
|
126 | with both CommonJS (`require()`) and ESModule (`import`) files. Ensure that any
|
127 | custom build configurations look for `.mjs` files!
|
128 |
|
129 | ### Contributing
|
130 |
|
131 | We actively welcome pull requests, learn how to
|
132 | [contribute](https://github.com/graphql/graphql-js/blob/master/.github/CONTRIBUTING.md).
|
133 |
|
134 | ### Changelog
|
135 |
|
136 | Changes are tracked as [GitHub releases](https://github.com/graphql/graphql-js/releases).
|
137 |
|
138 | ### License
|
139 |
|
140 | GraphQL.js is [MIT-licensed](https://github.com/graphql/graphql-js/blob/master/LICENSE).
|