{"id":13452156,"url":"https://github.com/apollographql/graphql-tag","last_synced_at":"2025-05-13T17:07:32.940Z","repository":{"id":38815194,"uuid":"61910952","full_name":"apollographql/graphql-tag","owner":"apollographql","description":"A JavaScript template literal tag that parses GraphQL queries","archived":false,"fork":false,"pushed_at":"2024-01-25T14:03:04.000Z","size":1071,"stargazers_count":2341,"open_issues_count":100,"forks_count":179,"subscribers_count":41,"default_branch":"main","last_synced_at":"2025-05-09T19:04:50.530Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/apollographql.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2016-06-24T20:32:33.000Z","updated_at":"2025-05-06T04:13:01.000Z","dependencies_parsed_at":"2023-07-17T19:54:16.004Z","dependency_job_id":"f30c5526-4572-4f87-b6aa-1883a3b56cb4","html_url":"https://github.com/apollographql/graphql-tag","commit_stats":{"total_commits":278,"total_committers":63,"mean_commits":4.412698412698413,"dds":0.8633093525179856,"last_synced_commit":"9f1cffef678d3e61181b98fd4849455f1b871e23"},"previous_names":["apollostack/graphql-tag"],"tags_count":35,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apollographql%2Fgraphql-tag","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apollographql%2Fgraphql-tag/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apollographql%2Fgraphql-tag/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apollographql%2Fgraphql-tag/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/apollographql","download_url":"https://codeload.github.com/apollographql/graphql-tag/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253501858,"owners_count":21918327,"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":[],"created_at":"2024-07-31T07:01:15.149Z","updated_at":"2025-05-13T17:07:32.874Z","avatar_url":"https://github.com/apollographql.png","language":"TypeScript","funding_links":[],"categories":["Libraries","JavaScript","TypeScript","Implementations"],"sub_categories":["JavaScript Libraries","JavaScript/TypeScript","GraphQL"],"readme":"# graphql-tag\n[![npm version](https://badge.fury.io/js/graphql-tag.svg)](https://badge.fury.io/js/graphql-tag)\n[![Build Status](https://travis-ci.org/apollographql/graphql-tag.svg?branch=master)](https://travis-ci.org/apollographql/graphql-tag)\n[![Get on Slack](https://img.shields.io/badge/slack-join-orange.svg)](http://www.apollodata.com/#slack)\n\nHelpful utilities for parsing GraphQL queries. Includes:\n\n- `gql` A JavaScript template literal tag that parses GraphQL query strings into the standard GraphQL AST.\n- `/loader` A webpack loader to preprocess queries\n\n`graphql-tag` uses [the reference `graphql` library](https://github.com/graphql/graphql-js) under the hood as a peer dependency, so in addition to installing this module, you'll also have to install `graphql`.\n\n### gql\n\nThe `gql` template literal tag can be used to concisely write a GraphQL query that is parsed into a standard GraphQL AST. It is the recommended method for passing queries to [Apollo Client](https://github.com/apollographql/apollo-client). While it is primarily built for Apollo Client, it generates a generic GraphQL AST which can be used by any GraphQL client.\n\n```js\nimport gql from 'graphql-tag';\n\nconst query = gql`\n  {\n    user(id: 5) {\n      firstName\n      lastName\n    }\n  }\n`\n```\n\nThe above query now contains the following syntax tree.\n\n```js\n{\n  \"kind\": \"Document\",\n  \"definitions\": [\n    {\n      \"kind\": \"OperationDefinition\",\n      \"operation\": \"query\",\n      \"name\": null,\n      \"variableDefinitions\": null,\n      \"directives\": [],\n      \"selectionSet\": {\n        \"kind\": \"SelectionSet\",\n        \"selections\": [\n          {\n            \"kind\": \"Field\",\n            \"alias\": null,\n            \"name\": {\n              \"kind\": \"Name\",\n              \"value\": \"user\",\n              ...\n            }\n          }\n        ]\n      }\n    }\n  ]\n}\n```\n\n#### Fragments\n\nThe `gql` tag can also be used to define reusable fragments, which can easily be added to queries or other fragments.\n\n```js\nimport gql from 'graphql-tag';\n\nconst userFragment = gql`\n  fragment User_user on User {\n    firstName\n    lastName\n  }\n`\n```\n\nThe above `userFragment` document can be embedded in another document using a template literal placeholder.\n\n```js\nconst query = gql`\n  {\n    user(id: 5) {\n      ...User_user\n    }\n  }\n  ${userFragment}\n`\n```\n\n**Note:** _While it may seem redundant to have to both embed the `userFragment` variable in the template literal **AND** spread the `...User_user` fragment in the graphQL selection set, this requirement makes static analysis by tools such as `eslint-plugin-graphql` possible._\n\n#### Why use this?\n\nGraphQL strings are the right way to write queries in your code, because they can be statically analyzed using tools like [eslint-plugin-graphql](https://github.com/apollographql/eslint-plugin-graphql). However, strings are inconvenient to manipulate, if you are trying to do things like add extra fields, merge multiple queries together, or other interesting stuff.\n\nThat's where this package comes in - it lets you write your queries with [ES2015 template literals](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals) and compile them into an AST with the `gql` tag.\n\n#### Caching parse results\n\nThis package only has one feature - it caches previous parse results in a simple dictionary. This means that if you call the tag on the same query multiple times, it doesn't waste time parsing it again. It also means you can use `===` to compare queries to check if they are identical.\n\n\n### Importing graphQL files\n\n_To add support for importing `.graphql`/`.gql` files, see [Webpack loading and preprocessing](#webpack-loading-and-preprocessing) below._\n\nGiven a file `MyQuery.graphql`\n\n```graphql\nquery MyQuery {\n  ...\n}\n```\n\nIf you have configured [the webpack graphql-tag/loader](#webpack-loading-and-preprocessing), you can import modules containing graphQL queries. The imported value will be the pre-built AST.\n\n```js\nimport MyQuery from 'query.graphql'\n```\n\n#### Importing queries by name\n\nYou can also import query and fragment documents by name.\n\n```graphql\nquery MyQuery1 {\n  ...\n}\n\nquery MyQuery2 {\n  ...\n}\n```\n\nAnd in your JavaScript:\n\n```javascript\nimport { MyQuery1, MyQuery2 } from 'query.graphql'\n```\n\n### Preprocessing queries and fragments\n\nPreprocessing GraphQL queries and fragments into ASTs at build time can greatly improve load times.\n\n#### Babel preprocessing\n\nGraphQL queries can be compiled at build time using [babel-plugin-graphql-tag](https://github.com/gajus/babel-plugin-graphql-tag). Pre-compiling queries decreases script initialization time and reduces bundle sizes by potentially removing the need for `graphql-tag` at runtime.\n\n#### TypeScript preprocessing\n\nTry this custom transformer to pre-compile your GraphQL queries in TypeScript: [ts-transform-graphql-tag](https://github.com/firede/ts-transform-graphql-tag).\n\n#### React Native and Next.js preprocessing\n\nPreprocessing queries via the webpack loader is not always possible. [babel-plugin-import-graphql](https://www.npmjs.com/package/babel-plugin-import-graphql) supports importing graphql files directly into your JavaScript by preprocessing GraphQL queries into ASTs at compile-time.\n\nE.g.:\n\n```javascript\nimport myImportedQuery from './productsQuery.graphql'\n\nclass ProductsPage extends React.Component {\n  ...\n}\n```\n\n#### Webpack loading and preprocessing\n\nUsing the included `graphql-tag/loader` it is possible to maintain query logic that is separate from the rest of your application logic. With the loader configured, imported graphQL files will be converted to AST during the webpack build process.\n\n_**Example webpack configuration**_\n\n```js\n{\n  ...\n  loaders: [\n    {\n      test: /\\.(graphql|gql)$/,\n      exclude: /node_modules/,\n      loader: 'graphql-tag/loader'\n    }\n  ],\n  ...\n}\n```\n\n#### Create React App\n\nPreprocessing GraphQL imports is supported in **create-react-app** \u003e= v2 using [evenchange4/graphql.macro](https://github.com/evenchange4/graphql.macro).\n\nFor **create-react-app** \u003c v2, you'll either need to eject or use [react-app-rewire-inline-import-graphql-ast](https://www.npmjs.com/package/react-app-rewire-inline-import-graphql-ast).\n\n#### Testing\n\nTesting environments that don't support Webpack require additional configuration. For [Jest](https://facebook.github.io/jest/) use [jest-transform-graphql](https://github.com/remind101/jest-transform-graphql).\n\n#### Support for fragments\n\nWith the webpack loader, you can import fragments by name:\n\nIn a file called `query.gql`:\n\n```graphql\nfragment MyFragment1 on MyType1 {\n  ...\n}\n\nfragment MyFragment2 on MyType2 {\n  ...\n}\n```\n\nAnd in your JavaScript:\n\n```javascript\nimport { MyFragment1, MyFragment2 } from 'query.gql'\n```\n\nNote: If your fragment references other fragments, the resulting document will\nhave multiple fragments in it. In this case you must still specify the fragment name when using the fragment. For example, with `@apollo/client` you would specify the `fragmentName` option when using the fragment for cache operations.\n\n### Warnings\n\nThis package will emit a warning if you have multiple fragments of the same name. You can disable this with:\n\n```js\nimport { disableFragmentWarnings } from 'graphql-tag';\n\ndisableFragmentWarnings()\n```\n\n### Experimental Fragment Variables\n\nThis package exports an `experimentalFragmentVariables` flag that allows you to use experimental support for [parameterized fragments](https://github.com/facebook/graphql/issues/204).\n\nYou can enable / disable this with:\n\n```js\nimport { enableExperimentalFragmentVariables, disableExperimentalFragmentVariables } from 'graphql-tag';\n```\n\nEnabling this feature allows you to declare documents of the form.\n\n```graphql\nfragment SomeFragment ($arg: String!) on SomeType {\n  someField\n}\n```\n\n### Resources\n\nYou can easily generate and explore a GraphQL AST on [astexplorer.net](https://astexplorer.net/#/drYr8X1rnP/1).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapollographql%2Fgraphql-tag","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fapollographql%2Fgraphql-tag","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapollographql%2Fgraphql-tag/lists"}