1 | # Apollo CLI
|
2 |
|
3 | [![GitHub license](https://img.shields.io/badge/license-MIT-lightgrey.svg?maxAge=2592000)](https://raw.githubusercontent.com/apollographql/apollo-cli/master/LICENSE) [![npm](https://img.shields.io/npm/v/apollo.svg)](https://www.npmjs.com/package/apollo) [![Get on Slack](https://img.shields.io/badge/slack-join-orange.svg)](http://www.apollostack.com/#slack)
|
4 |
|
5 | Apollo CLI brings together your GraphQL clients and servers with tools for validating your schema, linting your operations for compatibility with your server, and generating static types for improved client-side type safety.
|
6 |
|
7 |
|
8 | * [Apollo CLI](#apollo-cli)
|
9 | * [Usage](#usage)
|
10 | * [Commands](#commands)
|
11 | * [Configuration](#configuration)
|
12 | * [Code Generation](#code-generation)
|
13 | * [Contributing](#contributing)
|
14 |
|
15 |
|
16 | # Usage
|
17 |
|
18 |
|
19 | ```sh-session
|
20 | $ npm install -g apollo
|
21 | $ apollo COMMAND
|
22 | running command...
|
23 | $ apollo (-v|--version|version)
|
24 | apollo/1.7.1 darwin-x64 node-v10.8.0
|
25 | $ apollo --help [COMMAND]
|
26 | USAGE
|
27 | $ apollo COMMAND
|
28 | ...
|
29 | ```
|
30 |
|
31 |
|
32 | # Commands
|
33 |
|
34 |
|
35 | * [`apollo codegen:generate [OUTPUT]`](#apollo-codegengenerate-output)
|
36 | * [`apollo help [COMMAND]`](#apollo-help-command)
|
37 | * [`apollo queries:check`](#apollo-queriescheck)
|
38 | * [`apollo schema:check`](#apollo-schemacheck)
|
39 | * [`apollo schema:download OUTPUT`](#apollo-schemadownload-output)
|
40 | * [`apollo schema:publish`](#apollo-schemapublish)
|
41 |
|
42 | ## `apollo codegen:generate [OUTPUT]`
|
43 |
|
44 | Generate static types for GraphQL queries. Can use the published schema in Apollo Engine or a downloaded schema.
|
45 |
|
46 | ```
|
47 | USAGE
|
48 | $ apollo codegen:generate [OUTPUT]
|
49 |
|
50 | ARGUMENTS
|
51 | OUTPUT
|
52 | Directory to which generated files will be written.
|
53 | - For TypeScript/Flow generators, this specifies a directory relative to each source file by default.
|
54 | - For TypeScript/Flow generators with the "outputFlat" flag is set, and for the Swift generator, this specifies a
|
55 | file or directory (absolute or relative to the current working directory) to which:
|
56 | - a file will be written for each query (if "output" is a directory)
|
57 | - all generated types will be written
|
58 | - For all other types, this defines a file (absolute or relative to the current working directory) to which all
|
59 | generated types are written.
|
60 |
|
61 | OPTIONS
|
62 | -h, --help Show command help
|
63 | --addTypename Automatically add __typename to your queries
|
64 |
|
65 | --clientSchema=clientSchema Path to your client-side GraphQL schema file for `apollo-link-state`
|
66 | (.graphql, .json, .js, .ts)
|
67 |
|
68 | --config=config Path to your Apollo config file
|
69 |
|
70 | --customScalarsPrefix=customScalarsPrefix Include a prefix when using provided types for custom scalars
|
71 |
|
72 | --key=key The API key for the Apollo Engine service
|
73 |
|
74 | --mergeInFieldsFromFragmentSpreads Merge fragment fields onto its enclosing type
|
75 |
|
76 | --namespace=namespace The namespace to emit generated code into.
|
77 |
|
78 | --only=only Parse all input files, but only output generated code for the specified
|
79 | file [Swift only]
|
80 |
|
81 | --operationIdsPath=operationIdsPath Path to an operation id JSON map file. If specified, also stores the
|
82 | operation ids (hashes) as properties on operation types [currently
|
83 | Swift-only]
|
84 |
|
85 | --outputFlat By default, TypeScript/Flow will put each generated file in a directory
|
86 | next to its source file using the value of the "output" as the directory
|
87 | name. Set "outputFlat" to put all generated files in the directory relative
|
88 | to the current working directory defined by "output".
|
89 |
|
90 | --passthroughCustomScalars Use your own types for custom scalars
|
91 |
|
92 | --queries=queries [default: **/*.graphql] Path to your GraphQL queries, can include search
|
93 | tokens like **
|
94 |
|
95 | --schema=schema Path to your GraphQL schema (.graphql, .json, .js, .ts)
|
96 |
|
97 | --tagName=tagName [default: gql] Name of the template literal tag used to identify template
|
98 | literals containing GraphQL queries in Javascript/Typescript code
|
99 |
|
100 | --target=target Type of code generator to use (swift | typescript | flow | scala), inferred
|
101 | from output
|
102 |
|
103 | --useFlowExactObjects Use Flow exact objects for generated types [flow only]
|
104 |
|
105 | --useFlowReadOnlyTypes Use Flow read only types for generated types [flow only]
|
106 |
|
107 | --watch Watch the query files to auto-generate on changes.
|
108 | ```
|
109 |
|
110 | _See code: [src/commands/codegen/generate.ts](https://github.com/apollographql/apollo-cli/blob/master/packages/apollo-cli/src/commands/codegen/generate.ts)_
|
111 |
|
112 | ## `apollo help [COMMAND]`
|
113 |
|
114 | display help for apollo
|
115 |
|
116 | ```
|
117 | USAGE
|
118 | $ apollo help [COMMAND]
|
119 |
|
120 | ARGUMENTS
|
121 | COMMAND command to show help for
|
122 |
|
123 | OPTIONS
|
124 | --all see all commands in CLI
|
125 | ```
|
126 |
|
127 | _See code: [@oclif/plugin-help](https://github.com/oclif/plugin-help/blob/v1.2.11/src/commands/help.ts)_
|
128 |
|
129 | ## `apollo queries:check`
|
130 |
|
131 | Checks your GraphQL operations for compatibility with the server. Checks against the published schema in Apollo Engine.
|
132 |
|
133 | ```
|
134 | USAGE
|
135 | $ apollo queries:check
|
136 |
|
137 | OPTIONS
|
138 | -h, --help Show command help
|
139 | --config=config Path to your Apollo config file
|
140 | --json Output result as JSON
|
141 | --key=key The API key for the Apollo Engine service
|
142 | --queries=queries Path to your GraphQL queries, can include search tokens like **
|
143 |
|
144 | --tagName=tagName [default: gql] Name of the template literal tag used to identify template literals containing
|
145 | GraphQL queries in Javascript/Typescript code
|
146 | ```
|
147 |
|
148 | _See code: [src/commands/queries/check.ts](https://github.com/apollographql/apollo-cli/blob/master/packages/apollo-cli/src/commands/queries/check.ts)_
|
149 |
|
150 | ## `apollo schema:check`
|
151 |
|
152 | Check a schema against the version registered in Apollo Engine.
|
153 |
|
154 | ```
|
155 | USAGE
|
156 | $ apollo schema:check
|
157 |
|
158 | OPTIONS
|
159 | -h, --help Show command help
|
160 | --config=config Path to your Apollo config file
|
161 | --endpoint=endpoint The URL of the server to fetch the schema from
|
162 | --header=header Additional headers to send to server for introspectionQuery
|
163 | --json Output result as JSON
|
164 | --key=key The API key for the Apollo Engine service
|
165 | ```
|
166 |
|
167 | _See code: [src/commands/schema/check.ts](https://github.com/apollographql/apollo-cli/blob/master/packages/apollo-cli/src/commands/schema/check.ts)_
|
168 |
|
169 | ## `apollo schema:download OUTPUT`
|
170 |
|
171 | Download the schema from your GraphQL endpoint.
|
172 |
|
173 | ```
|
174 | USAGE
|
175 | $ apollo schema:download OUTPUT
|
176 |
|
177 | ARGUMENTS
|
178 | OUTPUT [default: schema.json] Path to write the introspection result to
|
179 |
|
180 | OPTIONS
|
181 | -h, --help Show command help
|
182 | --config=config Path to your Apollo config file
|
183 | --endpoint=endpoint The URL of the server to fetch the schema from or path to ./your/local/schema.graphql
|
184 | --header=header Additional headers to send to server for introspectionQuery
|
185 | --key=key The API key for the Apollo Engine service
|
186 | ```
|
187 |
|
188 | _See code: [src/commands/schema/download.ts](https://github.com/apollographql/apollo-cli/blob/master/packages/apollo-cli/src/commands/schema/download.ts)_
|
189 |
|
190 | ## `apollo schema:publish`
|
191 |
|
192 | Publish a schema to Apollo Engine
|
193 |
|
194 | ```
|
195 | USAGE
|
196 | $ apollo schema:publish
|
197 |
|
198 | OPTIONS
|
199 | -h, --help Show command help
|
200 | --config=config Path to your Apollo config file
|
201 | --endpoint=endpoint The URL of the server to fetch the schema from
|
202 | --header=header Additional headers to send to server for introspectionQuery
|
203 | --json Output successful publish result as JSON
|
204 | --key=key The API key for the Apollo Engine service
|
205 | ```
|
206 |
|
207 | _See code: [src/commands/schema/publish.ts](https://github.com/apollographql/apollo-cli/blob/master/packages/apollo-cli/src/commands/schema/publish.ts)_
|
208 |
|
209 |
|
210 | # Configuration
|
211 |
|
212 | The Apollo CLI and VS Code extension can be configured with an Apollo Config file. Apollo configuration is stored as a plain object and can be either specified under the `apollo` key in your `package.json` or as a separate `apollo.config.js` which exports the config data.
|
213 |
|
214 | The core of any configuration is specifying schemas and queries. Schemas specify information about your backend such as where to get the schema, what endpoint to make requests against, and the Apollo Engine API key to get schema updates and stats from. Queries define which documents Apollo tooling should analyze and tie them to the schema they are targeting.
|
215 |
|
216 | Let's take a look at a basic configuration file (`package.json` style):
|
217 |
|
218 | ```js
|
219 | {
|
220 | ...
|
221 | "apollo": {
|
222 | "schemas": {
|
223 | "myPrimaryBackend": {
|
224 | "schema": "downloadedSchema.json", // if not defined the an introspection query will be run
|
225 | "endpoint": "http://example.com/graphql", // if not defined the schema will be downloaded from Apollo Engine
|
226 | "engineKey": "my-engine-key" // use this key when connecting to Apollo Engine
|
227 | }
|
228 | },
|
229 | "queries": [ // optional if you only have one schema
|
230 | {
|
231 | "schema": "myPrimaryBackend", // reference the previously defined schema
|
232 | "includes": [ "**/*.tsx" ], // load queries from .tsx files
|
233 | "excludes": [ "node_modules/**" ] // don't include any matching files from node_modules
|
234 | }
|
235 | ]
|
236 | }
|
237 | }
|
238 | ```
|
239 |
|
240 | Or in `apollo.config.js` style:
|
241 |
|
242 | ```js
|
243 | ...
|
244 |
|
245 | module.exports = {
|
246 | schemas: {
|
247 | myPrimaryBackend: {
|
248 | schema: "downloadedSchema.json", // if not defined the an introspection query will be run
|
249 | endpoint: "http://example.com/graphql", // if not defined the schema will be downloaded from Apollo Engine
|
250 | engineKey: "my-engine-key" // use this key when connecting to Apollo Engine
|
251 | }
|
252 | },
|
253 | queries: [ // optional if you only have one schema
|
254 | {
|
255 | schema: "myPrimaryBackend", // reference the previously defined schema
|
256 | includes: [ "**/*.tsx" ], // load queries from .tsx files
|
257 | excludes: [ "node_modules/**" ] // don't include any matching files from node_modules
|
258 | }
|
259 | ]
|
260 | }
|
261 | ```
|
262 |
|
263 | ## Endpoint Configuration
|
264 |
|
265 | When configuring a schema's endpoint, you can either pass in a string or an object, which allows for specifying advanced options like headers and subscription endpoints.
|
266 |
|
267 | ```js
|
268 | endpoint: {
|
269 | url: "http://example.com/graphql",
|
270 | subscriptions: "ws://example.com/graphql",
|
271 | headers: {
|
272 | cookie: "myCookie=myCookieValue"
|
273 | }
|
274 | }
|
275 | ```
|
276 |
|
277 | ## Schema Dependencies
|
278 |
|
279 | Schemas can also declare dependencies on eachother, which can be useful in situations like having a client-side schema for `apollo-link-state`. To declare a dependency, use the `extends` key. When working with a client-side schema, make sure to also specify the `clientSide` key to enable code-generation support.
|
280 |
|
281 | ```js
|
282 | schemas: {
|
283 | myServerSideSchema: {
|
284 | ...
|
285 | },
|
286 | myClientSideSchema: {
|
287 | extends: "myServerSideSchema",
|
288 | clientSide: true
|
289 | ...
|
290 | }
|
291 | }
|
292 | ```
|
293 |
|
294 | # Code Generation
|
295 |
|
296 | ## Accompanying Libraries
|
297 |
|
298 | See [Apollo iOS](https://github.com/apollographql/apollo-ios) for details on the mapping from GraphQL results to Swift types, as well as runtime support for executing queries and mutations. For Scala, see [React Apollo Scala.js](https://github.com/apollographql/react-apollo-scalajs) for details on how to use generated Scala code in a Scala.js app with Apollo Client.
|
299 |
|
300 | ## `gql` template support
|
301 |
|
302 | If the source file for generation is a JavaScript or TypeScript file, the codegen will try to extrapolate the queries inside the [gql tag](https://github.com/apollographql/graphql-tag) templates.
|
303 |
|
304 | The tag name is configurable using the CLI `--tagName` option.
|
305 |
|
306 | ## Typescript and Flow
|
307 |
|
308 | When using the codegen command with Typescript or Flow, make sure to add the `__typename` introspection field to every selection set within your graphql operations.
|
309 |
|
310 | If you're using a client like `apollo-client` that does this automatically for your GraphQL operations, pass in the `--addTypename` option to `apollo codegen:generate` to make sure the generated Typescript and Flow types have the `__typename` field as well. This is required to ensure proper type generation support for `GraphQLUnionType` and `GraphQLInterfaceType` fields.
|
311 |
|
312 | ## Why is the \_\_typename field required?
|
313 |
|
314 | Using the type information from the GraphQL schema, we can infer the possible types for fields. However, in the case of a `GraphQLUnionType` or `GraphQLInterfaceType`, there are multiple types that are possible for that field. This is best modeled using a disjoint union with the `__typename`
|
315 | as the discriminant.
|
316 |
|
317 | For example, given a schema:
|
318 |
|
319 | ```graphql
|
320 | ...
|
321 |
|
322 | interface Character {
|
323 | name: String!
|
324 | }
|
325 |
|
326 | type Human implements Character {
|
327 | homePlanet: String
|
328 | }
|
329 |
|
330 | type Droid implements Character {
|
331 | primaryFunction: String
|
332 | }
|
333 |
|
334 | ...
|
335 | ```
|
336 |
|
337 | Whenever a field of type `Character` is encountered, it could be either a Human or Droid. Human and Droid objects
|
338 | will have a different set of fields. Within your application code, when interacting with a `Character` you'll want to make sure to handle both of these cases.
|
339 |
|
340 | Given this query:
|
341 |
|
342 | ```graphql
|
343 | query Characters {
|
344 | characters(episode: NEW_HOPE) {
|
345 | name
|
346 |
|
347 | ... on Human {
|
348 | homePlanet
|
349 | }
|
350 |
|
351 | ... on Droid {
|
352 | primaryFunction
|
353 | }
|
354 | }
|
355 | }
|
356 | ```
|
357 |
|
358 | Apollo Codegen will generate a union type for Character.
|
359 |
|
360 | ```javascript
|
361 | export type CharactersQuery = {
|
362 | characters: Array<
|
363 | | {
|
364 | __typename: "Human",
|
365 | name: string,
|
366 | homePlanet: ?string
|
367 | }
|
368 | | {
|
369 | __typename: "Droid",
|
370 | name: string,
|
371 | primaryFunction: ?string
|
372 | }
|
373 | >
|
374 | };
|
375 | ```
|
376 |
|
377 | This type can then be used as follows to ensure that all possible types are handled:
|
378 |
|
379 | ```javascript
|
380 | function CharacterFigures({ characters }: CharactersQuery) {
|
381 | return characters.map(character => {
|
382 | switch (character.__typename) {
|
383 | case "Human":
|
384 | return (
|
385 | <HumanFigure
|
386 | homePlanet={character.homePlanet}
|
387 | name={character.name}
|
388 | />
|
389 | );
|
390 | case "Droid":
|
391 | return (
|
392 | <DroidFigure
|
393 | primaryFunction={character.primaryFunction}
|
394 | name={character.name}
|
395 | />
|
396 | );
|
397 | }
|
398 | });
|
399 | }
|
400 | ```
|
401 |
|
402 | # Contributing
|
403 |
|
404 | [![Build status](https://travis-ci.org/apollographql/apollo-cli.svg?branch=master)](https://travis-ci.org/apollographql/apollo-cli)
|
405 |
|
406 | This repo is composed of multiple packages managed by Lerna. The `apollo-cli` contains the core CLI commands. The `apollo-codegen-core` package contains all the compiler APIs needed to implement code generation support for new languages. The other `apollo-codegen-*` packages implement code generation support for individual languages.
|
407 |
|
408 | Running tests locally:
|
409 |
|
410 | ```
|
411 | npm install
|
412 | npm test
|
413 | ```
|
414 |
|
415 | You can also run `npm` commands within package folders after you have bootstrapped the repository (part of `npm install`).
|
416 |
|
417 | ```
|
418 |
|
419 | ```
|