Essential Workflows

1. Setup

Before getting started, the gql-tada CLI has the generate schema and doctor commands to help with getting all set up.

Downloading Schemas

The schema setting supports loading your GraphQL schema from an SDL or introspection file, as well as making a GraphQL introspection request to a URL.

While this is convenient you may not want your schema to be introspected from an API running locally or remotely indefinitely. However, as you may not be maintaining your GraphQL API in the same repository or your GraphQL server may not output an SDL file itself, the generate schema CLI command exists to close this gap.

To introspect an API and download your schema, run the generate schema command while passing your API's URL.

gql-tada generate schema 'http://api.test/graphql' --output './schema.graphql'

When no --output argument is passed, the command will attempt to use your configuration's schema setting, provided it's a file path.

You may also pass --header arguments, which define headers sent during the GraphQL introspection request. If a GraphQL endpoint requires authentication headers, you may use this to pass in tokens or authorization headers.

gql-tada generate schema 'http://api.test/graphql' --header "Authorization: $ENV_TOKEN"

CLI Reference

Learn more about the generate-schema command

---

The doctor command

Since you've run through the steps on the Installation page, you may have seen that there are several moving parts to gql.tada, including needing an output file to be generated and relying on the TypeScript plugin to display diagnostics.

To prevent any of these parts working improperly, and to detect whether there are any issues in your configuration or with your setup, the doctor command exists.

gql-tada doctor

The doctor command runs through several environment checks, loads your configuration, and checks your schema to make sure you don't run into any unexpected issues.

While it's entirely optional, it doesn't hurt to run it before you get started or when onboarding a new team member onto gql.tada.

2. Editing

While editing, the TypeScript plugin will update the gql.tada output file and display diagnostics, but we can achieve the same using the generate output and check commands.

Usually while editing your code, the TypeScript plugin takes care of several things automatically:

• it generates the output typings file
• it provides type hints and suggestions
• it displays diagnostics when it detects a problem

However, you can also generate the output typings file or get diagnostics outside of your editor. This is especially important if you need diagnostics or the output file before or without opening your editor, or if your editor does not support TypeScript plugins.

Generating the output file

As we've learned on the Installation page, the output typings file is necessary for gql.tada to infer types of GraphQL documents as it contains an introspection type of your schema.

To generate the output typings file, use the gql-tada CLI's generate turbo command.

gql-tada generate output

The generate output command loads your schema, generates introspection output and finally saves the output typings file.

Just like the TypeScript plugin, the command will use the tadaOutputLocation setting to determine where to write the output file to, and will load your schema using the schema setting:

tsconfig.json

{
  "compilerOptions": {
    "plugins": [
      {
        "name": "gql.tada/ts-plugin",
        "schema": "./schema.graphql"
        "tadaOutputLocation": "./src/graphql-env.d.ts"
      }
    ]
  }
}

The output typings file essentially contains the regular introspection data of your schema. If the format is changed from a .d.ts to a .ts file, the introspection data is even reusable for runtime code. However, the d.ts file type is recommended as it's more efficient for the TypeScript type checker for larger schemas. This format is also preprocessed into an intermediary format.

Config Format

Learn more about the tadaOutputLocation setting

CLI Reference

See more arguments the generate-output command accepts

Should the output tyings file be committed?

You can decide yourself whether you want to check the output typings file into version control.

Without the typings file, GraphQL types can't be inferred and you'll get errors when running type checks, for example with the tsc command. Committing the output file to your repository has the advantage that you'll always be in a state to run type checks.

---

Running diagnostics

The TypeScript plugin runs several checks on your code, providing diagnostics releant to your GraphQL schema right in your editor. But to run gql.tada's diagnostics as a standalone process we can use the CLI's check command instead. The command runs all diagnostics and gives us an idea of GraphQL-related issues across a whole workspace.

gql-tada check

The check command loads your schema then runs diagnostics on your code. This includes both diagnostics specific to gql.tada as well as GraphQL validation, and checks against your GraphQL schema.

The GraphQL checks that are run are basically the same that your GraphQL server would run during GraphQL Validation. For example, when you write a query that selects fields that don't exist on your schema, or you pass invalid arguments to a field an error will be displayed.

