1 | # Apollo CLI
|
2 |
|
3 | [![GitHub license](https://img.shields.io/badge/license-MIT-lightgrey.svg?maxAge=2592000)](https://raw.githubusercontent.com/apollographql/apollo-tooling/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/spectrum-join-orange.svg)](https://spectrum.chat/apollo?tab=posts)
|
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/2.10.2 darwin-x64 node-v11.14.0
|
25 | $ apollo --help [COMMAND]
|
26 | USAGE
|
27 | $ apollo COMMAND
|
28 | ...
|
29 | ```
|
30 |
|
31 |
|
32 | # Commands
|
33 |
|
34 |
|
35 | * [`apollo client:check`](#apollo-clientcheck)
|
36 | * [`apollo client:codegen [OUTPUT]`](#apollo-clientcodegen-output)
|
37 | * [`apollo client:download-schema OUTPUT`](#apollo-clientdownload-schema-output)
|
38 | * [`apollo client:extract OUTPUT`](#apollo-clientextract-output)
|
39 | * [`apollo client:push`](#apollo-clientpush)
|
40 | * [`apollo help [COMMAND]`](#apollo-help-command)
|
41 | * [`apollo plugins`](#apollo-plugins)
|
42 | * [`apollo plugins:install PLUGIN...`](#apollo-pluginsinstall-plugin)
|
43 | * [`apollo plugins:link PLUGIN`](#apollo-pluginslink-plugin)
|
44 | * [`apollo plugins:uninstall PLUGIN...`](#apollo-pluginsuninstall-plugin)
|
45 | * [`apollo plugins:update`](#apollo-pluginsupdate)
|
46 | * [`apollo service:check`](#apollo-servicecheck)
|
47 | * [`apollo service:download OUTPUT`](#apollo-servicedownload-output)
|
48 | * [`apollo service:push`](#apollo-servicepush)
|
49 |
|
50 | ## `apollo client:check`
|
51 |
|
52 | Check a client project against a pushed service
|
53 |
|
54 | ```
|
55 | USAGE
|
56 | $ apollo client:check
|
57 |
|
58 | OPTIONS
|
59 | -c, --config=config Path to your Apollo config file
|
60 | -t, --tag=tag The published service tag for this client
|
61 | --clientName=clientName Name of the client that the queries will be attached to
|
62 |
|
63 | --clientReferenceId=clientReferenceId Reference id for the client which will match ids from client traces, will use
|
64 | clientName if not provided
|
65 |
|
66 | --clientVersion=clientVersion The version of the client that the queries will be attached to
|
67 |
|
68 | --endpoint=endpoint The url of your service
|
69 |
|
70 | --excludes=excludes Glob of files to exclude for GraphQL operations. Caveat: this doesn't currently
|
71 | work in watch mode
|
72 |
|
73 | --header=header Additional header to send to server for introspectionQuery. May be used
|
74 | multiple times to add multiple headers. NOTE: The `--endpoint` flag is REQUIRED
|
75 | if using the `--header` flag.
|
76 |
|
77 | --includes=includes Glob of files to search for GraphQL operations. This should be used to find
|
78 | queries *and* any client schema extensions
|
79 |
|
80 | --key=key The API key for the Apollo Engine service
|
81 |
|
82 | --queries=queries Deprecated in favor of the includes flag
|
83 |
|
84 | --tagName=tagName Name of the template literal tag used to identify template literals containing
|
85 | GraphQL queries in Javascript/Typescript code
|
86 | ```
|
87 |
|
88 | _See code: [src/commands/client/check.ts](https://github.com/apollographql/apollo-tooling/blob/master/packages/apollo/src/commands/client/check.ts)_
|
89 |
|
90 | ## `apollo client:codegen [OUTPUT]`
|
91 |
|
92 | Generate static types for GraphQL queries. Can use the published schema in Apollo Engine or a downloaded schema.
|
93 |
|
94 | ```
|
95 | USAGE
|
96 | $ apollo client:codegen [OUTPUT]
|
97 |
|
98 | ARGUMENTS
|
99 | OUTPUT
|
100 | Directory to which generated files will be written.
|
101 | - For TypeScript/Flow generators, this specifies a directory relative to each source file by default.
|
102 | - For TypeScript/Flow generators with the "outputFlat" flag is set, and for the Swift generator, this specifies a
|
103 | file or directory (absolute or relative to the current working directory) to which:
|
104 | - a file will be written for each query (if "output" is a directory)
|
105 | - all generated types will be written
|
106 | - For all other types, this defines a file (absolute or relative to the current working directory) to which all
|
107 | generated types are written.
|
108 |
|
109 | OPTIONS
|
110 | -c, --config=config Path to your Apollo config file
|
111 | -t, --tag=tag The published service tag for this client
|
112 |
|
113 | --[no-]addTypename [default: true] Automatically add __typename to your queries, can be unset
|
114 | with --no-addTypename
|
115 |
|
116 | --clientName=clientName Name of the client that the queries will be attached to
|
117 |
|
118 | --clientReferenceId=clientReferenceId Reference id for the client which will match ids from client traces, will
|
119 | use clientName if not provided
|
120 |
|
121 | --clientVersion=clientVersion The version of the client that the queries will be attached to
|
122 |
|
123 | --customScalarsPrefix=customScalarsPrefix Include a prefix when using provided types for custom scalars
|
124 |
|
125 | --endpoint=endpoint The url of your service
|
126 |
|
127 | --excludes=excludes Glob of files to exclude for GraphQL operations. Caveat: this doesn't
|
128 | currently work in watch mode
|
129 |
|
130 | --globalTypesFile=globalTypesFile By default, TypeScript will put a file named "globalTypes.ts" inside the
|
131 | "output" directory. Set "globalTypesFile" to specify a different path.
|
132 |
|
133 | --header=header Additional header to send to server for introspectionQuery. May be used
|
134 | multiple times to add multiple headers. NOTE: The `--endpoint` flag is
|
135 | REQUIRED if using the `--header` flag.
|
136 |
|
137 | --includes=includes Glob of files to search for GraphQL operations. This should be used to find
|
138 | queries *and* any client schema extensions
|
139 |
|
140 | --key=key The API key for the Apollo Engine service
|
141 |
|
142 | --localSchemaFile=localSchemaFile Path to your local GraphQL schema file (introspection result or SDL)
|
143 |
|
144 | --mergeInFieldsFromFragmentSpreads Merge fragment fields onto its enclosing type
|
145 |
|
146 | --namespace=namespace The namespace to emit generated code into.
|
147 |
|
148 | --only=only Parse all input files, but only output generated code for the specified
|
149 | file [Swift only]
|
150 |
|
151 | --operationIdsPath=operationIdsPath Path to an operation id JSON map file. If specified, also stores the
|
152 | operation ids (hashes) as properties on operation types [currently
|
153 | Swift-only]
|
154 |
|
155 | --outputFlat By default, TypeScript/Flow will put each generated file in a directory
|
156 | next to its source file using the value of the "output" as the directory
|
157 | name. Set "outputFlat" to put all generated files in the directory relative
|
158 | to the current working directory defined by "output".
|
159 |
|
160 | --passthroughCustomScalars Use your own types for custom scalars
|
161 |
|
162 | --queries=queries Deprecated in favor of the includes flag
|
163 |
|
164 | --tagName=tagName Name of the template literal tag used to identify template literals
|
165 | containing GraphQL queries in Javascript/Typescript code
|
166 |
|
167 | --target=target (required) Type of code generator to use (swift | typescript | flow |
|
168 | scala)
|
169 |
|
170 | --useFlowExactObjects Use Flow exact objects for generated types [flow only]
|
171 |
|
172 | --useFlowReadOnlyTypes Use Flow read only types for generated types [flow only]
|
173 |
|
174 | --watch Watch for file changes and reload codegen
|
175 |
|
176 | ALIASES
|
177 | $ apollo codegen:generate
|
178 | ```
|
179 |
|
180 | _See code: [src/commands/client/codegen.ts](https://github.com/apollographql/apollo-tooling/blob/master/packages/apollo/src/commands/client/codegen.ts)_
|
181 |
|
182 | ## `apollo client:download-schema OUTPUT`
|
183 |
|
184 | Download a schema from engine or a GraphQL endpoint.
|
185 |
|
186 | ```
|
187 | USAGE
|
188 | $ apollo client:download-schema OUTPUT
|
189 |
|
190 | ARGUMENTS
|
191 | OUTPUT [default: schema.json] Path to write the introspection result to
|
192 |
|
193 | OPTIONS
|
194 | -c, --config=config Path to your Apollo config file
|
195 | -t, --tag=tag The published service tag for this client
|
196 | --clientName=clientName Name of the client that the queries will be attached to
|
197 |
|
198 | --clientReferenceId=clientReferenceId Reference id for the client which will match ids from client traces, will use
|
199 | clientName if not provided
|
200 |
|
201 | --clientVersion=clientVersion The version of the client that the queries will be attached to
|
202 |
|
203 | --endpoint=endpoint The url of your service
|
204 |
|
205 | --excludes=excludes Glob of files to exclude for GraphQL operations. Caveat: this doesn't currently
|
206 | work in watch mode
|
207 |
|
208 | --header=header Additional header to send to server for introspectionQuery. May be used
|
209 | multiple times to add multiple headers. NOTE: The `--endpoint` flag is REQUIRED
|
210 | if using the `--header` flag.
|
211 |
|
212 | --includes=includes Glob of files to search for GraphQL operations. This should be used to find
|
213 | queries *and* any client schema extensions
|
214 |
|
215 | --key=key The API key for the Apollo Engine service
|
216 |
|
217 | --queries=queries Deprecated in favor of the includes flag
|
218 |
|
219 | --tagName=tagName Name of the template literal tag used to identify template literals containing
|
220 | GraphQL queries in Javascript/Typescript code
|
221 | ```
|
222 |
|
223 | _See code: [src/commands/client/download-schema.ts](https://github.com/apollographql/apollo-tooling/blob/master/packages/apollo/src/commands/client/download-schema.ts)_
|
224 |
|
225 | ## `apollo client:extract OUTPUT`
|
226 |
|
227 | Extract queries from a client
|
228 |
|
229 | ```
|
230 | USAGE
|
231 | $ apollo client:extract OUTPUT
|
232 |
|
233 | ARGUMENTS
|
234 | OUTPUT [default: manifest.json] Path to write the extracted queries to
|
235 |
|
236 | OPTIONS
|
237 | -c, --config=config Path to your Apollo config file
|
238 | -t, --tag=tag The published service tag for this client
|
239 | --clientName=clientName Name of the client that the queries will be attached to
|
240 |
|
241 | --clientReferenceId=clientReferenceId Reference id for the client which will match ids from client traces, will use
|
242 | clientName if not provided
|
243 |
|
244 | --clientVersion=clientVersion The version of the client that the queries will be attached to
|
245 |
|
246 | --endpoint=endpoint The url of your service
|
247 |
|
248 | --excludes=excludes Glob of files to exclude for GraphQL operations. Caveat: this doesn't currently
|
249 | work in watch mode
|
250 |
|
251 | --header=header Additional header to send to server for introspectionQuery. May be used
|
252 | multiple times to add multiple headers. NOTE: The `--endpoint` flag is REQUIRED
|
253 | if using the `--header` flag.
|
254 |
|
255 | --includes=includes Glob of files to search for GraphQL operations. This should be used to find
|
256 | queries *and* any client schema extensions
|
257 |
|
258 | --key=key The API key for the Apollo Engine service
|
259 |
|
260 | --queries=queries Deprecated in favor of the includes flag
|
261 |
|
262 | --tagName=tagName Name of the template literal tag used to identify template literals containing
|
263 | GraphQL queries in Javascript/Typescript code
|
264 | ```
|
265 |
|
266 | _See code: [src/commands/client/extract.ts](https://github.com/apollographql/apollo-tooling/blob/master/packages/apollo/src/commands/client/extract.ts)_
|
267 |
|
268 | ## `apollo client:push`
|
269 |
|
270 | Push a service to Engine
|
271 |
|
272 | ```
|
273 | USAGE
|
274 | $ apollo client:push
|
275 |
|
276 | OPTIONS
|
277 | -c, --config=config Path to your Apollo config file
|
278 | -t, --tag=tag The published service tag for this client
|
279 | --clientName=clientName Name of the client that the queries will be attached to
|
280 |
|
281 | --clientReferenceId=clientReferenceId Reference id for the client which will match ids from client traces, will use
|
282 | clientName if not provided
|
283 |
|
284 | --clientVersion=clientVersion The version of the client that the queries will be attached to
|
285 |
|
286 | --endpoint=endpoint The url of your service
|
287 |
|
288 | --excludes=excludes Glob of files to exclude for GraphQL operations. Caveat: this doesn't currently
|
289 | work in watch mode
|
290 |
|
291 | --header=header Additional header to send to server for introspectionQuery. May be used
|
292 | multiple times to add multiple headers. NOTE: The `--endpoint` flag is REQUIRED
|
293 | if using the `--header` flag.
|
294 |
|
295 | --includes=includes Glob of files to search for GraphQL operations. This should be used to find
|
296 | queries *and* any client schema extensions
|
297 |
|
298 | --key=key The API key for the Apollo Engine service
|
299 |
|
300 | --queries=queries Deprecated in favor of the includes flag
|
301 |
|
302 | --tagName=tagName Name of the template literal tag used to identify template literals containing
|
303 | GraphQL queries in Javascript/Typescript code
|
304 | ```
|
305 |
|
306 | _See code: [src/commands/client/push.ts](https://github.com/apollographql/apollo-tooling/blob/master/packages/apollo/src/commands/client/push.ts)_
|
307 |
|
308 | ## `apollo help [COMMAND]`
|
309 |
|
310 | display help for apollo
|
311 |
|
312 | ```
|
313 | USAGE
|
314 | $ apollo help [COMMAND]
|
315 |
|
316 | ARGUMENTS
|
317 | COMMAND command to show help for
|
318 |
|
319 | OPTIONS
|
320 | --all see all commands in CLI
|
321 | ```
|
322 |
|
323 | _See code: [@oclif/plugin-help](https://github.com/oclif/plugin-help/blob/v2.1.6/src/commands/help.ts)_
|
324 |
|
325 | ## `apollo plugins`
|
326 |
|
327 | list installed plugins
|
328 |
|
329 | ```
|
330 | USAGE
|
331 | $ apollo plugins
|
332 |
|
333 | OPTIONS
|
334 | --core show core plugins
|
335 |
|
336 | EXAMPLE
|
337 | $ apollo plugins
|
338 | ```
|
339 |
|
340 | _See code: [@oclif/plugin-plugins](https://github.com/oclif/plugin-plugins/blob/v1.7.8/src/commands/plugins/index.ts)_
|
341 |
|
342 | ## `apollo plugins:install PLUGIN...`
|
343 |
|
344 | installs a plugin into the CLI
|
345 |
|
346 | ```
|
347 | USAGE
|
348 | $ apollo plugins:install PLUGIN...
|
349 |
|
350 | ARGUMENTS
|
351 | PLUGIN plugin to install
|
352 |
|
353 | OPTIONS
|
354 | -f, --force yarn install with force flag
|
355 | -h, --help show CLI help
|
356 | -v, --verbose
|
357 |
|
358 | DESCRIPTION
|
359 | Can be installed from npm or a git url.
|
360 |
|
361 | Installation of a user-installed plugin will override a core plugin.
|
362 |
|
363 | e.g. If you have a core plugin that has a 'hello' command, installing a user-installed plugin with a 'hello' command
|
364 | will override the core plugin implementation. This is useful if a user needs to update core plugin functionality in
|
365 | the CLI without the need to patch and update the whole CLI.
|
366 |
|
367 | ALIASES
|
368 | $ apollo plugins:add
|
369 |
|
370 | EXAMPLES
|
371 | $ apollo plugins:install myplugin
|
372 | $ apollo plugins:install https://github.com/someuser/someplugin
|
373 | $ apollo plugins:install someuser/someplugin
|
374 | ```
|
375 |
|
376 | _See code: [@oclif/plugin-plugins](https://github.com/oclif/plugin-plugins/blob/v1.7.8/src/commands/plugins/install.ts)_
|
377 |
|
378 | ## `apollo plugins:link PLUGIN`
|
379 |
|
380 | links a plugin into the CLI for development
|
381 |
|
382 | ```
|
383 | USAGE
|
384 | $ apollo plugins:link PLUGIN
|
385 |
|
386 | ARGUMENTS
|
387 | PATH [default: .] path to plugin
|
388 |
|
389 | OPTIONS
|
390 | -h, --help show CLI help
|
391 | -v, --verbose
|
392 |
|
393 | DESCRIPTION
|
394 | Installation of a linked plugin will override a user-installed or core plugin.
|
395 |
|
396 | e.g. If you have a user-installed or core plugin that has a 'hello' command, installing a linked plugin with a 'hello'
|
397 | command will override the user-installed or core plugin implementation. This is useful for development work.
|
398 |
|
399 | EXAMPLE
|
400 | $ apollo plugins:link myplugin
|
401 | ```
|
402 |
|
403 | _See code: [@oclif/plugin-plugins](https://github.com/oclif/plugin-plugins/blob/v1.7.8/src/commands/plugins/link.ts)_
|
404 |
|
405 | ## `apollo plugins:uninstall PLUGIN...`
|
406 |
|
407 | removes a plugin from the CLI
|
408 |
|
409 | ```
|
410 | USAGE
|
411 | $ apollo plugins:uninstall PLUGIN...
|
412 |
|
413 | ARGUMENTS
|
414 | PLUGIN plugin to uninstall
|
415 |
|
416 | OPTIONS
|
417 | -h, --help show CLI help
|
418 | -v, --verbose
|
419 |
|
420 | ALIASES
|
421 | $ apollo plugins:unlink
|
422 | $ apollo plugins:remove
|
423 | ```
|
424 |
|
425 | _See code: [@oclif/plugin-plugins](https://github.com/oclif/plugin-plugins/blob/v1.7.8/src/commands/plugins/uninstall.ts)_
|
426 |
|
427 | ## `apollo plugins:update`
|
428 |
|
429 | update installed plugins
|
430 |
|
431 | ```
|
432 | USAGE
|
433 | $ apollo plugins:update
|
434 |
|
435 | OPTIONS
|
436 | -h, --help show CLI help
|
437 | -v, --verbose
|
438 | ```
|
439 |
|
440 | _See code: [@oclif/plugin-plugins](https://github.com/oclif/plugin-plugins/blob/v1.7.8/src/commands/plugins/update.ts)_
|
441 |
|
442 | ## `apollo service:check`
|
443 |
|
444 | Check a service against known operation workloads to find breaking changes
|
445 |
|
446 | ```
|
447 | USAGE
|
448 | $ apollo service:check
|
449 |
|
450 | OPTIONS
|
451 | -c, --config=config Path to your Apollo config file
|
452 | -t, --tag=tag The published tag to check this service against
|
453 | --endpoint=endpoint The url of your service
|
454 |
|
455 | --header=header Additional header to send to server for
|
456 | introspectionQuery. May be used multiple times to add
|
457 | multiple headers. NOTE: The `--endpoint` flag is
|
458 | REQUIRED if using the `--header` flag.
|
459 |
|
460 | --json Output result in json, which can then be parsed by CLI
|
461 | tools such as jq.
|
462 |
|
463 | --key=key The API key for the Apollo Engine service
|
464 |
|
465 | --localSchemaFile=localSchemaFile Path to your local GraphQL schema file (introspection
|
466 | result or SDL)
|
467 |
|
468 | --markdown Output result in markdown.
|
469 |
|
470 | --queryCountThreshold=queryCountThreshold Minimum number of requests within the requested time
|
471 | window for a query to be considered.
|
472 |
|
473 | --queryCountThresholdPercentage=queryCountThresholdPercentage Number of requests within the requested time window for
|
474 | a query to be considered, relative to total request
|
475 | count. Expected values are between 0 and 0.05 (minimum
|
476 | 5% of total request volume)
|
477 |
|
478 | --validationPeriod=validationPeriod The size of the time window with which to validate the
|
479 | schema against. You may provide a number (in seconds),
|
480 | or an ISO8601 format duration for more granularity
|
481 | (see: https://en.wikipedia.org/wiki/ISO_8601#Durations)
|
482 |
|
483 | ALIASES
|
484 | $ apollo schema:check
|
485 | ```
|
486 |
|
487 | _See code: [src/commands/service/check.ts](https://github.com/apollographql/apollo-tooling/blob/master/packages/apollo/src/commands/service/check.ts)_
|
488 |
|
489 | ## `apollo service:download OUTPUT`
|
490 |
|
491 | Download the schema from your GraphQL endpoint.
|
492 |
|
493 | ```
|
494 | USAGE
|
495 | $ apollo service:download OUTPUT
|
496 |
|
497 | ARGUMENTS
|
498 | OUTPUT [default: schema.json] Path to write the introspection result to
|
499 |
|
500 | OPTIONS
|
501 | -c, --config=config Path to your Apollo config file
|
502 | -k, --skipSSLValidation Allow connections to an SSL site without certs
|
503 | -t, --tag=tag [default: current] The published tag to check this service against
|
504 | --endpoint=endpoint The url of your service
|
505 |
|
506 | --header=header Additional header to send to server for introspectionQuery. May be used multiple times to add
|
507 | multiple headers. NOTE: The `--endpoint` flag is REQUIRED if using the `--header` flag.
|
508 |
|
509 | --key=key The API key for the Apollo Engine service
|
510 |
|
511 | ALIASES
|
512 | $ apollo schema:download
|
513 | ```
|
514 |
|
515 | _See code: [src/commands/service/download.ts](https://github.com/apollographql/apollo-tooling/blob/master/packages/apollo/src/commands/service/download.ts)_
|
516 |
|
517 | ## `apollo service:push`
|
518 |
|
519 | Push a service to Engine
|
520 |
|
521 | ```
|
522 | USAGE
|
523 | $ apollo service:push
|
524 |
|
525 | OPTIONS
|
526 | -c, --config=config Path to your Apollo config file
|
527 | -t, --tag=tag [default: current] The tag to publish this service to
|
528 | --endpoint=endpoint The url of your service
|
529 |
|
530 | --header=header Additional header to send to server for introspectionQuery. May be used multiple
|
531 | times to add multiple headers. NOTE: The `--endpoint` flag is REQUIRED if using the
|
532 | `--header` flag.
|
533 |
|
534 | --key=key The API key for the Apollo Engine service
|
535 |
|
536 | --localSchemaFile=localSchemaFile Path to your local GraphQL schema file (introspection result or SDL)
|
537 |
|
538 | ALIASES
|
539 | $ apollo schema:publish
|
540 | ```
|
541 |
|
542 | _See code: [src/commands/service/push.ts](https://github.com/apollographql/apollo-tooling/blob/master/packages/apollo/src/commands/service/push.ts)_
|
543 |
|
544 |
|
545 | # Configuration
|
546 |
|
547 | The Apollo CLI and VS Code extension can be configured with an Apollo config file. Apollo configuration is stored as a plain object in an `apollo.config.js` file which exports the configuration. For more information about configuring an Apollo project, see: https://bit.ly/2ByILPj.
|
548 |
|
549 | > Note: the use of the `apollo` key in the project's package.json file for configuration is deprecated, and will no longer be supported in Apollo v3
|
550 |
|
551 | You'll need to set up your Apollo configuration for all the features of the Apollo CLI and VS Code extension to work correctly. For full details on how to do that, [visit our docs](https://www.apollographql.com/docs/references/apollo-config.html). A basic configuration (`apollo.config.js` style) looks something like this:
|
552 |
|
553 | ```js
|
554 | module.exports = {
|
555 | client: {
|
556 | name: "My Client Project",
|
557 | service: "my-service-name"
|
558 | }
|
559 | };
|
560 | ```
|
561 |
|
562 | # Code Generation
|
563 |
|
564 | ## Accompanying Libraries
|
565 |
|
566 | 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.
|
567 |
|
568 | ## `gql` template support
|
569 |
|
570 | 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.
|
571 |
|
572 | The tag name is configurable using the CLI `--tagName` option.
|
573 |
|
574 | ## Typescript and Flow
|
575 |
|
576 | 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.
|
577 |
|
578 | 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.
|
579 |
|
580 | ## Why is the \_\_typename field required?
|
581 |
|
582 | 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`
|
583 | as the discriminant.
|
584 |
|
585 | For example, given a schema:
|
586 |
|
587 | ```graphql
|
588 | ...
|
589 |
|
590 | interface Character {
|
591 | name: String!
|
592 | }
|
593 |
|
594 | type Human implements Character {
|
595 | homePlanet: String
|
596 | }
|
597 |
|
598 | type Droid implements Character {
|
599 | primaryFunction: String
|
600 | }
|
601 |
|
602 | ...
|
603 | ```
|
604 |
|
605 | Whenever a field of type `Character` is encountered, it could be either a Human or Droid. Human and Droid objects
|
606 | 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.
|
607 |
|
608 | Given this query:
|
609 |
|
610 | ```graphql
|
611 | query Characters {
|
612 | characters(episode: NEW_HOPE) {
|
613 | name
|
614 |
|
615 | ... on Human {
|
616 | homePlanet
|
617 | }
|
618 |
|
619 | ... on Droid {
|
620 | primaryFunction
|
621 | }
|
622 | }
|
623 | }
|
624 | ```
|
625 |
|
626 | Apollo Codegen will generate a union type for Character.
|
627 |
|
628 | ```javascript
|
629 | export type CharactersQuery = {
|
630 | characters: Array<
|
631 | | {
|
632 | __typename: "Human",
|
633 | name: string,
|
634 | homePlanet: ?string
|
635 | }
|
636 | | {
|
637 | __typename: "Droid",
|
638 | name: string,
|
639 | primaryFunction: ?string
|
640 | }
|
641 | >
|
642 | };
|
643 | ```
|
644 |
|
645 | This type can then be used as follows to ensure that all possible types are handled:
|
646 |
|
647 | ```javascript
|
648 | function CharacterFigures({ characters }: CharactersQuery) {
|
649 | return characters.map(character => {
|
650 | switch (character.__typename) {
|
651 | case "Human":
|
652 | return (
|
653 | <HumanFigure
|
654 | homePlanet={character.homePlanet}
|
655 | name={character.name}
|
656 | />
|
657 | );
|
658 | case "Droid":
|
659 | return (
|
660 | <DroidFigure
|
661 | primaryFunction={character.primaryFunction}
|
662 | name={character.name}
|
663 | />
|
664 | );
|
665 | }
|
666 | });
|
667 | }
|
668 | ```
|
669 |
|
670 | # Contributing
|
671 |
|
672 | [![Build Status](https://circleci.com/gh/apollographql/apollo-tooling.svg?style=svg)](https://circleci.com/gh/apollographql/apollo-tooling)
|
673 |
|
674 | 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.
|
675 |
|
676 | Running tests locally:
|
677 |
|
678 | ```
|
679 | npm install
|
680 | npm test
|
681 | ```
|
682 |
|
683 | You can also run `npm` commands within package folders after you have bootstrapped the repository (part of `npm install`).
|
684 |
|
685 | > Note: if you have issues, try `npm run clean && npm i` to get a fresh install of the packages. Occasionally problems arise when removed dependencies stay around
|
686 |
|
687 | ## Nock tests
|
688 |
|
689 | To display the debugging messages for nock, run the following command:
|
690 |
|
691 | ```bash
|
692 | DEBUG=nock.* npm test
|
693 | ```
|
694 |
|
695 | It can also be helpful to print standard out during testing. To enable logging, add the following configuration to the `stdout` function call during test creation:
|
696 |
|
697 | ```
|
698 | .stdout({ print: true })
|
699 | ```
|
700 |
|
701 | ## Active Development / Debugging
|
702 |
|
703 | To simplify the development process, you may want to step through and debug commands whose behavior you're modifying. To do this, run the executable with node in debug mode like so, where `<command>` is a valid CLI command like `client:check` or `service:push`:
|
704 |
|
705 | ```
|
706 | node --inspect-brk=9002 packages/apollo/bin/run <command>
|
707 | ```
|
708 |
|
709 | If you're using VS Code, you can run the included "Attach to CLI Debugger" launch task and debug right from VS Code! Otherwise, you may use the (Chrome inspector)[https://nodejs.org/en/docs/guides/debugging-getting-started/] or other Node debugger of your choice.
|
710 |
|
711 | ## Publishing
|
712 |
|
713 | - Make sure the `CHANGELOG.md` is updated with all changes committed since the last release. Make sure the versions for each package to update are correct, and there's a blank `Upcoming` section for future work.
|
714 | - Run `npm run release` to publish the individual packages.
|
715 |
|
716 | ## Maintainers
|
717 |
|
718 | - [@jbaxleyiii](https://github.com/jbaxleyiii) (Apollo)
|
719 | - [@trevor-scheer](https://github.com/trevor-scheer) (Apollo)
|