This plugin generates
oclif CLI commands.
In order to use this GraphQL Codegen plugin, please make sure that you have GraphQL operations (
fragment) set as
documents: ... in your
Without loading your GraphQL operations (query, mutation, subscription and fragment), you won't see any change in the generated output.
The, make sure you have
typescript plugin as well in your configuration:
With GraphQL Codegen, building a CLI tool for your GraphQL API couldn't be easier. In four steps, you can have a user-friendly command-line interface:
- Generate a boilerplate CLI using
- Add GraphQL Documents (Queries & Mutations)
- Add and export a graphql client of your choice (
- Add, configure, and run the code generator
Step 1: Generate the CLI scaffold
You'll be starting from your projects directory. From there, generate the CLI skeleton using
by following the steps in their guide. You can choose either
multi type, and can switch later if you change your mind.
Step 2: Add GraphQL Documents
These documents are how
oclif will interact with your API. For each document, there will be
exactly one command.
Within the directory created by the
oclif tool, you'll have a subdirectory
where you'll put your GraphQL documents. Ie, to create a
<cli-name> hello command, you'd write a
src/commands/hello.graphql document, which will be used to generate a
file. Important: each document should have exactly one GraphQL operation.
Step 3: Add & Export a GraphQL Query Handler
Which client you use, and how you configure it, is entirely up to you! It just has to conform to
This allows you to pre-process, send, and post-process requests however you'd like, as well as format the results returned. The arguments are:
command: the command object being executed, described here in the
query: the string version of the GraphQL query being executed.
variables: the variables as configured in your GraphQL operation and parsed by
You can add a
src/handler.ts (or any other path), configure your handler function there, and then
export your handler as the default export. It's in this module that you can handle auth logic,
read config files, etc., and that will apply to all CLI operations. This file will not be modified
by the codegen.
To get started quickly and easily, consider using the simple
graphql-request as your handler:
Step 4: Add & Configure GraphQL Codegen
First, follow the GraphQL-Code-Generator guide to install it, and make sure to also install
@graphql-codegen/typescript-oclif. Then, change your
codegen.yml file to look like this:
Breaking that down:
- Reading your schema allows the codegen tool to understand what types it's working with
- The 'documents' section will collect all of your
src/types.tscreates the typescript types that the rest of the tool can reference
graphql-codegenpreset which allows one output file per input file (ie, one
.graphqldocument) rather than one output file for the whole package. This is required for
oclifto work, since it uses the file structure to generate the command structure.
typescript-operationsplugin isn't required, since this library isn't meant to be consumed programmatically (and so nothing reads the types that
clientpath is to the file which has a default export of your
graphql-requestclient, relative to the generated files (ie here,
src/commands/something/file.graphql). Note that it has no extension.
With that configured, just run
yarn graphql-codegen or
npx graphql-codegen to generate all the
oclif command files. With that complete, follow the directions in the
oclif guide to run your new CLI tool.
Descriptions & Examples
You can add descriptions and examples for your commands via
typescript-oclif with the
client-side directive, like so:
@oclif directive will not be sent to the server. Note that, for multiple examples, you must
example keys rather than an
examples array. This is a
quirk feature of
If you want a command that doesn't just execute a GraphQL Query or Mutation, then you can still
create one manually in the same way as any other
oclif application. If you wanted to add a
command, for example, you can just create a file at
src/commands/fix.ts, follow the
(ie, export a class with a
run() method), and
graphql-codegen won't disturb that file - so long
as you don't also create a
fix.graphql file next to it (in which case, it would overrride
fix.ts on the next run of