{"id":10648,"library":"codegen-typescript-graphql-module-declarations-plugin","title":"GraphQL Code Generator Typed Module Declarations","description":"This `graphql-code-generator` plugin enhances the standard `@graphql-codegen/typescript-graphql-files-modules` plugin by generating TypeScript module declarations for `.graphql` files, but critically, it produces *typed* `DocumentNode` objects. This typing leverages the output of the `@graphql-codegen/typed-document-node` plugin, ensuring type-safety and auto-completion when importing GraphQL operations (queries, mutations, subscriptions) directly from `.graphql` files into your TypeScript codebase. It currently stands at version `1.0.3` and shows a stable release cadence with dependency updates and minor bug fixes. Key differentiators include its focus on generating fully typed `DocumentNode` definitions for imported GraphQL files, allowing for robust type-checking at compile time, which is not directly provided by `graphql-tag/loader` alone without this intermediary type generation. It also supports `.graphql` files with multiple operations, naming imports according to the operation names, enhancing code organization and readability.","status":"active","version":"1.0.3","language":"javascript","source_language":"en","source_url":"https://github.com/niieani/codegen-typescript-graphql-module-declarations-plugin","tags":["javascript","codegen","graphql","typescript"],"install":[{"cmd":"npm install codegen-typescript-graphql-module-declarations-plugin","lang":"bash","label":"npm"},{"cmd":"yarn add codegen-typescript-graphql-module-declarations-plugin","lang":"bash","label":"yarn"},{"cmd":"pnpm add codegen-typescript-graphql-module-declarations-plugin","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required to execute GraphQL Code Generator plugins.","package":"@graphql-codegen/cli","optional":false},{"reason":"Often used as a base plugin for generating core TypeScript types from the schema.","package":"@graphql-codegen/typescript","optional":false},{"reason":"Generates types for GraphQL operations (queries, mutations, subscriptions, fragments).","package":"@graphql-codegen/typescript-operations","optional":false},{"reason":"This plugin builds upon the output of TypedDocumentNode to provide typed DocumentNodes. It is a mandatory prerequisite for this plugin to function correctly.","package":"@graphql-codegen/typed-document-node","optional":false},{"reason":"Core GraphQL library, a peer dependency for most GraphQL tooling.","package":"graphql","optional":false},{"reason":"Mentioned as a common way to consume the generated types in a webpack setup.","package":"graphql-tag/loader","optional":true}],"imports":[{"note":"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.","symbol":"codegen.yml configuration","correct":"# codegen.yml\nplugins:\n  - codegen-typescript-graphql-module-declarations-plugin"},{"note":"For GraphQL operations (queries, mutations, subscriptions) defined in `.graphql` files, the plugin generates named exports corresponding to the operation name, providing a typed `DocumentNode`.","symbol":"MyQuery","correct":"import { MyQuery } from './my-query.graphql';"},{"note":"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.","wrong":"import { UserFields } from './my-fragment.graphql';","symbol":"UserFields","correct":"import UserFields from './my-fragment.graphql';"}],"quickstart":{"code":"/* package.json */\n{\n  \"name\": \"my-graphql-app\",\n  \"version\": \"1.0.0\",\n  \"devDependencies\": {\n    \"@graphql-codegen/cli\": \"^5.0.0\",\n    \"@graphql-codegen/typescript\": \"^4.0.0\",\n    \"@graphql-codegen/typescript-operations\": \"^4.0.0\",\n    \"@graphql-codegen/typed-document-node\": \"^5.0.0\",\n    \"codegen-typescript-graphql-module-declarations-plugin\": \"^1.0.0\",\n    \"graphql\": \"^16.0.0\"\n  }\n}\n\n/* src/my-query.graphql */\nquery MyQuery {\n  user {\n    id\n    name\n  }\n}\n\n/* src/my-fragment.graphql */\nfragment UserFields on User {\n  id\n  name\n}\n\n/* codegen.yml */\noverwrite: true\nschema: \"http://localhost:4000/graphql\" # Replace with your GraphQL API endpoint\ndocuments: \"src/**/*.graphql\"\ngenerates:\n  src/graphql/generated.ts:\n    plugins:\n      - typescript\n      - typescript-operations\n      - typed-document-node\n  src/graphql/modules.d.ts:\n    plugins:\n      - codegen-typescript-graphql-module-declarations-plugin\n    config:\n      typedDocumentNodeModule: ./generated # Relative path from modules.d.ts to generated.ts\n\n/* src/app.ts */\n// Run `npx graphql-codegen` first to generate types\n// Then `tsc src/app.ts` to type-check\n\nimport { MyQuery } from './my-query.graphql';\nimport UserFields from './my-fragment.graphql'; // Fragments are default imports\n\ninterface User { id: string; name: string; }\n\n// MyQuery is a TypedDocumentNode with inferred types\n// You would typically pass this to a GraphQL client (e.g., Apollo Client's useQuery)\nconsole.log('MyQuery operation name:', MyQuery.definitions[0].name?.value); // Should log 'MyQuery'\n\n// Example of accessing the inferred types (runtime code would use actual client data)\ntype MyQueryResult = typeof MyQuery['__generated_graphql_codegen_typescript_document_node']['result'];\nconst simulatedQueryResult: MyQueryResult = {\n    user: { id: 'user123', name: 'Alice' }\n};\nconsole.log('Simulated query result:', simulatedQueryResult.user?.name);\n\n// UserFields is a DocumentNode, its types are also inferred for consistency\nconsole.log('UserFields fragment name:', UserFields.definitions[0].name?.value); // Should log 'UserFields'\n\n// A fragment doesn't have a direct 'result' type like a query, but its fields are known\n// type UserFieldsType = typeof UserFields['__generated_graphql_codegen_typescript_document_node']; // This approach is for operations\n// Instead, use the type generated by typescript-operations for the fragment\ninterface UserFieldsType { id: string; name: string; }\nconst simulatedFragmentData: UserFieldsType = { id: 'frag456', name: 'Bob' };\nconsole.log('Simulated fragment data:', simulatedFragmentData.name);","lang":"typescript","description":"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."},"warnings":[{"fix":"Always use a default import statement for GraphQL fragments: `import MyFragment from './my-fragment.graphql';`","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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).","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Change your import statement for fragments to use a default import, e.g., `import MyFragment from './my-fragment.graphql';`","cause":"You are attempting to import a GraphQL fragment using a named import, but this plugin generates fragments as default exports.","error":"TypeScript error: Module './my-fragment.graphql' has no exported member 'MyFragment'."},{"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`.","cause":"The generated `DocumentNode` is not being correctly typed by `TypedDocumentNode`, or the types are not being picked up when importing the `.graphql` file.","error":"TypeScript error: Property 'user' does not exist on type 'DocumentNode<any, Record<string, any>>'."}],"ecosystem":"npm"}