GraphQL Code Generator Typed Module Declarations

Common errors

• TypeScript error: Module './my-fragment.graphql' has no exported member 'MyFragment'.

  cause You are attempting to import a GraphQL fragment using a named import, but this plugin generates fragments as default exports.
  fix Change your import statement for fragments to use a default import, e.g., `import MyFragment from './my-fragment.graphql';`

• TypeScript error: Property 'user' does not exist on type 'DocumentNode<any, Record<string, any>>'.

  cause The generated `DocumentNode` is not being correctly typed by `TypedDocumentNode`, or the types are not being picked up when importing the `.graphql` file.
  fix Verify that `@graphql-codegen/typed-document-node` is correctly configured and runs before this plugin. Ensure the `typedDocumentNodeModule` path in this plugin's configuration in `codegen.yml` is correctly pointing to the output file of `typed-document-node`.

Warnings

• gotcha GraphQL fragments defined in `.graphql` files are generated as *default* imports, not named imports, when consumed as modules. Attempting to use a named import for a fragment will lead to a TypeScript error or runtime failure.
  Fix: Always use a default import statement for GraphQL fragments: `import MyFragment from './my-fragment.graphql';`
• gotcha This plugin is dependent on the `@graphql-codegen/typed-document-node` plugin. It must be configured to run *before* this plugin in your `codegen.yml`, and the `typedDocumentNodeModule` option in this plugin's configuration must accurately point to the output file of the `typed-document-node` plugin. Incorrect setup will result in missing or incorrect type information.
  Fix: Ensure `@graphql-codegen/typed-document-node` is listed and generates types into a file (e.g., `src/graphql/generated.ts`). Then, configure this plugin with `typedDocumentNodeModule: './path/to/generated'` (relative to the output of this plugin).

Install

• npm install codegen-typescript-graphql-module-declarations-plugin npm
• yarn add codegen-typescript-graphql-module-declarations-plugin yarn
• pnpm add codegen-typescript-graphql-module-declarations-plugin pnpm

Imports

• codegen.yml configuration

  # codegen.yml
  plugins:
    - codegen-typescript-graphql-module-declarations-plugin

  The plugin is integrated into the GraphQL Code Generator workflow via its configuration file (e.g., `codegen.yml` or `codegen.ts`), not by a direct JavaScript/TypeScript import statement.
• MyQuery

  import { MyQuery } from './my-query.graphql';

  For GraphQL operations (queries, mutations, subscriptions) defined in `.graphql` files, the plugin generates named exports corresponding to the operation name, providing a typed `DocumentNode`.
• UserFields
  wrong:

  import { UserFields } from './my-fragment.graphql';

  correct:

  import UserFields from './my-fragment.graphql';

  Due to `graphql-tag/loader` behavior, GraphQL fragments are exported as default imports when consumed as modules. Attempting to use a named import for a fragment will result in a runtime error or a TypeScript type error.

Quickstart

This quickstart demonstrates how to configure `graphql-code-generator` with this plugin to generate typed module declarations for `.graphql` files, and how to consume these typed imports in a TypeScript application. It shows handling both named operations (queries) and default-imported fragments.

/* package.json */
{
  "name": "my-graphql-app",
  "version": "1.0.0",
  "devDependencies": {
    "@graphql-codegen/cli": "^5.0.0",
    "@graphql-codegen/typescript": "^4.0.0",
    "@graphql-codegen/typescript-operations": "^4.0.0",
    "@graphql-codegen/typed-document-node": "^5.0.0",
    "codegen-typescript-graphql-module-declarations-plugin": "^1.0.0",
    "graphql": "^16.0.0"
  }
}

/* src/my-query.graphql */
query MyQuery {
  user {
    id
    name
  }
}

/* src/my-fragment.graphql */
fragment UserFields on User {
  id
  name
}

/* codegen.yml */
overwrite: true
schema: "http://localhost:4000/graphql" # Replace with your GraphQL API endpoint
documents: "src/**/*.graphql"
generates:
  src/graphql/generated.ts:
    plugins:
      - typescript
      - typescript-operations
      - typed-document-node
  src/graphql/modules.d.ts:
    plugins:
      - codegen-typescript-graphql-module-declarations-plugin
    config:
      typedDocumentNodeModule: ./generated # Relative path from modules.d.ts to generated.ts

/* src/app.ts */
// Run `npx graphql-codegen` first to generate types
// Then `tsc src/app.ts` to type-check

import { MyQuery } from './my-query.graphql';
import UserFields from './my-fragment.graphql'; // Fragments are default imports

interface User { id: string; name: string; }

// MyQuery is a TypedDocumentNode with inferred types
// You would typically pass this to a GraphQL client (e.g., Apollo Client's useQuery)
console.log('MyQuery operation name:', MyQuery.definitions[0].name?.value); // Should log 'MyQuery'

// Example of accessing the inferred types (runtime code would use actual client data)
type MyQueryResult = typeof MyQuery['__generated_graphql_codegen_typescript_document_node']['result'];
const simulatedQueryResult: MyQueryResult = {
    user: { id: 'user123', name: 'Alice' }
};
console.log('Simulated query result:', simulatedQueryResult.user?.name);

// UserFields is a DocumentNode, its types are also inferred for consistency
console.log('UserFields fragment name:', UserFields.definitions[0].name?.value); // Should log 'UserFields'

// A fragment doesn't have a direct 'result' type like a query, but its fields are known
// type UserFieldsType = typeof UserFields['__generated_graphql_codegen_typescript_document_node']; // This approach is for operations
// Instead, use the type generated by typescript-operations for the fragment
interface UserFieldsType { id: string; name: string; }
const simulatedFragmentData: UserFieldsType = { id: 'frag456', name: 'Bob' };
console.log('Simulated fragment data:', simulatedFragmentData.name);