Why doesn't tsc show me diagnostics?

TypeScript plugins are hook into the TypeScript language server API, which is specific to editor and IDE features. During other tasks, like when you run tsc or other TypeScript compiler tools, TypeScript plugins aren't loaded.

The gql-tada check command exists to be a standalone version of GraphQL-related diagnostics instead and itself loads the TypeScript plugin's diagnostics code.

Two diagnostics that feature in gql.tada output opinionated warnings that may not be relevant to your codebase:

• trackFieldUsage
• shouldCheckForColocatedFragments

CLI Reference

Learn more about the CLI's check command

3. Committing

Before we commit and push our work, we can use the turbo command to speed up TypeScript's type checks for all our GraphQL documents.

gql.tada usually infers the types of GraphQL documents entirely in TypeScript's type system. It has types to parses documents and convert them to types. If you worked with TypeScript before you may have already spotted a problem here.

For each GraphQL document you add more, TypeScript's type checker has more work to do, and over time type checking will get slower and slower as your codebase grows.

Turbo Mode

To help with this and prevent performance issues, the gql-tada CLI has a turbo command that pre-processes types and outputs a type cache.

gql-tada turbo

The turbo command scans your codebase for GraphQL documents and evaluates their TypeScript types ahead of time. It will then write these types to a type cache, which contains all your documents' pre-evaluated types.

You can update your configuration to change where this type cache gets written to with the tadaTurboLocation setting:

tsconfig.json

{
  "compilerOptions": {
    "plugins": [
      {
        "name": "gql.tada/ts-plugin",
        "schema": "./schema.graphql"
        "tadaOutputLocation": "./src/graphql-env.d.ts",
        "tadaTurboLocation": "./src/graphql-cache.d.ts"
      }
    ]
  }
}

If you inspect the written file, you'll see that it's a regular d.ts typings file which contains a map of GraphQL document strings, as they appear in your code, to TypeScript type literals.

If you're familiar with GraphQL type generation tools, you may recognize that this is essentially a compromise between "codegen tools", which are explained further on the page on "Typed Documents", and the pure type inference approach that gql.tada takes out of the box.

Should the type cache be committed?

You can decide yourself whether you want to check the type cache file into version control.

Committing it to your repository has the advantage that when you or someone else starts working on a new set of changes, TypeScript's type checks will be as fast as they can be, which can improve the Developer Experience on larger codebases.

4. CI Checks

For after we commit and push our work, we can set up our CI environment with the gql-tada CLI commands we've now seen to output files and run diagnostics.

Integrating the gql-tada CLI into your continuous integration pipeline takes just adding a few commands and should effectively replicate the errors you may see in an editor when using gql.tada.

At the very least, you'll likely want to run the check command in your CI environment.

gql-tada generate output
gql-tada check

GitHub Actions Example

If you're using GitHub Actions, you can run the commands in a simple step in your workflow's jobs.

- name: "gql.tada Checks"
  run: |
    gql-tada generate output
    gql-tada check

On GitHub Actions, the check command will also integrate with GitHub's, and annotate errors and warnings inside the GitHub UI on pull requests, for instance.

The generate output command, as previously mentioned, generates the typings output file and since this file is necessary for type inference, if it's not generated and missing, running type checks (for instance, with tsc) will likely fail with type errors.

Uncommitted output files

As you've seen on this page, there are two different output files we're concerned with when running inside an continuous integration environment.

• the output typings file (via the generate output command)
• the type cache file (via the turbo command)

Checking these files into your repository makes sure that your codebase is less reliant on running gql.tada, and that anyone who clones your code does not have to even know how to use gql.tada.

This may mean however that you want to keep these files up-to-date and check for them in your CI's checks as well.

gql-tada generate-output
gql-tada turbo
git diff --name-status --exit-code .

GitHub Actions Example

If you're using GitHub Actions, you can run the commands in a simple step in your workflow's jobs.

- name: "gql.tada Checks"
  run: |
    gql-tada generate output
    gql-tada generate turbo
    git diff --name-status --exit-code .

The git diff command added at the end will fail if any unstaged changes are present. Adding this can help fail your CI step, if any of gql.tada's files need to be updated.