Using GraphQL Code Generator with ChatBotKit's GraphQL API

Setting up GraphQL Code Generator with ChatBotKit's GraphQL API is straightforward and will dramatically improve your development experience by providing type-safe client code generation. This comprehensive tutorial will walk you through the entire process, including the crucial authentication setup required for ChatBotKit's protected endpoint.

Prerequisites

Before getting started, ensure you have:

• Node.js installed
• A ChatBotKit account with an API key
• Basic familiarity with TypeScript and GraphQL

Installation

First, install the necessary dependencies. We'll use the TypeScript plugins approach with graphql-request for type-safe API interactions.

The packages serve different purposes:

• graphql: The core GraphQL library
• graphql-request: Minimal GraphQL client
• @graphql-codegen/cli: The command-line interface for code generation
• @graphql-codegen/typescript: Generates TypeScript types from GraphQL schema
• @graphql-codegen/typescript-operations: Generates types for GraphQL operations
• @graphql-codegen/typescript-graphql-request: Generates SDK for graphql-request
• dotenv: Loads environment variables for authentication

Configuration Setup

GraphQL Code Generator uses a TypeScript configuration file, providing better type safety and IDE support.

Create Configuration File

Create a codegen.ts file in your project root:

Important: ChatBotKit's GraphQL endpoint requires authentication headers to access the schema definitions. This is intentionally designed this way because some customers may have custom GraphQL extensions that require proper authorization to access. Note that we load environment variables using dotenv.config() at the top of the file.

Environment Variables Setup

Create a .env file in your project root to store your API credentials securely:

This approach keeps sensitive credentials out of your source code while allowing the code generator to access them during the introspection process.

Package.json Scripts

Add the necessary scripts to your package.json:

Since we load environment variables directly in codegen.ts using dotenv.config(), we don't need the -r dotenv/config flag.

Writing GraphQL Operations

Before running the code generator, you need to define some GraphQL operations. With the TypeScript plugins approach, we create separate .graphql files for each operation.

Example query in src/queries/listBots.graphql:

This approach keeps your GraphQL operations separate from your TypeScript code, making them easier to manage and review.

Running Code Generation

Execute the code generation process:

The generator will:

1. Connect to ChatBotKit's GraphQL endpoint using your Bearer token
2. Introspect the schema to understand all available types and operations
3. Analyze your GraphQL operations in the specified document files
4. Generate type-safe TypeScript definitions in the ./src/gql/ directory

Generated Output

The TypeScript plugins generate a single comprehensive file:

• ./src/generated/graphql.ts: Contains all GraphQL types, operation result types, and a complete SDK with type-safe methods

This file includes:

• All GraphQL schema types (prefixed with CBK)
• Type definitions for your operations
• A getSdk() function that creates a type-safe SDK wrapper around your graphql-request client

Using Generated Types

After generation, you can use the type-safe SDK in your application. Here's an example using Next.js server components:

The generated SDK provides methods for all your GraphQL operations with complete type safety for variables and responses.

Troubleshooting Common Issues

Authentication Failures

If you encounter authentication errors during schema introspection:

• Verify your API key is correct and has the necessary permissions
• Ensure the environment variable is properly loaded
• Check that the Authorization header format matches ChatBotKit's requirements

Missing Types

If generated types seem incomplete:

• Ensure all your GraphQL operations are in files matching the documents pattern
• Verify that your operations are using the graphql function from the generated code
• Check that the schema introspection was successful

Build Errors

If you encounter TypeScript errors after generation:

• Run npm run codegen to ensure you have the latest generated types
• Check that your GraphQL operations match the schema exactly
• Verify that all required fields are included in your queries

Best Practices

1. Version Control: Include generated files in version control to ensure consistency across team members and deployments.
2. Environment Management: Use environment variables for API keys and endpoint URLs to support different environments (development, staging, production).
3. Operation Organization: Group related GraphQL operations in logical files and folders for better maintainability.
4. Type Safety: Take advantage of the generated types throughout your application to catch errors at compile time rather than runtime.
5. Regular Updates: Run code generation regularly, especially after schema changes, to keep your types in sync with the API.

Conclusion

GraphQL Code Generator with ChatBotKit's API provides a robust foundation for building type-safe applications that can efficiently query and manipulate your chatbot resources. The authentication setup ensures secure access to the schema while enabling powerful development-time features like autocompletion and compile-time type checking.