getting-started.md

link	title	order	category
getting-started	Getting Started	0	Basics

Getting Started

Getting Started

Use the Zeus CLI to generate types and GraphQL clients based on your schema, which you can then import into your projects to autocomplete, query and use GraphQL responses in a type-safe way.

Quick Start

Installation

$ npm i -g graphql-zeus
# OR
# yarn global add graphql-zeus

You can also install locally to a project and then use as a npm or yarn script command or with npx or yarn directly eg:

$ npx zeus schema.graphql ./
# OR
# yarn zeus schema.graphql ./

TypeScript

Zeus is Typescript native, you can refer to imported types directly from the generated output of the CLI:

$ zeus schema.graphql ./

Demo Endpoint

All the demo code here was made using the demo GraphQL endpoint of Olympus Cards built with GraphQL Editor. Feel free to check out the GraphiQL interface too.

Query With Zeus Chain Client

You can now use the Zeus Chain client from the generated output to make type-safe queries and mutations to your endpoint and receive type-safe responses.

import { Chain } from './zeus';

// Create a Chain client instance with the endpoint
const chain = Chain('https://faker.graphqleditor.com/a-team/olympus/graphql');

// Query the endpoint with Typescript autocomplete for arguments and response fields
const listCardsAndDraw = await chain('query')({
  cardById: [
    {
      cardId: 'da21ce0a-40a0-43ba-85c2-6eec2bf1ae21',
    },
    {
      name: true,
      description: true,
    },
  ],
  listCards: {
    name: true,
    skills: true,
    attack: [
      { cardID: ['66c1af53-7d5e-4d89-94b5-1ebf593508f6', 'fc0e5757-4d8a-4f6a-a23b-356ce167f873'] },
      {
        name: true,
      },
    ],
  },
  drawCard: {
    name: true,
    skills: true,
    Attack: true,
  },
});
// listCardsAndDraw is now typed as the response of the query.

When querying a GraphQL field which takes an argument such as the cardById above, the fields are defined in terms of a tuple. For example for cardById: [ {...arguments} , {...response_selection_set} ] the equivalent in gql syntax would be:

cardById (cardId: "da21ce0a-40a0-43ba-85c2-6eec2bf1ae21") {
  name
  description
}

For fields which have no argument, those receive only the response selection set object values.

Note: Chain will also accept a second argument of fetch-like options to configure the client with properties such as credentials, mode, headers etc...

Note: There is also an exported Zeus Gql convenience function, it is a Chain client pre-configured with the endpoint specified in the CLI.

Listen on a WebSocket - GraphQL Subscriptions

Use the Zeus Subscription client creator in your generated output to create WebSocket connections to your GraphQL socket.

import { Subscription } from './zeus';

// Create a Subscription client instance with the endpoint
const sub = Subscription('https://faker.graphqleditor.com/a-team/olympus/graphql');

// Call the client instance and listen for responses
sub('subscription')({
  deck: {
    id: true,
  },
}).on((response) => {
  console.log(response.deck);
});

Read more about subscriptions

Usage with NodeJS

Generate clients for use with Node.js:

$ zeus schema.graphql ./  --node

Usage with React Native

As usual:

$ zeus schema.graphql ./

Other CLI Options

Specify the output folder with the second argument:

$ zeus schema.graphql ./generated

Output Typescript Only with the --typescript flag:

$ zeus schema.graphql ./ --typescript

Load your schema from a URL with a URL in the first argument:

$ zeus https://faker.graphqleditor.com/a-team/olympus/graphql ./

Download and save GraphQL schema to a local path with the --graphql=savePath flag:

$ zeus https://faker.graphqleditor.com/a-team/olympus/graphql ./ --graphql=generated

Generate and save a JSON schema to a local path with the --jsonSchema=savePath flag:

$ zeus https://faker.graphqleditor.com/a-team/olympus/graphql ./ --graphql=generated

Add a header value with the --header=value flag:

$ zeus https://faker.graphqleditor.com/a-team/olympus/graphql ./ --header=Authorization:myNiceAuthHeader

Get help with the Zeus CLI by using:

$ zeus help

Tip:

Add a script entry in your package.json file for quickly calling Zeus generation:

"scripts": {
//...
"generate": "zeus https://faker.graphqleditor.com/a-team/olympus/graphql zeusGenerated --typescript --header='My-Auth-Secret:JsercjjJY5MmghtHww6UF' --apollo"
},