{"id":13727312,"url":"https://github.com/codemodsquad/graphql-typegen","last_synced_at":"2025-06-20T09:04:45.157Z","repository":{"id":40617679,"uuid":"237726003","full_name":"codemodsquad/graphql-typegen","owner":"codemodsquad","description":"JSCodeshift transform that inserts Flow types generated from GraphQL documents in template string literals and your GraphQL schema","archived":false,"fork":false,"pushed_at":"2025-06-12T21:03:55.000Z","size":792,"stargazers_count":6,"open_issues_count":10,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-06-12T22:21:34.775Z","etag":null,"topics":["apollo","codemods","flow","flowtype","graphql","jscodeshift"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/codemodsquad.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-02-02T05:55:31.000Z","updated_at":"2025-06-12T21:04:00.000Z","dependencies_parsed_at":"2024-01-07T21:07:08.649Z","dependency_job_id":"98b9b4a2-9eaf-4ff5-915c-de8af994e72e","html_url":"https://github.com/codemodsquad/graphql-typegen","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/codemodsquad/graphql-typegen","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codemodsquad%2Fgraphql-typegen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codemodsquad%2Fgraphql-typegen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codemodsquad%2Fgraphql-typegen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codemodsquad%2Fgraphql-typegen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codemodsquad","download_url":"https://codeload.github.com/codemodsquad/graphql-typegen/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codemodsquad%2Fgraphql-typegen/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260915850,"owners_count":23082036,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["apollo","codemods","flow","flowtype","graphql","jscodeshift"],"created_at":"2024-08-03T01:03:49.307Z","updated_at":"2025-06-20T09:04:40.135Z","avatar_url":"https://github.com/codemodsquad.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# graphql-typegen\n\n[![CircleCI](https://circleci.com/gh/codemodsquad/graphql-typegen.svg?style=svg)](https://circleci.com/gh/codemodsquad/graphql-typegen)\n[![Coverage Status](https://codecov.io/gh/codemodsquad/graphql-typegen/branch/master/graph/badge.svg)](https://codecov.io/gh/codemodsquad/graphql-typegen)\n[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)\n[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)\n[![npm version](https://badge.fury.io/js/graphql-typegen.svg)](https://badge.fury.io/js/graphql-typegen)\n\nJSCodeshift transform that inserts Flow types generated from GraphQL documents in template string literals and your GraphQL schema, and wires up the generated types to Apollo\n\n# Table of Contents\n\n\u003c!-- toc --\u003e\n\n- [Example](#example)\n  - [Before](#before)\n  - [After](#after)\n- [Rationale](#rationale)\n  - [Importing generated types from external files is annoying](#importing-generated-types-from-external-files-is-annoying)\n  - [`graphql-codegen` outputs messy types for documents](#graphql-codegen-outputs-messy-types-for-documents)\n  - [I want to extract parts of the query with their own type aliases](#i-want-to-extract-parts-of-the-query-with-their-own-type-aliases)\n  - [Interpolation in GraphQL tagged template literals](#interpolation-in-graphql-tagged-template-literals)\n  - [Automatically adding type annotations to `Query`, `Mutation`, `useQuery`, `useMutation`, and `useSubscription`](#automatically-adding-type-annotations-to-query-mutation-usequery-usemutation-and-usesubscription)\n- [Configuration](#configuration)\n  - [`schemaFile` / `server`](#schemafile--server)\n  - [`tagName` (default: `gql`)](#tagname-default-gql)\n  - [`addTypename` (default: `true`)](#addtypename-default-true)\n  - [`objectType` (default: `ambiguous`)](#objecttype-default-ambiguous)\n  - [`useReadOnlyTypes` (default: `false`)](#usereadonlytypes-default-false)\n  - [`useFunctionTypeArguments` (default: `true`)](#usefunctiontypearguments-default-true)\n  - [`external as`](#external-as-)\n  - [`extract [as ]`](#extract-as-)\n- [CLI Usage](#cli-usage)\n- [Node.js API](#nodejs-api)\n\n\u003c!-- tocstop --\u003e\n\n# Example\n\n## Before\n\n```js\nimport gql from 'graphql-tag'\n\nconst fragment = gql`\n  fragment CharacterFields on Character {\n    name\n    appearsIn\n  }\n`\n\nconst fragment2 = gql`\n  ${fragment}\n  fragment CharacterAndFriends on Character {\n    ...CharacterFields\n    friends {\n      ...CharacterFields\n    }\n  }\n`\n\nconst query = gql`\n  ${fragment2}\n  query Test($id: ID!) {\n    character(id: $id) {\n      id\n      ...CharacterAndFriends\n    }\n  }\n`\n```\n\n## After\n\n```js\nimport gql from 'graphql-tag'\n\nconst fragment = gql`\n  fragment CharacterFields on Character {\n    name\n    appearsIn\n    ... on Human {\n      mass\n    }\n    ... on Droid {\n      primaryFunction\n    }\n  }\n`\n\n// @graphql-typegen auto-generated\ntype CharacterFields =\n  | {\n      name: string,\n      appearsIn: Array\u003c?('NEWHOPE' | 'EMPIRE' | 'JEDI')\u003e,\n      __typename: 'Human',\n      mass: ?number,\n    }\n  | {\n      name: string,\n      appearsIn: Array\u003c?('NEWHOPE' | 'EMPIRE' | 'JEDI')\u003e,\n      __typename: 'Droid',\n      primaryFunction: ?string,\n    }\n\nconst fragment2 = gql`\n  ${fragment}\n  fragment CharacterAndFriends on Character {\n    ...CharacterFields\n    friends {\n      ...CharacterFields\n    }\n  }\n`\n\n// @graphql-typegen auto-generated\ntype CharacterAndFriends = {\n  __typename: 'Human' | 'Droid',\n  friends: ?Array\u003c?CharacterFields\u003e,\n} \u0026 CharacterFields\n\nconst query = gql`\n  ${fragment2}\n  query Test($id: ID!) {\n    character(id: $id) {\n      id\n      ...CharacterAndFriends\n    }\n  }\n`\n\n// @graphql-typegen auto-generated\ntype TestQueryVariables = { id: string }\n\n// @graphql-typegen auto-generated\ntype TestQueryData = {\n  __typename: 'Query',\n  character: ?({\n    __typename: 'Human' | 'Droid',\n    id: string,\n  } \u0026 CharacterAndFriends),\n}\n```\n\n# Rationale\n\nWith established GraphQL code generators out there (`apollo-tooling` and `graphql-codegen`)\nyou might wonder why I decided to make my own instead. There are several reasons...\n\n## Importing generated types from external files is annoying\n\nBoth `graphql-codegen` and `apollo-tooling` output types in separate files from your\nGraphQL documents. This means you have to pick a globally unique identifier for\neach GraphQL operation. Dealing with global namespaces is always a pain in the ass.\nIt also means you have to insert an import statement. While I also have [my own tool\nthat's pretty damn good at automatic imports](https://github.com/jedwards1211/dude-wheres-my-module),\nit would still be an annoying extra step.\n\n`graphql-typegen` just inserts the generated types after the GraphQL\ntagged template literals in my code, so I don't have to worry about picking\nglobally unique operation names or adding imports.\n\n## `graphql-codegen` outputs messy types for documents\n\nExample:\n\n```graphql\nquery Test($id: ID!) {\n  user(id: $id) {\n    id\n    username\n  }\n}\n```\n\nOutput:\n\n```js\ntype $Pick\u003cOrigin: Object, Keys: Object\u003e = $ObjMapi\u003c\n  Keys,\n  \u003cKey\u003e(k: Key) =\u003e $ElementType\u003cOrigin, Key\u003e\n\u003e\n\nexport type TestQueryVariables = {\n  id: $ElementType\u003cScalars, 'ID'\u003e,\n}\n\nexport type TestQuery = {\n  ...{ __typename?: 'Query' },\n  ...{|\n    user: ?{\n      ...{ __typename?: 'User' },\n      ...$Pick\u003cUser, {| id: *, username: * |}\u003e,\n    },\n  |},\n}\n```\n\nPretty awful, huh? It's questionable if this even works properly in Flow; I've seen bugs with spreads inside inexact/ambiguous object types in the past.\n\n`graphql-typegen` would output:\n\n```js\n// @graphql-typegen auto-generated\ntype TestQueryData = {\n  __typename: 'Query',\n  user: {\n    __typename: 'User',\n    id: ID,\n    username: string,\n  },\n}\n```\n\n## I want to extract parts of the query with their own type aliases\n\nTake the query example above. Let's say I need to refer to the `user` type in `TestQuery`\nabove. All I have to do is add this comment:\n\n```graphql\nquery Test($id: ID!) {\n  # @graphql-typegen extract\n  user(id: $id) {\n    id\n    username\n  }\n}\n```\n\nAnd `graphql-typegen` will output:\n\n```js\n// @graphql-typegen auto-generated\ntype User = {\n  __typename: 'User',\n  id: ID,\n  username: string,\n}\n\n// @graphql-typegen auto-generated\ntype TestQueryData = {\n  __typename: 'Query',\n  user: User,\n}\n```\n\nThis is much easier than `type User = $PropertyType\u003cTestQuery, 'user'\u003e`,\nespecially for extracting types that are more than one level deep in the query\n(`$PropertyType\u003c$PropertyType\u003cTestQuery, 'foo'\u003e, 'bar'\u003e` would be pretty awful)\n\n## Interpolation in GraphQL tagged template literals\n\nAt the moment, [`apollo-tooling` doesn't support interpolation in tagged template literals](https://github.com/apollographql/apollo-tooling/issues/182).\nThis is a pretty crucial for sharing fragments between queries and mutations, which is, you know, common.\n\n`graphql-typegen` supports this:\n\n```js\nconst UserFragment = gql`\n  fragment UserFields on User {\n    id\n    username\n  }\n`\n\nconst userQuery = gql`\n  ${UserFragment}\n  query user($id: ID!) {\n    user(id: $id) {\n      ...UserFields\n    }\n  }\n`\n\nconst updateUserMutation = gql`\n  ${UserFragment}\n  mutation updateUser($id: ID!, $values: UpdateUser!) {\n    updateUser(id: $id, values: $values) {\n      ...UserFields\n    }\n  }\n`\n```\n\nOutput:\n\n```js\n// @graphql-typegen auto-generated\ntype UserFields = {\n  id: ID,\n  username: string,\n}\n\n// @graphql-typegen auto-generated\ntype UserQueryData = {\n  __typename: 'Query',\n  user: { __typename: 'User' } \u0026 UserFields,\n}\n\n// @graphql-typegen auto-generated\ntype UserQueryVariables = {\n  id: ID,\n}\n\n// @graphql-typegen auto-generated\ntype UpdateUserMutationData = {\n  __typename: 'Mutation',\n  updateUser: { __typename: 'User' } \u0026 UserFields,\n}\n\n// @graphql-typegen auto-generated\ntype UpdateUserMutationVariables = {\n  id: ID,\n  values: {\n    username?: string,\n  },\n}\n```\n\n`graphql-typegen` also supports string interpolation:\n\n```js\nconst userFields = `\n  id\n  username\n`\n\nconst userQuery = gql`\n  query user($id: ID!) {\n    user(id: $id) {\n      ${userFields}\n    }\n  }\n`\n\nconst updateUserMutation = gql`\n  mutation updateUser($id: ID!, $values: UpdateUser!) {\n    updateUser(id: $id, values: $values) {\n      ${userFields}\n    }\n  }\n`\n```\n\nOutput:\n\n```js\n// @graphql-typegen auto-generated\ntype UserQueryData = {\n  __typename: 'Query',\n  user: {\n    __typename: 'User',\n    id: ID,\n    username: string,\n  },\n}\n\n// @graphql-typegen auto-generated\ntype UserQueryVariables = {\n  id: ID,\n}\n\n// @graphql-typegen auto-generated\ntype UpdateUserMutationData = {\n  __typename: 'Mutation',\n  updateUser: {\n    __typename: 'User',\n    id: ID,\n    username: string,\n  },\n}\n\n// @graphql-typegen auto-generated\ntype UpdateUserMutationVariables = {\n  id: ID,\n  values: {\n    username?: string,\n  },\n}\n```\n\n## Automatically adding type annotations to `Query`, `Mutation`, `useQuery`, `useMutation`, and `useSubscription`\n\n`graphql-typegen` will analyze all calls to these hooks and add the correct type annotations:\n\n### Before\n\n```js\nconst userQuery = gql`\n  query user($id: ID!) {\n    user(id: $id) {\n      id\n      username\n    }\n  }\n`\n\nconst Foo = ({ id }: { id: ID }): React.Node =\u003e {\n  const { data } = useQuery(userQuery, { variables: { id } })\n  return \u003cpre\u003e{JSON.stringify(data)}\u003c/pre\u003e\n}\n```\n\n### After\n\n`graphql-typegen` inserts the type parameters `useQuery\u003cUserQueryData, UserQueryVariables\u003e`.\n\n```js\nconst userQuery = gql`\n  query user($id: ID!) {\n    user(id: $id) {\n      id\n      username\n    }\n  }\n`\n\n// @graphql-typegen auto-generated\ntype UserQueryData = {\n  __typename: 'Query',\n  user: {\n    __typename: 'User',\n    id: ID,\n    username: string,\n  },\n}\n\n// @graphql-typegen auto-generated\ntype UserQueryVariables = {\n  id: ID,\n}\n\nconst Foo = ({id}: {id: ID}): React.Node =\u003e {\n  const {data} = useQuery\u003cUserQueryData, UserQueryVariables\u003e(userQuery, {variables: {id}})\n  return \u003cpre\u003e{JSON.stringify(data)}\u003c/pre\u003e\n}\n```\n\n# Configuration\n\n## `schemaFile` / `server`\n\nFirst, you need to add the following to your `package.json` to tell `graphql-typegen` how to\nfind your schema:\n\n```\n  \"graphql-typegen\": {\n    \"schemaFile\": \"path/to/schema.graphql\"\n  }\n```\n\nOr\n\n```\n  \"graphql-typegen\": {\n    \"server\": \"http://localhost:4000/graphql\"\n  }\n```\n\n## `tagName` (default: `gql`)\n\nName of the template literal tag used to identify template literals containing GraphQL queries in Javascript/Typescript code\n\nConfigure this in your `package.json`:\n\n```\n  \"graphql-typegen\": {\n    \"tagName\": \"gql\"\n  }\n```\n\n## `validate` (default: `true`)\n\nWhether to validate each GraphQL document before processing it.\nExcludes `NoUnusedFragmentsRule` from validation, in case you put fragment definitions\nin separate template literals.\n\nRight now this is only configurable in your `package.json`:\n\n```\n  \"graphql-typegen\": {\n    \"validate\": false\n  }\n```\n\n## `addTypename` (default: `true`)\n\nPlaces this may be configured, in order of increasing precendence:\n\n### `package.json`\n\n```\n  \"graphql-typegen\": {\n    \"addTypename\": false\n  }\n```\n\n### in the description for a type or field in your GraphQL schema\n\n```graphql\n\"\"\"\n@graphql-typegen noTypename\n\"\"\"\ntype User {\n  id: ID!\n  name: String!\n}\n```\n\n### in a comment in your GraphQL document\n\n```js\nconst query = gql`\n  query user($id: Int!) {\n    # @graphql-typegen addTypename\n    user(id: $id) {\n      id\n      name\n    }\n  }\n`\n```\n\n## `objectType` (default: `ambiguous`)\n\nThe type of Flow object to output, one of:\n\n- `exact`\n- `inexact`\n- `ambiguous`\n\nPlaces this may be configured, in order of increasing precendence:\n\n### `package.json`\n\n```\n  \"graphql-typegen\": {\n    \"objectType\": \"exact\"\n  }\n```\n\n### in the description for a type or field in your GraphQL schema\n\n```graphql\n\"\"\"\n@graphql-typegen exact\n\"\"\"\ntype User {\n  id: ID!\n  name: String!\n}\n```\n\n### in a comment in your GraphQL document\n\n```js\nconst query = gql`\n  query user($id: Int!) {\n    # @graphql-typegen exact\n    user(id: $id) {\n      id\n      name\n    }\n  }\n`\n```\n\n## `useReadOnlyTypes` (default: `false`)\n\nWhether to use readonly object and array types.\n\nPlaces this may be configured, in order of increasing precendence:\n\n### `package.json`\n\n```\n  \"graphql-typegen\": {\n    \"useReadOnlyTypes\": true\n  }\n```\n\n### in the description for a type or field in your GraphQL schema\n\n```graphql\n\"\"\"\n@graphql-typegen readOnly\n\"\"\"\ntype User {\n  id: ID!\n  name: String!\n}\n```\n\n### in a comment in your GraphQL document\n\n```js\nconst query = gql`\n  query user($id: Int!) {\n    # @graphql-typegen mutable\n    user(id: $id) {\n      id\n      name\n    }\n  }\n`\n```\n\n## `useFunctionTypeArguments` (default: `true`)\n\nWhether to annotate `useQuery`, `useMutation` and `useSubscription` calls with type arguments,\nor annotate the input variables and output data.\n\nConfigure this in your `package.json`:\n\n```\n  \"graphql-typegen\": {\n    \"useFunctionTypeArguments\": false\n  }\n```\n\n### When `true` (default)\n\nAdds `\u003cQueryData, QueryVariables\u003e` to `useQuery`:\n\n```js\nconst {loading, error, data} = useQuery\u003cQueryData, QueryVariables\u003e(query, {\n  variables: {id}\n})\n```\n\n### When `false`:\n\nAnnotates this way:\n\n```js\nconst { loading, error, data }: QueryRenderProps\u003cQueryData, QueryVariables\u003e =\n  useQuery(query, {\n    variables: ({ id }: QueryVariables),\n  })\n```\n\n## `external as \u003ctype annotation or import statement\u003e`\n\nMakes `graphql-typegen` use the given external type for a scalar.\n\nPlaces this may be configured, in order of increasing precendence:\n\n### in the description for a type or field in your GraphQL schema\n\n```graphql\n\"\"\"\n@graphql-typegen external as import { type DateISOString } from './src/types/DateISOString'\n\"\"\"\nscalar DateTime\n```\n\n### in a comment in your GraphQL document\n\n```js\nconst query = gql`\n  query user($id: Int!) {\n    user(id: $id) {\n      id\n      # @graphql-typegen external as string\n      createdAt\n    }\n  }\n`\n```\n\n## `extract [as \u003cidentifier\u003e]`\n\nMakes `graphql-typegen` extract the given type or field's inner type into a type alias,\ninstead of generating an inline type.\n\nThere may be funky behavior if a selection set with inline fragment spreads is extracted.\n\nThe name of the type is used if you don't specify **as \u003cidentifier\u003e**.\n\nPlaces this may be configured, in order of increasing precendence:\n\n### in the description for a type or field in your GraphQL schema\n\n```graphql\n\"\"\"\n@graphql-typegen extract\n\"\"\"\ntype User {\n\n}\n```\n\n### in a comment in your GraphQL document\n\n```js\nconst query = gql`\n  query user($id: Int!) {\n    # @graphql-typegen extract as User\n    user(id: $id) {\n      id\n      name\n    }\n  }\n`\n```\n\n#### Output without `extract`\n\n```js\n// @graphql-typegen auto-generated\ntype UserQueryData = {\n  __typename: 'Query',\n  user: ?{\n    id: string,\n    name: string,\n  },\n}\n```\n\n#### Output with `extract as User`\n\n```js\n// @graphql-typegen auto-generated\ntype UserQueryData = {\n  __typename: 'Query',\n  user: ?User,\n}\n\n// @graphql-typegen auto-generated\ntype User = {\n  id: string,\n  name: string,\n}\n```\n\n## `ignore [data | variables]`\n\n`ignore data` makes `graphql-typegen` not output a data type.\n`ignore variables` makes `graphql-typegen` not output a variables type.\n`ignore` makes `graphql-typegen` not output either a data or variables type.\n\nThis may be set in a comment in your GraphQL operation:\n\n```js\nconst query = gql`\n  # @graphql-typegen ignore variables\n  query user($id: Int!) {\n    user(id: $id) {\n      id\n      name\n    }\n  }\n`\n```\n\n# CLI Usage\n\n```\njscodeshift -t path/to/graphql-typegen/graphql-typegen.js src/**/*.js\n```\n\n# Node.js API\n\nBecause `jscodeshift` unfortunately requires transform functions to be sync,\n`graphql-typegen` uses an `execFileSync` hack to synchronously fetch your schema\nfrom your schema file or server.\n\nIf you're calling directly from node, you can bypass this by using `graphql-typegen-async`:\n\n```js\nimport graphqlTypegen from 'graphql-typegen/graphql-typegen-async'\n```\n\nIt has the same API as a `jscodeshift` transform, except that it returns a `Promise` instead\nof a sync result. Maybe someday `jscodeshift` will support async transforms.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodemodsquad%2Fgraphql-typegen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodemodsquad%2Fgraphql-typegen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodemodsquad%2Fgraphql-typegen/lists"}