How to Use `gql.tada` in a React Next.js App

Introduction

GraphQL in Next.js can be tricky to organize efficiently. One of the biggest challenges developers face is handling TypeScript types for GraphQL queries. Manually writing types for every query can be tedious, error-prone, and hard to maintain—especially as your API evolves.

This is where gql.tada comes in! With gql.tada, we can structure our GraphQL queries, fragments, and types neatly in our project while automatically generating TypeScript types. This means:

✅ No more manually defining types for queries.
✅ Automatic type inference for query results.
✅ Cleaner, more maintainable code.

A well-organized GraphQL setup in a Next.js app should follow a structured directory like this:

libs/graphql/
  ├── generated/  (output and schema)
  ├── fragments.ts
  ├── queries.ts
  ├── types.ts

Let’s go through the process of setting up gql.tada in a Next.js project. 🚀

1. Install `gql.tada`

First, install gql.tada along with GraphQL:

npm install gql.tada graphql

or using Yarn:

yarn add gql.tada graphql

2. Download the Schema

To generate types and queries, we need the GraphQL schema from our API. Run the following command to download it:

dotenv -c -- bash -c 'gql.tada generate schema <<API_ENDPOINT>> --output ./src/libs/graphql/generated/schema.ts --header "X-Exclude-Invalid: true" --header "Authorization: $TOKEN"'

This will create a schema.graphql file that contains the API schema. More details can be found in the official documentation.

3. Setting up `gql.tada`

Automatically using `init`

You can use the init command to configure the plugin and define the paths for the schema and output:

npx gql-tada init ./my-project

Manually Configuring TypeScript Plugin

If you prefer manual setup, update your tsconfig.json:

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

4. Generate `gql.tada` Output

Run the following command to generate the TypeScript outputs based on your schema:

npx gql-tada generate output

This will generate the generated/ directory inside libs/graphql/, containing the necessary GraphQL outputs and types.

5. Configure VS Code Settings

To enable better editor support, add this to .vscode/settings.json:

{
  "typescript.preferences.importModuleSpecifier": "non-relative",
  "typescript.tsserver.experimental.enableProjectDiagnostics": true
}

This ensures that auto-imports work smoothly when using gql.tada in your code.

6. Create a `types.ts` File

Since gql.tada generates types dynamically, we can create a file to easily export them:

libs/graphql/types.ts:

import { ResultOf } from 'gql.tada';
import * as QUERY from './queries';

export type PostsResult = ResultOf<typeof QUERY.ALL_POSTS>;

This allows us to keep our type definitions modular and reusable across our Next.js app.

7. Add Basic Scripts to `package.json`

To streamline the GraphQL schema generation process, add the following scripts:

{
  "scripts": {
    "generate-schema": "dotenv -c -- bash -c 'gql.tada generate schema <<API_ENDPOINT>> --output ./src/libs/graphql/generated/schema.ts --header \"X-Exclude-Invalid: true\" --header \"Authorization: $TOKEN\"'",
    "generate-gql": "npx gql-tada generate output && npx gql-tada check",
    "prepare": "yarn generate-schema && yarn generate-gql"
  }
}

This setup ensures that running yarn prepare will generate the latest schema and GraphQL output automatically.

8. Verify Settings

To confirm that everything is correctly configured, run:

npx gql-tada check

This will validate your setup and highlight any issues.

Bonus: Customizing Scalar Types

If your GraphQL API uses custom scalar types, gql.tada allows you to define them. You can configure them manually as shown in the official documentation.

Wrapping Up

By following these steps, you now have a well-structured, TypeScript-powered GraphQL setup in your Next.js app using gql.tada. 🚀

✅ Installed gql.tada
✅ Downloaded the GraphQL schema
✅ Configured TypeScript for gql.tada
✅ Generated GraphQL output
✅ Configured VS Code for smooth DX
✅ Created a types.ts file for reusable GraphQL types
✅ Set up automation with package scripts

Now, you’re ready to start building GraphQL-powered React components with ease! Happy coding! 🎉

How to Use gql.tada in a React Next.js App