Enodia

Enodia is a GraphQL client generator for Typescript projects. It generates a fully typed client file from your GraphQL API, allowing you to have both automatic types in return of your queries and mutations, and type safety when providing arguments and fields.

Installation

As Enodia generates the client file, you can install it as a dev dependency:

npm install -D enodia

For Enodia to work, you will also need to have ts-node installed, either as a dependency in your project, or globally:

npm install -D ts-node

Finally, you will need to setup an enodia.config.ts file at the root of your project. This file should export an object with the following properties:

export default {
  // This is either the path to your graphql schema, or the URL where your API runs
  input: "./src/graphql.schema",
  // This the path where you want the client to be generated
  output: "./src/graphql.ts",
  // This is the URL of your API
  url: "http://localhost:3000/graphql",
  scalarTypes: {
    // This is a map of scalar types in your GraphQL schema to Typescript types.
    // For example, if your GraphQL schema has a `Date` scalar type, you can map
    // it to the `Date` type in Typescript.
    Date: { name: "Date" },
  },
};

More information on this file in the configuration section.

Usage

Generating the client

Once your enodia.config.ts file is setup, you can simply run Enodia:

npx enodia

This will generate a client file at the given path. You should .gitignore the generated file.

Using the client

The generated file exports a simple enodia function, which takes the URL of your API as a first parameter. The second parameter is a configuration object, allowing you to inject a custom fetch function. This can be used to handle authentication, for example. This function will return the instantiated client. The client has two properties, query and mutation containing functions to call every query and mutation your GraphQL API exposes.

Configuration

input

Enodia needs a GraphQL schema definition to generate a client. You can either use a GraphQL file:

{
  input: "./path/to/schema.graphql";
}

Or the URL of your GraphQL API:

{
  input: "http://localhost:3000/graphql";
}

output

It also needs to know where to generate the client. You need to provide a path:

{
  output: "./path/to/client.ts";
}

url

Finally, it needs to know what URL to call to make the actual calls at runtime:

{
  url: "http://localhost:3000/graphql";
}

scalarTypes

This is a map of scalar types in your GraphQL schema to Typescript types. For example, if your GraphQL schema has a Date scalar type, you can map it to the Date type in Typescript.

export default {
  scalarTypes: {
    Date: { name: "Date" },
  },
};

If you need to use custom types, you can also provide a path property, which will be used to import the type from the generated client file.

export default {
  scalarTypes: {
    Json: { name: "Json", path: "./types" },
  },
};

The name property is optional when providing a path, if the returned type is the default export of the module.

headers

This is an async function that returns an object containing the headers to send to the GraphQL API when generating the client. This can be used to handle authentication, for example. This will not be used if you point to the GraphQL schema file when running the command. This will not be used at runtime, nor will it be stored in the generated client.

import { getToken } from "./src/auth";

export default {
  headers: async () => {
    const token = await getToken();

    return {
      Authorization: `Bearer ${token}`,
    };
  },
};

React

If you want to generate hooks to use with React, simply set the react property to true:

{
  react: true;
}