GraphQL Tooling

Link to this section#A Complete Guide to GraphQL Tooling with Quiltt

Type safety is crucial for building reliable applications, especially when working with GraphQL APIs. This guide will help you set up GraphQL Code Generator with Quiltt to automatically generate TypeScript types for your GraphQL operations, ensuring type safety across your entire application.

Link to this section#Understanding GraphQL Code Generator

GraphQL Code Generator is a powerful tool that:

• Generates TypeScript types from your GraphQL schema
• Creates typed queries, mutations, and subscriptions
• Provides full IDE support with autocompletion
• Catches type errors at compile time
• Ensures consistency between client and server

Link to this section#Prerequisites

Before we begin, you'll need:

• A Quiltt account with API access
• A Next.js project with TypeScript
• Basic understanding of GraphQL
• Node.js and pnpm installed

Link to this section#Initial Setup

Link to this section#1. Create a New Project

If you haven't already, create a new Next.js project:

Link to this section#2. Install Required Dependencies

Install the necessary packages for GraphQL Code Generator:

These packages provide:

• @graphql-codegen/cli: The core code generation tool
• @graphql-codegen/client-preset: Preset for client-side GraphQL operations
• @graphql-codegen/typescript: TypeScript types generation
• @graphql-codegen/typescript-operations: Types for operations (queries/mutations)
• graphql: The GraphQL runtime (required peer dependency)
• @quiltt/react: Quiltt's React SDK

Link to this section#Configuration

Link to this section#1. Set Up Environment Variables

Create or update your .env.local file:

Link to this section#2. Configure GraphQL Code Generator

Create a codegen.ts configuration file in your project root:

This configuration:

1. Uses your Quiltt API key for schema fetching
2. Watches TypeScript/React files for GraphQL operations
3. Generates types in src/types/generated/
4. Applies Prettier formatting to generated files
5. Configures various generation options for optimal output

Link to this section#3. Add NPM Scripts

Update your package.json to include GraphQL Code Generator scripts:

Link to this section#Using Generated Types

Link to this section#1. Basic Query Example

Let's create a component that uses the generated types:

Link to this section#2. Mutation Example

Here's how to use generated types with mutations:

Link to this section#3. Subscription Example

Here's how to implement type-safe subscriptions:

Link to this section#Best Practices

Link to this section#1. Fragment Usage

Use fragments to share common fields between queries:

Link to this section#2. Type Safety for Custom Hooks

Create type-safe custom hooks:

Link to this section#3. Error Handling Types

Create type-safe error handling utilities:

Link to this section#Troubleshooting

Link to this section#1. Schema Loading Issues

If you're having trouble loading the schema:

Link to this section#2. Generation Issues

If you're experiencing generation problems:

1. Clear the generated files:

2. Verify your GraphQL operations:

Link to this section#3. Type Resolution Issues

If you're having problems with type resolution:

Link to this section#Advanced Topics

Link to this section#1. Custom Scalars

Configure custom scalar types:

Link to this section#2. Operation Presets

Create operation presets for common queries:

Link to this section#3. Development Workflow

Set up a development workflow that automatically generates types:

Link to this section#Conclusion

By following this guide, you've set up a robust GraphQL development environment with:

• Automatic type generation
• Type-safe operations
• IDE support
• Error catching at compile time

Remember to:

• Keep your schema up to date
• Use fragments for reusable fields
• Handle errors consistently
• Maintain type safety across your application