e9bd159e98
Use turbopack for dev builds. Remove graphql-tag/loader, replaced by gql`` tag literals instead. Approved-by: Linus Flood
151 lines
3.4 KiB
Markdown
151 lines
3.4 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
yarn graphql:convert
|
|
```
|
|
|
|
Convert files matching a specific pattern:
|
|
|
|
```bash
|
|
yarn graphql:convert "packages/trpc/**/*.graphql"
|
|
```
|
|
|
|
Convert a single file:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
yarn graphql:convert --dry-run
|
|
```
|
|
|
|
Convert and delete originals:
|
|
|
|
```bash
|
|
yarn graphql:convert --delete-originals
|
|
```
|
|
|
|
Convert specific directory:
|
|
|
|
```bash
|
|
yarn graphql:convert "packages/trpc/lib/graphql/Fragments/**/*.graphql"
|
|
```
|
|
|
|
## Input Format
|
|
|
|
### GraphQL Fragment
|
|
|
|
```graphql
|
|
fragment Contact on ContactBlock {
|
|
sections {
|
|
__typename
|
|
}
|
|
}
|
|
```
|
|
|
|
### GraphQL Query with Imports
|
|
|
|
```graphql
|
|
#import "../Fragments/System.graphql"
|
|
#import "../Fragments/Metadata.graphql"
|
|
|
|
query GetData($locale: String!) {
|
|
data(locale: $locale) {
|
|
...System
|
|
...Metadata
|
|
}
|
|
}
|
|
```
|
|
|
|
## Output Format
|
|
|
|
### TypeScript Fragment
|
|
|
|
```typescript
|
|
import { gql } from "graphql-tag";
|
|
|
|
export const Contact = gql`
|
|
fragment Contact on ContactBlock {
|
|
sections {
|
|
__typename
|
|
}
|
|
}
|
|
`;
|
|
```
|
|
|
|
### TypeScript Query with Imports
|
|
|
|
```typescript
|
|
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
|