Registry /
llm-agents / codegen-typescript-graphql-module-declarations-plugin
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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
✓ import UserFields from './my-fragment.graphql';
✗ 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.
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);
Errors
Common errors & fixes
TypeScript error: Module './my-fragment.graphql' has no exported member 'MyFragment'.
You are attempting to import a GraphQL fragment using a named import, but this plugin generates fragments as default exports.
fixChange 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>>'.
The generated `DocumentNode` is not being correctly typed by `TypedDocumentNode`, or the types are not being picked up when importing the `.graphql` file.
fixVerify 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`.
Audit
Dependencies
@graphql-codegen/clirequiredRequired to execute GraphQL Code Generator plugins.
@graphql-codegen/typescriptrequiredOften used as a base plugin for generating core TypeScript types from the schema.
@graphql-codegen/typescript-operationsrequiredGenerates types for GraphQL operations (queries, mutations, subscriptions, fragments).
@graphql-codegen/typed-document-noderequiredThis plugin builds upon the output of TypedDocumentNode to provide typed DocumentNodes. It is a mandatory prerequisite for this plugin to function correctly.
graphqlrequiredCore GraphQL library, a peer dependency for most GraphQL tooling.
graphql-tag/loaderoptionalMentioned as a common way to consume the generated types in a webpack setup.