GraphQL Schema TypeScript Generator

Common errors

• Error: Cannot find module 'graphql' or its corresponding type declarations.

  cause The `graphql` peer dependency is either not installed, or its version is incompatible with `graphql-schema-typescript`.
  fix Install the correct `graphql` version as specified in `graphql-schema-typescript`'s `package.json` or README. For example, `npm install graphql@^16.0.0`.

• Error: Schema must contain unique named types but contains multiple types named "YourType"

  cause Your GraphQL schema definition has duplicate type names, which is not allowed by the GraphQL specification.
  fix Review your `.gql` or `.graphqls` schema files (or the schema object passed programmatically) and ensure all type, input, enum, and interface names are unique across the entire schema. Check for accidental re-declarations or issues with schema merging if using multiple files.

• TypeError: Cannot read properties of undefined (reading 'kind') at buildASTSchema

  cause The input provided to `buildSchema` (when using the programmatic API) or the schema files provided to the CLI are not valid GraphQL SDL strings or do not represent a parseable schema.
  fix Ensure that the `schema` argument passed to `generateTypeScriptTypes` is a valid `GraphQLSchema` object, typically created with `buildSchema` from a correct SDL string. If using the CLI, verify that the `--schema` argument points to valid GraphQL schema files (`.gql`, `.graphqls`).

• TS2307: Cannot find module './generated-types' or its corresponding type declarations.

  cause The generated TypeScript file (`generated-types.ts` in this example) is not being correctly picked up by your TypeScript compiler or IDE. This can be due to an incorrect `outputPath`, missing `include` in `tsconfig.json`, or the file not existing.
  fix Verify that the `outputPath` in your `generateTypeScriptTypes` call (or CLI output path) is correct and accessible. Ensure your `tsconfig.json`'s `include` array covers the directory where the types are generated (e.g., `"include": ["./src", "./generated-types.ts"]`). Run the generation script to confirm the file is actually created.

Warnings

• breaking The `graphql` peer dependency has specific version requirements for each major/minor release of `graphql-schema-typescript`. For example, v1.6.x requires `^16.0.0` of `graphql`, while v1.5.x required `^14.0.0` or `^15.0.0`. Using an incompatible `graphql` version will lead to runtime errors or incorrect type generation.
  Fix: Always check the `Compatibility` table in the package's README or `package.json` to ensure your installed `graphql` version matches the `graphql-schema-typescript` peer dependency. Upgrade or downgrade `graphql` as needed (e.g., `npm install graphql@^16.0.0`).
• breaking In version 1.3.1, enum types under the global scope are now generated as TypeScript `enum` instead of `string union` types. This is a breaking change that might affect existing code relying on string union behavior.
  Fix: Update your code to expect generated enum types where appropriate. If string unions are preferred, consider custom type mapping options or adjusting your schema. For `d.ts` generation, `export const enum` is used.
• gotcha The default `TParent` and `TResult` types for generated resolvers can be implicitly `any` or inferred based on schema, but v1.2.2 introduced `smartTParent` and `smartTResult` options. If these are set to `true`, `TParent` might become `undefined` (if `rootValueType` is used) or `TResult` will be strongly inferred, which could alter resolver signatures.
  Fix: Explicitly set `smartTParent: false` and `smartTResult: false` in `GenerateTypescriptOptions` if you prefer the legacy `any` defaults or require manual type declaration for resolver parent/result types. Otherwise, adjust resolver implementations to match the inferred types.
• gotcha From v1.2.10 onwards, generated files include `/* eslint-disable */` comments. While this prevents linting errors in generated code, it might override project-specific linting configurations if you wish to apply custom rules to generated files or integrate them more tightly into your linting pipeline.
  Fix: If you need to apply linting rules to generated files, you can use a post-processing script to remove these comments or configure your linter to ignore specific patterns. Alternatively, rely on the `// eslint-disable` comments and focus linting efforts on handwritten code.

Install

• npm install graphql-schema-typescript npm
• yarn add graphql-schema-typescript yarn
• pnpm add graphql-schema-typescript pnpm

Imports

• generateTypeScriptTypes
  wrong:

  const { generateTypeScriptTypes } = require('graphql-schema-typescript');

  correct:

  import { generateTypeScriptTypes } from 'graphql-schema-typescript';

  Primary function for programmatic type generation. The library is primarily consumed as an ESM module in modern Node.js/TypeScript environments.
• GenerateTypescriptOptions

  import type { GenerateTypescriptOptions } from 'graphql-schema-typescript';

  This type defines the configuration options for the `generateTypeScriptTypes` function. Always import types using `import type` for clarity and bundler optimization.

Quickstart

This quickstart demonstrates how to programmatically generate TypeScript types from a GraphQL schema string, including common configuration options like `smartTParent` and `contextType`. It uses `buildSchema` from `graphql` to create a schema object and writes the output to a file.

import { generateTypeScriptTypes } from 'graphql-schema-typescript';
import { buildSchema } from 'graphql';
import * as fs from 'fs/promises';

async function generateTypes() {
  const schemaString = `
    type Query {
      hello(name: String!): String!
      users: [User!]!
    }

    type User {
      id: ID!
      name: String!
      email: String
    }

    schema {
      query: Query
    }
  `;
  const schema = buildSchema(schemaString);
  const outputPath = './generated-types.ts';

  try {
    await generateTypeScriptTypes(schema, outputPath, {
      debug: true, // Enable debug logging
      contextType: 'MyContextType',
      rootValueType: 'MyRootValueType',
      smartTParent: true, // Infer TParent type for resolvers
      smartTResult: true, // Infer TResult type for resolvers
      enumValueSuffix: 'Enum' // Suffix for generated enum types
    });
    console.log(`Successfully generated TypeScript types to ${outputPath}`);
    const generatedContent = await fs.readFile(outputPath, 'utf-8');
    console.log('Generated content preview:\n', generatedContent.substring(0, 500), '...');
  } catch (err) {
    console.error('Error generating types:', err);
    process.exit(1);
  }
}

generateTypes();