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