1 | # graphql-config
|
2 |
|
3 | > The README reflects new [graphql-config protocol](specification.md).
|
4 | > Old graphql-config-parser documentation [can be found here](https://github.com/graphcool/graphql-config/tree/graphql-config-parser)
|
5 |
|
6 | The easiest way to configure your development environment with your GraphQL schema (supported by most tools, editors & IDEs)
|
7 |
|
8 | ## Supported by...
|
9 |
|
10 | ### Language Services
|
11 | * [graphql-language-service](https://github.com/graphql/graphql-language-service) - An interface for building GraphQL language services for IDEs (_pending_)
|
12 |
|
13 | ### Editors
|
14 | * [js-graphql-intellij-plugin](https://github.com/jimkyndemeyer/js-graphql-intellij-plugin) - GraphQL language support for IntelliJ IDEA and WebStorm, including Relay.QL tagged templates in JavaScript and TypeScript (_pending_)
|
15 | * [atom-language-graphql](https://github.com/rmosolgo/language-graphql) - GraphQL support for Atom text editor (_pending_)
|
16 |
|
17 | ### Tools
|
18 |
|
19 | * [babel-plugin-react-relay](https://github.com/graphcool/babel-plugin-react-relay) - Babel compile step to process your `Relay.QL` queries (_pending_)
|
20 | * [babel-plugin-transform-relay-hot](https://github.com/nodkz/babel-plugin-transform-relay-hot) - Wrapper under BabelRelayPlugin with hot reload (_pending_)
|
21 | * [eslint-plugin-graphql](https://github.com/apollostack/eslint-plugin-graphql) - An ESLint plugin that checks tagged template strings against a GraphQL schema (_pending_)
|
22 | * [webpack-plugin-graphql-schema-hot](https://github.com/nodkz/webpack-plugin-graphql-schema-hot) - Webpack plugin which tracks changes in your schema and generates its introspection in `json` and `txt` formats (_pending_)
|
23 |
|
24 | > Did we forget a tool/editor? Please [add it here](https://github.com/graphcool/graphql-config/issues/new).
|
25 |
|
26 | **[Go to `graphql-config` library docs](#graphql-config-api)**
|
27 |
|
28 | ## Usage
|
29 |
|
30 | **tl;dr**
|
31 |
|
32 | Install [`graphql-cli`](https://github.com/graphcool/graphql-cli) and run `graphql init`. Answer a few simple questions and you are set up!
|
33 |
|
34 | You can either configure your GraphQL endpoint via a configuration file `.graphqlconfig`
|
35 | (or `.graphqlconfig.yaml`) which should be put into the root of your project
|
36 |
|
37 | ### Simplest use case
|
38 |
|
39 | The simplest config specifies only `schemaPath` which is path to the file with introspection
|
40 | results or corresponding SDL document
|
41 |
|
42 | ```json
|
43 | {
|
44 | "schemaPath": "schema.graphql"
|
45 | }
|
46 | ```
|
47 |
|
48 | or
|
49 |
|
50 | ```json
|
51 | {
|
52 | "schemaPath": "schema.json"
|
53 | }
|
54 | ```
|
55 |
|
56 | ### Specifying includes/excludes files
|
57 |
|
58 | You can specify which files are included/excluded using the corresponding options:
|
59 |
|
60 | ```json
|
61 | {
|
62 | "schemaPath": "schema.graphql",
|
63 | "includes": ["*.graphql"],
|
64 | "excludes": ["temp/**"]
|
65 | }
|
66 | ```
|
67 |
|
68 | > Note: `excludes` and `includes` fields are globs that should match filename.
|
69 | > So, just `temp` or `temp/` won't match all files inside the directory.
|
70 | > That's why the example uses `temp/**`
|
71 |
|
72 | #### Specifying endpoint info
|
73 |
|
74 | You may specify your endpoints info in `.graphqlconfig` which may be used by some tools.
|
75 | The simplest case:
|
76 |
|
77 | ```json
|
78 | {
|
79 | "schemaPath": "schema.graphql",
|
80 | "extensions": {
|
81 | "endpoints": {
|
82 | "dev": "https://example.com/graphql"
|
83 | }
|
84 | }
|
85 | }
|
86 | ```
|
87 |
|
88 | In case you need provide additional information, for example headers to authenticate your GraphQL endpoint or
|
89 | an endpoint for subscription, you can use expanded version:
|
90 |
|
91 | ```json
|
92 | {
|
93 | "schemaPath": "schema.graphql",
|
94 | "extensions": {
|
95 | "endpoints": {
|
96 | "dev": {
|
97 | "url": "https://example.com/graphql",
|
98 | "headers": {
|
99 | "Authorization": "Bearer ${env:AUTH_TOKEN_ENV}"
|
100 | },
|
101 | "subscription": {
|
102 | "url": "ws://example.com/graphql",
|
103 | "connectionParams": {
|
104 | "Token": "${env:YOUR_APP_TOKEN}"
|
105 | }
|
106 | }
|
107 | }
|
108 | }
|
109 | }
|
110 | }
|
111 | ```
|
112 |
|
113 | > Note: do not save secure information in .graphqlconfig file. Use [Environment variables](specification.md#referencing-environment-variables) for that like in the example above.
|
114 |
|
115 | In case if you have multiple endpoints use the following syntax:
|
116 |
|
117 | ```json
|
118 | {
|
119 | "schemaPath": "schema.graphql",
|
120 | "extensions": {
|
121 | "endpoints": {
|
122 | "prod": {
|
123 | "url": "https://your-app.com/graphql",
|
124 | "subscription": {
|
125 | "url": "wss://subscriptions.graph.cool/v1/instagram"
|
126 | }
|
127 | },
|
128 | "dev": {
|
129 | "url": "http://localhost:3000/graphql",
|
130 | "subscription": {
|
131 | "url": "ws://localhost:3001"
|
132 | }
|
133 | }
|
134 | }
|
135 | }
|
136 | }
|
137 | ```
|
138 |
|
139 | ### Multi-project configuration (advanced)
|
140 | > TBD
|
141 |
|
142 | __Refer to [specification use-cases](specification.md#use-cases) for details__
|
143 |
|
144 | ## How it works
|
145 |
|
146 | This project aims to be provide a unifying configuration file format to configure your GraphQL schema in your development environment.
|
147 |
|
148 | Additional to the format specification, it provides the [`graphql-config`](#graphql-config-api) library, which is used by [all supported tools and editor plugins](#supported-by). The library reads your provided configuration and passes the actual GraphQL schema along to the tool which called it.
|
149 |
|
150 |
|
151 | ## `graphql-config` API
|
152 | [![Build Status](https://travis-ci.org/graphcool/graphql-config.svg?branch=master)](https://travis-ci.org/graphcool/graphql-config) [![npm version](https://badge.fury.io/js/graphql-config.svg)](https://badge.fury.io/js/graphql-config)
|
153 |
|
154 | Here are very basic examples of how to use `graphql-config` library.
|
155 |
|
156 | You can find **[the detailed documentation here](docs/)**
|
157 |
|
158 | ### getGraphQLProjectConfig
|
159 |
|
160 | **NOTE:** if your tool works on per-file basis (e.g. editor plugin, linter, etc) use
|
161 | [`getGraphQLConfig`](#getGraphQLConfig) function
|
162 |
|
163 | `getGraphQLProjectConfig` should be used by tools that do not work on per-file basis
|
164 |
|
165 | ```js
|
166 | import { getGraphQLProjectConfig } from 'graphql-config'
|
167 |
|
168 | const config = getGraphQLProjectConfig('./optionalProjectDir', 'optionalProjectName')
|
169 | const schema = config.getSchema()
|
170 | // use schema for your tool/plugin
|
171 | ```
|
172 |
|
173 | ### getGraphQLConfig
|
174 |
|
175 | `getGraphQLConfig` should be used by tools that work on per-file basis (editor plugins,
|
176 | linters, etc.)
|
177 |
|
178 | ```js
|
179 | import { getGraphQLConfig } from 'graphql-config'
|
180 |
|
181 | const config = getGraphQLConfig('./optionalProjectDir')
|
182 | const schema = config.getConfigForFile(filename).getSchema()
|
183 | // use schema for your tool/plugin
|
184 | ```
|
185 |
|
186 | ## Help & Community [![Slack Status](https://slack.graph.cool/badge.svg)](https://slack.graph.cool)
|
187 |
|
188 | Join our [Slack community](http://slack.graph.cool/) if you run into issues or have questions. We love talking to you!
|
189 |
|
190 | ![](http://i.imgur.com/5RHR6Ku.png)
|