web/scripts/README-convert-graphql-to-ts.md

GraphQL to TypeScript Converter

This script converts GraphQL files (.graphql) to TypeScript files (.graphql.ts) that use the gql template literal from graphql-tag.

Features

• Converts individual fragments and queries into separate TypeScript exports
• Handles GraphQL imports (#import) and converts them to TypeScript imports
• Preserves fragment references and generates proper import statements
• Groups multiple imports from the same file
• Supports fragments, queries, mutations, and subscriptions
• Handles files with multiple operations

Usage

Basic Conversion

Convert all GraphQL files in the project:

yarn graphql:convert

Convert files matching a specific pattern:

yarn graphql:convert "packages/trpc/**/*.graphql"

Convert a single file:

yarn graphql:convert "path/to/file.graphql"

Options

• --dry-run: Preview what files would be converted without actually converting them
• --delete-originals: Delete original .graphql files after successful conversion
• --help, -h: Show help message

Examples

Preview conversion:

yarn graphql:convert --dry-run

Convert and delete originals:

yarn graphql:convert --delete-originals

Convert specific directory:

yarn graphql:convert "packages/trpc/lib/graphql/Fragments/**/*.graphql"

Input Format

GraphQL Fragment

fragment Contact on ContactBlock {
    sections {
        __typename
    }
}

GraphQL Query with Imports

#import "../Fragments/System.graphql"
#import "../Fragments/Metadata.graphql"

query GetData($locale: String!) {
    data(locale: $locale) {
        ...System
        ...Metadata
    }
}

Output Format

TypeScript Fragment

import { gql } from "graphql-tag";

export const Contact = gql`
    fragment Contact on ContactBlock {
        sections {
            __typename
        }
    }
`;

TypeScript Query with Imports

import { gql } from "graphql-tag";

import { System } from "../Fragments/System.graphql";
import { Metadata } from "../Fragments/Metadata.graphql";

export const GetData = gql`
    query GetData($locale: String!) {
        data(locale: $locale) {
            ...System
            ...Metadata
        }
    }
    ${System}
    ${Metadata}
`;

How It Works

1. Parse GraphQL Files: Reads .graphql files and extracts imports and operations
2. Handle Imports: Converts #import statements to TypeScript imports by:
   • Reading the imported file to determine export names
   • Converting paths from .graphql to .graphql.ts
   • Grouping multiple imports from the same file
3. Extract Operations: Identifies fragments, queries, mutations, and subscriptions
4. Generate TypeScript: Creates TypeScript files with:
   • gql template literals
   • Proper import statements
   • Named exports for each operation

Dependencies

• glob: For file pattern matching
• tsx: For TypeScript execution
• @types/node: For Node.js types
• graphql-tag: For the gql template literal (runtime dependency)

Notes

• The script preserves the original file structure and naming
• Fragment references (...FragmentName) are preserved in the GraphQL content
• Multiple operations in a single file are split into separate exports
• Import conflicts are avoided by using the exact export names from referenced files
• Generated files maintain the same directory structure with .graphql.ts extension