About Generation generated client

This guide is an overview of using generation. Individual features enabled by generation are discussed in other guides. There is a practical tutorial in getting started. But if you're trying to build a mental model of what Graffle means when it talks about generation or generally want more detail on generation tools, then this guide is for you.

Benefits

If you haven't read the introduction, here is a recap of benefits from generation:

1. A TypeScript first interface for creating and sending requests including method names that reflect the schema.
2. Type-safe request inputs (selection set, directives, etc.).
3. Type-safe request outputs (results) inferred from the input.
4. Automatic encoding and decoding of custom scalars.
5. Type utilities to create TypeScript types based on types in the GraphQL schema.
6. Runtime utilities to create reusable selection sets.

Architecture

TODO

Multiple Clients

Sometimes you need to work with multiple schemas in one project, for example imagine having to use both the Shopify API and GitHub API. In such a case you may want to name your clients differently. Naming them has the advantage of changing the generated namespace name making it easier for you to auto-import. For that matter even when using a single client you may prefer to name it semantically.

Here is an example walkthrough.

1. You generate a client for GitHub. The default output goes to ./github.

   pnpm graffle --name Github --schema '...'

2. You can now import from it:

   import { Github } from './github/index.js'
   
   const github = Github.create({
     transport: { headers: { authorization: '...' } },
   })
   
   const repos = await github.query.viewer({ repos: { name: true } })

CLI

Typically you will use the CLI to generate a client. After installing graffle you will have access to a CLI also named graffle.

pnpm add graffle
pnpm graffle --schema '...'

The CLI has built in help that you can use to learn about all its inputs.

pnpm graffle --help

Configuration File

The CLI will by default look for a graffle.config.{js,ts,mts,mjs} file in your project. If found, it will use the default export as configuration. Any arguments you provide on the command line will take precedence over the configuration file.

// graffle.config.ts
import { SchemaErrors } from 'graffle/extensions/schema-errors/generator'
import { Generator } from 'graffle/generator'

export default Generator.configure({
  lint: {
    missingCustomScalarCodec: false,
  },
})

API

If you need to script graffle client generation then you can drop to the underlying Graffle generator API. It is largely one-to-one with the CLI. Use its JSDoc to learn about all its inputs.

import { Generator } from 'graffle/generator'

await Generator.generate({
  // ...
})