{"id":13547069,"url":"https://github.com/piglovesyou/graphql-let","last_synced_at":"2025-05-14T13:09:04.184Z","repository":{"id":39580111,"uuid":"228404071","full_name":"piglovesyou/graphql-let","owner":"piglovesyou","description":"A webpack loader / babel-plugin / babel-plugin-macros / CLI / generated file manager of GraphQL code generator.","archived":false,"fork":false,"pushed_at":"2025-04-17T19:24:52.000Z","size":5151,"stargazers_count":455,"open_issues_count":64,"forks_count":34,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-05-12T18:00:53.939Z","etag":null,"topics":["babel-plugin","babel-plugin-macros","graphql","graphql-codegen","jest-transformer","typescript","webpack-loader"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/piglovesyou.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","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,"zenodo":null},"funding":{"github":"piglovesyou"}},"created_at":"2019-12-16T14:22:37.000Z","updated_at":"2025-04-24T02:32:28.000Z","dependencies_parsed_at":"2023-02-18T08:01:17.089Z","dependency_job_id":"e9505958-b045-4fa1-b003-143ce3d80f31","html_url":"https://github.com/piglovesyou/graphql-let","commit_stats":{"total_commits":461,"total_committers":21,"mean_commits":"21.952380952380953","dds":0.5748373101952278,"last_synced_commit":"a5e95fa9d724c9885230c56e804116c84a5fc08d"},"previous_names":[],"tags_count":75,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piglovesyou%2Fgraphql-let","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piglovesyou%2Fgraphql-let/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piglovesyou%2Fgraphql-let/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piglovesyou%2Fgraphql-let/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/piglovesyou","download_url":"https://codeload.github.com/piglovesyou/graphql-let/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254149976,"owners_count":22022852,"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":["babel-plugin","babel-plugin-macros","graphql","graphql-codegen","jest-transformer","typescript","webpack-loader"],"created_at":"2024-08-01T12:00:50.538Z","updated_at":"2025-05-14T13:08:59.141Z","avatar_url":"https://github.com/piglovesyou.png","language":"TypeScript","funding_links":["https://github.com/sponsors/piglovesyou"],"categories":["Libraries","TypeScript","Implementations"],"sub_categories":["JavaScript Libraries","JavaScript/TypeScript"],"readme":"# graphql-let [![Node CI](https://github.com/piglovesyou/graphql-let/actions/workflows/nodejs.yml/badge.svg?branch=main)](https://github.com/piglovesyou/graphql-let/actions/workflows/nodejs.yml) [![npm version](https://badgen.net/npm/v/graphql-let)](https://www.npmjs.com/package/graphql-let) [![downloads](https://badgen.net/npm/dm/graphql-let)](https://www.npmjs.com/package/graphql-let) [![Babel Macro](https://img.shields.io/badge/babel--macro-%F0%9F%8E%A3-f5da55.svg?style=flat-square)](https://github.com/kentcdodds/babel-plugin-macros) [![Stake to support us](https://badge.devprotocol.xyz/0xaC5f6A59f4b40eCF0815eB53Af49A83834b47005/descriptive)](https://stakes.social/0xaC5f6A59f4b40eCF0815eB53Af49A83834b47005)\n\nA webpack loader/babel-plugin/babel-plugin-macros/CLI/generated file manager of\nGraphQL code generator.\n\nTry\n[Create React App example](https://github.com/piglovesyou/cra-template-graphql#readme)\nand\n[Next.js example](https://github.com/zeit/next.js/blob/canary/examples/with-typescript-graphql/README.md#readme)\nintegrating graphql-let. [A blog post](https://the-guild.dev/blog/graphql-let)\n\n🛰 **[Migration guide to v0.18.0](https://github.com/piglovesyou/graphql-let/releases/tag/v0.18.0)**\n\n## Table of Contents\n\n-   [Why this exists](#why-this-exists)\n-   [Entrypoints and features](#entrypoints-and-features)\n-   [Getting started with webpack loader](#getting-started-with-webpack-loader)\n-   [Getting started with babel-plugin-macros](#getting-started-with-babel-plugin-macros)\n-   [Getting started with Babel Plugin](#getting-started-with-babel-plugin)\n-   [Difference between .graphql-let.yml and codegen.yml](#difference-between-graphql-letyml-and-codegenyml)\n-   [Jest Transformer](#jest-transformer)\n-   [Experimental feature: Resolver Types](#experimental-feature-resolver-types)\n-   [FAQ](#faq)\n-   [Contribution](#contribution)\n-   [License](#license)\n\n## Why this exists\n\nOne of the strengths of GraphQL is\n[enforcing data types on runtime](https://graphql.github.io/graphql-spec/June2018/#sec-Value-Completion).\nFurther, TypeScript and\n[GraphQL code generator](https://graphql-code-generator.com/) help it even safer\nby typing your codebase statically. Both make a truly type-protected development\nenvironment with rich IDE assists.\n\ngraphql-let enhances that development pattern by minimizing configuration setup,\nintroducing intuitive syntax, and comfortable development experience through HMR\n(hot module replacement).\n\n```typescript jsx\nimport { useNewsQuery } from './news.graphql' // webpack\n// or\nimport { gql, load } from \"graphql-let/macro\" // babel-plugin-macros\nconst { useNewsQuery } = gql(\"query News { braa }\")\n\nconst News: React.FC = () =\u003e {\n    // Typed already️⚡️\n    const { data: { news } } = useNewsQuery()\n    return \u003cdiv\u003e{news.map(...)}\u003c/div\u003e\n}\n```\n\n## Entrypoints and features\n\nSummary of characteristics of each entrypoint.\n\n-   **CLI** for efficient code generation before your type checking\n-   **webpack loader** to get HMR even on modifying GraphQL documents\n-   **babel-plugin-macros** for the minimum configuration\n-   **Babel plugin** if you don't want babel-plugin-macros\n\nAll of them mostly do the same behind the scene.\n\n1.  Loads your configuration from `.graphql-let.yml`\n2.  Finds GraphQL documents (queries, mutations, subscriptions) from `.graphql*`\n    and `.ts*` specified in your `config.documents`\n3.  Processes and passes arguments to GraphQL code generator **to generate\n    `.ts*` s**. These are used for runtime.\n4.  It also **generates the corresponding `.d.ts` s** of the codegen results.\n    These are used for typing checking / IDE code completion.\n\nNote there are a few differences between the entrypoints.\n\n\u003cdetails\u003e\n  \u003csummary\u003eSyntax table for the entrypoints\u003c/summary\u003e\n    \u003ctable\u003e\n        \u003ctr\u003e\n            \u003cth\u003eEntry pointsYou need .graphql-let.yml and:\u003c/th\u003e\n            \u003cth\u003eGetting codegen result from\u003c/th\u003e\n            \u003cth\u003eUse values of codegen result\u003c/th\u003e\n            \u003cth\u003eUse types of codegen result\u003c/th\u003e\n            \u003cth\u003ePros/Cons\u003c/th\u003e\n        \u003c/tr\u003e\n        \u003ctr\u003e\n            \u003cth rowspan=\"2\" align=\"left\"\u003ewebpack loader\u003cbr /\u003e\u003cbr /\u003eConfigure \u003ccode\u003e\"graphql-let/loader\"\u003c/code\u003e\u003cbr /\u003e to files \u003ccode\u003e\"/.*\\.(tsx?|graphql)$/\"\u003c/code\u003e in webpack.config.(js|ts)\u003c/td\u003e\n            \u003ctd\u003eFile\u003c/td\u003e\n            \u003ctd colspan=\"2\"\u003e✅ Import both value and types from a GraphQL document as a module.\u003cpre\u003eimport { useQuery, Query } from \"./a.graphql\"\u003c/pre\u003e\u003c/td\u003e\n            \u003ctd rowspan=\"2\"\u003eHMR works as expected.\u003cbr /\u003eWebpack config is required even though your project only uses Babel\u003c/td\u003e\n        \u003c/tr\u003e\n        \u003ctr\u003e\n            \u003ctd\u003eString literal\u003c/td\u003e\n            \u003ctd\u003e✅ by\u003cpre\u003eimport { gql } from \"graphql-let\" \u003cbr /\u003e\u003cbr /\u003econst { useQuery } = gql(\"query A { braa }\")\u003c/pre\u003e\u003c/td\u003e\n            \u003ctd\u003e⚠️ You can, but you have to find the internal d.ts.\u003cpre\u003eimport { gql } from \"graphql-let\"\u003cbr /\u003eimport {Query} from 'graphql-let/__generated__/index-A'\u003cbr /\u003e\u003cbr /\u003econst { useQuery } = gql(\"query { braa }\")\u003c/pre\u003e\u003c/td\u003e\n        \u003c/tr\u003e\n        \u003ctr\u003e\n            \u003cth rowspan=\"2\" align=\"left\"\u003ebabel-plugin-macros\u003cbr /\u003e\u003cbr /\u003eIf you've already setupbabel-plugin-macros,no config needed any more\u003c/td\u003e\n            \u003ctd\u003eFile\u003c/td\u003e\n            \u003ctd\u003e✅ by\u003cpre\u003eimport { load } from \"graphql-let/macro\"\u003cbr /\u003e\u003cbr /\u003econst { useQuery } = load(\"./a.graphql\")\u003c/pre\u003e\u003c/td\u003e\n            \u003ctd\u003e⚠️ You can, but you have to find the internally generated d.ts.\u003cpre\u003eimport { load } from \"graphql-let/macro\"\u003cbr /\u003eimport {Query} from 'graphql-let/__generated__/index-A'\u003cbr /\u003e\u003cbr /\u003econst { useQuery } = load(\"./a.graphql\")\u003c/pre\u003e\u003c/td\u003e\n            \u003ctd rowspan=\"2\"\u003eEasiest to integrate if your project already has babel-plugin-macros. create-react-app is the great fit.Cannot load types from function call.\u003cbr /\u003e\u003cbr /\u003eModifying *.graphql doesn't emit HMR.\u003c/td\u003e\n        \u003c/tr\u003e\n        \u003ctr\u003e\n            \u003ctd\u003eString literal\u003c/td\u003e\n            \u003ctd\u003e✅ by\u003cpre\u003eimport { gql } from \"graphql-let/macro\"\u003cbr /\u003e\u003cbr /\u003econst { useQuery } = gql(\"query A { braa }\")\u003c/pre\u003e\u003c/td\u003e\n            \u003ctd\u003e⚠️ You can, but you have to find the internally generated d.ts.\u003cpre\u003eimport { gql } from \"graphql-let/macro\"\u003cbr /\u003eimport {Query} from 'graphql-let/__generated__/index-A'\u003cbr /\u003e\u003cbr /\u003econst { useQuery } = gql(\"query { braa }\")\u003c/pre\u003e\u003c/td\u003e\n        \u003c/tr\u003e\n        \u003ctr\u003e\n            \u003cth rowspan=\"2\" align=\"left\"\u003ebabel-plugin\u003cbr /\u003e\u003cbr /\u003ePut \"graphql-let/babel\"to you .babelrc as a plugin\u003c/td\u003e\n            \u003ctd\u003eFile\u003c/td\u003e\n            \u003ctd\u003e✅ by\u003cpre\u003eimport { load } from \"graphql-let\"\u003cbr /\u003e\u003cbr /\u003econst { useQuery } = load(\"./a.graphql\")\u003c/pre\u003e\u003c/td\u003e\n            \u003ctd\u003e⚠️ You can, but you have to find the internally generated d.ts.\u003cpre\u003eimport { load } from \"graphql-let\"\u003cbr /\u003eimport {Query} from 'graphql-let/__generated__/index-A'\u003cbr /\u003e\u003cbr /\u003econst { useQuery } = load(\"./a.graphql\")\u003c/pre\u003e\u003c/td\u003e\n            \u003ctd rowspan=\"2\"\u003eMostly equivalent to babel-plugin-macros, but you always need your .babelrc configuration. Possibly, \"import \"./a.graphql\"\" could be implemented, but not supported yet.Cannot load types from function call.\u003cbr /\u003e\u003cbr /\u003eModifying *.graphql doesn't emit HMR.Possibly I can make \"--watch\" option butlots to do for dependency management to detect file change.\u003c/td\u003e\n        \u003c/tr\u003e\n        \u003ctr\u003e\n            \u003ctd\u003eString literal\u003c/td\u003e\n            \u003ctd\u003e✅ by\u003cpre\u003eimport { gql } from \"graphql-let\"\u003cbr /\u003e\u003cbr /\u003econst { useQuery } = gql(\"query A { braa }\")\u003c/pre\u003e\u003c/td\u003e\n            \u003ctd\u003e⚠️ You can, but you have to find the internally generated d.ts.\u003cpre\u003eimport { gql } from \"graphql-let\"\u003cbr /\u003eimport {Query} from 'graphql-let/__generated__/index-A'\u003cbr /\u003e\u003cbr /\u003econst { useQuery } = gql(\"query { braa }\")\u003c/pre\u003e\u003c/td\u003e\n        \u003c/tr\u003e\n    \u003c/table\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eEfficiency\u003c/summary\u003e\n\nThere are things to make graphql-let light and stable.\n\n-   Sharing the processes. Generating files is expensive, so it runs less time\n    to run GraphQL code generator and TypeScript API.\n-   Caching. Embedding hashes, as your source states, reduces the number of\n    unnecessary processing.\n-   Sharing the promises. The webpack compilation in typical SSR applications as\n    Next.js runs [targets](https://webpack.js.org/concepts/targets/) of `\"node\"`\n    and `\"web\"` simultaneously. If sources are the same, the compilation should\n    be once.\n\n\u003c/details\u003e\n\n## Getting started with webpack loader\n\nThis is an example of **TypeScript + React + Apollo Client on webpack**. You may\nwant\n[TypeScript Vue Apollo](https://www.graphql-code-generator.com/docs/plugins/typescript-vue-apollo)\nor\n[TypeScript Urql](https://www.graphql-code-generator.com/docs/plugins/typescript-urql).\nPlease replace the corresponding lines depending on your needs.\n\n### 1. Install dependencies\n\nNote graphql-let is in `devDependencies`.\n\n```bash\n# Prerequisites\nyarn add -D typescript graphql\n\n# Install graphql-let with its peer dependencies\nyarn add -D graphql-let @graphql-codegen/cli @graphql-codegen/typescript @graphql-codegen/import-types-preset\n\n# Install GraphQL code generator plugins depending on your needs. These are in `plugins` of your .graphql-let.yml.\nyarn add -D @graphql-codegen/typescript-operations @graphql-codegen/typescript-react-apollo\n\n# Other libraries depending on your scenario\nyarn add @apollo/client\n```\n\n### 2. Configure .graphql-let.yml\n\nRun this command to generate a configuration template.\n\n```bash\nyarn graphql-let init\n# This will generate .graphql-let.yml\n```\n\nNext, add\n[graphql-codegen plugins](https://graphql-code-generator.com/docs/plugins/index)\nin it. **Please note that you have to generate a TypeScript source** by the\nplugins.\n\nEdit it like this:\n\n```diff\n  schema: lib/type-defs.graphqls\n  documents:\n    - '**/*.graphql'\n    - '**/*.tsx'\n  plugins:\n+   - typescript-operations\n+   - typescript-react-apollo\n```\n\n### 3. Check your `cacheDir`\n\n`cacheDir` will have `.ts(x)`s that your sources will import. It's\n`node_modules/.cache/graphql-let` by default, but you may exclude `node_modules`\nfor webpack compilation. In that case, we recommend setting up like this.\n\n```diff\n  schema: lib/type-defs.graphqls\n  documents:\n    - '**/*.graphql'\n    - '**/*.tsx'\n  plugins:\n    - typescript-operations\n    - typescript-react-apollo\n+ cacheDir: .cache\n```\n\nPlease note that files in `cacheDir` are only intermediate cache, possibly having wrong import paths. Your `tsconfig.json` probably complains, so give it a line for exclusion.\n\n```diff\n  // tsconfig.json\n  {\n+   \"excludes\": [\".cache\"]\n  }\n```\nAlso, remember you have to `.gitignore` the `.cache` directory in the next section.\n\n### 3. Add lines to .gitignore\n\ngraphql-let will generate `.d.ts` files in the same folder of `.graphql`. Add\nthese lines in your .gitignore.\n\n```diff\n+ *.graphql.d.ts\n+ *.graphqls.d.ts\n+ /.cache\n```\n\n### 4. Configure webpack.config.ts\n\nThe webpack loader also needs to be configured. Note that the content that\n`graphql-let/loader` generates is JSX-TypeScript. You have to compile it to\nJavaScript with an additional loader such as `babel-loader`.\n\n```diff\n  const config: Configuration = {\n    module: {\n      rules: [\n+       {\n+         test: /\\.(tsx|graphql)$/,\n+         use: [\n+           { loader: 'babel-loader', options: { presets: ['@babel/preset-typescript', '@babel/preset-react'] } },\n+           { loader: 'graphql-let/loader' },\n+         ]\n+       }\n      ]\n    }\n  }\n```\n\n### 5. Generate type declarations\n\nRun this to generate `.d.ts`.\n\n```bash\nyarn graphql-let\n\n# This will generate files such as:\n#   - src/query.graphql.d.ts\n#   - src/schema.graphqls.d.ts\n```\n\nBy `--config` option, you can specify the custom path to the `.graphql-let.yml`.\nThe directory .graphql-let.yml is located at **is the basepath of** the relative\npaths in .grpahql-let.yml. Also, the basepath should be identical to webpack's\n`config.context` so the loader can find the config file.\n\n```bash\npwd # \"/app\"\nyarn graphql-let --config custom/path/.graphql-let.yml\n\n# This will point paths such as:\n# /app/custom/path/src/query.graphql.d.ts\n# /app/custom/path/src/schema.graphqls.d.ts\n```\n\nYou may want to run it every time before calling `tsc`. Please check your\n`package.json` and modify like this.\n\n```diff\n   \"scripts\": {\n-     \"build\": \"tsc\"\n+     \"build\": \"graphql-let \u0026\u0026 tsc\"\n   },\n```\n\n### 6. Run `webpack serve` and Code\n\nEnjoy HMR (Hot Module Replacement) of webpack with the generated react-apollo\nhooks and IDE code assists.\n\n```typescript jsx\nimport { gql } from 'graphql-let'\nimport { useNewsQuery } from './news.graphql'\n\nconst { useViewerQuery } = gql(`query Viewer { blaa }`)\n\nconst News: React.FC = () =\u003e {\n    // Already typed⚡️\n    const { data: { news } } = useNewsQuery()\n    const { data: { viewer } } = useViewerQuery()\n    return \u003cdiv\u003e{ news.map(...) }\u003c/div\u003e\n}\n```\n\n## Getting started with babel-plugin-macros\n\n[babel-plugin-macros](https://github.com/kentcdodds/babel-plugin-macros)\nrequires the least configuration to setup.\n\nPlease finish [1. Install dependencies](#1-install-dependencies), and\n[2. Configure .graphql-let.yml](#2-configure-graphql-letyml) as you still need\n.graphql-let.yml.\n\n### 3. Make sure your babel-plugin-macros is ready\n\n[Put a line `\"plugins\": [\"macros\"]` to your .babelrc](https://github.com/kentcdodds/babel-plugin-macros/blob/main/other/docs/user.md#via-babelrc-recommended).\nIf you use [Create React App](https://create-react-app.dev/), it contains\nbabel-plugin-macros out of the box.\n\nIf you want a custom path to .graphql-let.yml, you can use `configFilePath`\nbabel option. `\u003cprojectRoot\u003e${configFilePath}` should point to your\n.graphql-let.yml.\n\n### 4. Code\n\nThanks to babel-plugin-macros's beautiful architecture, you're ready to use\nGraphQL codegen values.\n\n```typescript jsx\nimport { gql, load } from \"graphql-let/macro\"\n\n// Typed⚡️\nconst { useNewsQuery } = gql(\"query News { braa }\")\nconst { useViewerQuery } = load(\"./viewer.graphql\")\n```\n\nNote that your schema types are generated in\n`graphql-let/__generated__/__types__`, instead of per-document outputs.\n\n```typescript jsx\nimport { News } from 'graphql-let/__generated__/__types__'\n```\n\n## Getting started with Babel Plugin\n\nMostly the same as babel-plugin-macros, only you need to `import \"graphql-let\"`.\n\nPlease finish [1. Install dependencies](#1-install-dependencies) and\n[2. Configure .graphql-let.yml](#2-configure-graphql-letyml) as you still need\n.graphql-let.yml.\n\n### 3. Setup .babelrc\n\n```diff\n  {\n+   \"plugins\": [\"graphql-let/babel\"]\n  }\n```\n\n### 4. Code\n\n```typescript jsx\nimport { gql, load } from \"graphql-let\"\n\nconst { useNewsQuery } = gql(\"query News { braa }\")\nconst { useViewerQuery } = load(\"./viewer.graphql\")\n```\n\n## Difference between .graphql-let.yml and codegen.yml\n\ngraphql-let half passes your config options to GraphQL code generator API and\nhalf controls them. Here explains how different these and why. You can see this\nsection as a migration guide, too.\n\n```diff\n  schema: https://api.github.com/graphql\n  documents: \"**/*.graphql\"\n- generates:\n-     ./__generated__/operations.ts:\n-         config:\n-             key: value\n-         plugins:\n-             - typescript\n-             - typescript-operations\n-         preset: xxx\n+ plugins:\n+     - typescript-operations\n+ config:\n+     key: value\n```\n\n### Plugin `typescript` should not be specified\n\nYou have to have `@graphql-codegen/typescript` as a dev dependency. graphql-let\ngenerates types **by default**, where it uses the plugin. The `plugins` in\n.graphql-let.yml is for per-document, which imports the shared types\nautomatically. If you specify `typescript` as a plugin, it's\nstill okay, but you can imagine it's kind of redundant.\n\n### No `generates`\n\ncodegen.yml has an option `generates`, but it's strictly controlled under\ngraphql-let. Rather, think graphql-let as a tool to let you forget intermediate\noutputs and import/call GraphQL directly.\n\nTherefore, we don't support output-file level configuration such as\n[Output-file level schema](https://graphql-code-generator.com/docs/getting-started/schema-field#output-file-level),\n[Output-file level documents](https://graphql-code-generator.com/docs/getting-started/documents-field#output-file-level),\nand\n[Output Level config](https://graphql-code-generator.com/docs/getting-started/config-field#output-level)\nright now. But this could be changed logically, so please\n[vote by issuing](https://github.com/piglovesyou/graphql-let/issues) if you'd\nlike.\n\n### No `preset`\n\n[Presets](https://www.graphql-code-generator.com/docs/presets/presets-index)\ndecide how to split/import each other, which graphql-let manages basically.\ngraphql-let generates per-document `.d.ts` and binds up schema types into a\nshared file, that's why\n[`@graphql-codegen/import-types-preset`](https://www.graphql-code-generator.com/docs/presets/import-types)\nis our peer dependency.\n\nI think you don't need to configure Presets, because graphql-let takes care of\nwhat Presets does on your behalf. If you notice the use-case you need more\nflexibility, please issue it.\n\n### Limitation: `documents` expects `string | string[]`\n\nDocument-level options such as `noRequir` or\n[Custom Document Loader](https://graphql-code-generator.com/docs/getting-started/documents-field#custom-document-loader)\nare not supported.\n\n### graphql-let specific options\n\nIn addition to `codegen.yml` options, graphql-let accepts these.\n\n```yaml\n# \"plugins\", required. The plugins for GraphQL documents to run GraphQL code\n# generator with. You should omit `typescript` plugin which graphql-let generates internally.\n# See here for more information. https://graphql-code-generator.com/docs/plugins/index\n# Example:\nplugins:\n    - typescript-operations\n    - typescript-react-apollo\n    - add: \"/* eslint-disable */\"\n\n# \"respectGitIgnore\", optional. `true` by default.\n# If true, graphql-let will ignore files in .gitignore.\n# Useful to prevent parsing files in such as `node_modules`.\nrespectGitIgnore: true\n\n# \"cacheDir\", optional. `node_modules/.cache/graphql-let` by default.\n# graphql-let takes care of intermediate `.ts(x)`s that GraphQL code generator\n# generates, but we still need to write them on the disk for caching and\n# TypeScript API purposes. This is the directory we store them to.\n# Examples:\ncacheDir: node_modules/.cache/graphql-let\ncacheDir: .cache\n\n# \"TSConfigFile\", optional. `tsconfig.json` by default.\n# You can specify a custom config for generating `.d.ts`s.\n# Examples:\nTSConfigFile: tsconfig.json\nTSConfigFile: tsconfig.compile.json\n\n# \"typeInjectEntrypoint\", optional.\n# `node_modules/@types/graphql-let/index.d.ts` by default. Needs to end with \".d.ts\".\n# Used as an entrypoint and directory of generated type declarations\n# for `gql()` and `load()` calls.\ntypeInjectEntrypoint: node_modules/@types/graphql-let/index.d.ts\n\n# \"silent\", optional. `false` by default.\n# Pass `true` if you want to suppress all standard output from graphql-let.\nsilent: false\n```\n\nSimple example:\n\n```yaml\nschema: \"schema/**/*.graphqls\"\ndocuments:\n    - \"**/*.graphql\"\n    - \"!shouldBeIgnored1\"\nplugins:\n    - typescript-operations\n    - typescript-react-apollo\n```\n\nExample with a bit more complicated options:\n\n```yaml\nschema:\n    - https://api.github.com/graphql:\n          headers:\n              Authorization: YOUR-TOKEN-HERE\ndocuments:\n    - \"**/*.graphql\"\n    - \"!shouldBeIgnored1\"\nplugins:\n    - typescript-operations\n    - typescript-react-apollo\nrespectGitIgnore: true\nconfig:\n    reactApolloVersion: 3\n    apolloReactComponentsImportFrom: \"@apollo/client/react/components\"\n    useIndexSignature: true\ncacheDir: .cache\nTSConfigFile: tsconfig.compile.json\ntypeInjectEntrypoint: typings/graphql-let.d.ts\n```\n\n### Limitations of `graphql-let/babel`\n\n-   **Sadly**, type injection can't be done with TaggedTemplateExpression such\n    as `` gql`query {}` ``. This is the limitation of TypeScript.\n    [Please answer me if you have any ideas.](https://stackoverflow.com/questions/61917066/can-taggedtempalte-have-overload-signatures-with-a-certain-string-literal-argume)\n-   Fragments are still not available. Please watch\n    [the issue.](https://github.com/piglovesyou/graphql-let/issues/65)\n\n## Jest Transformer\n\n`graphql-let/jestTransformer` is available. Configure your `jest.config.js` as:\n\n```diff\n  module.exports = {\n    transform: {\n+     \"\\\\.graphql$\": \"graphql-let/jestTransformer\",\n    },\n  };\n```\n\n### Use `babel-jest` in Jest\n\n`babel-jest` is the default subsequent transformer of\n`graphql-let/jestTransformer`. Install these:\n\n```bash\nyarn add -D graphql-let babel-jest\n```\n\nAnd make sure your babel config can compile generated `.ts(x)`s.\n\n### Use `ts-jest` or other subsequent transformers in Jest\n\nThe option `subsequentTransformer` is available. If you use `ts-jest`, your\n`jest.config.js` will look like this:\n\n```diff\n  const { defaults: tsjPreset } = require(\"ts-jest/presets\");\n\n  module.exports = {\n    preset: \"ts-jest\",\n    transform: {\n      ...tsjPreset.transform,\n+     \"\\\\.graphql$\": [\n+       \"graphql-let/jestTransformer\",\n+       { subsequentTransformer: \"ts-jest\" },\n+     ],\n    },\n  };\n```\n\n### Transform `.graphqls` in Jest\n\nIf you use `graphql-let/schema/loader`, you may want a corresponding\ntransformer, but remember graphql-let does not transform the content of GraphQL\nschema. Just use what you need; it's most likely to be `jest-transform-graphql`.\n\n```diff\n  module.exports = {\n    transform: {\n      \"\\\\.graphql$\": \"graphql-let/jestTransformer\",\n+     \"\\\\.graphqls$\": \"jest-transform-graphql\",\n    },\n  };\n```\n\n## Experimental feature: Resolver Types\n\nIf you meet the following conditions, graphql-let generates Resolver Types.\n\n-   You have file paths including glob patterns in `schema`\n-   You have\n    [`@graphql-codegen/typescript-resolvers`](https://graphql-code-generator.com/docs/plugins/typescript-resolvers)\n    installed\n\nRun:\n\n```bash\nyarn add -D @graphql-codegen/typescript-resolvers\nyarn graphql-let\n```\n\nThen you will get resolver types in `graphql-let/__generated__/__types__`.\n\n```typescript\nimport { Resolvers } from \"graphql-let/__generated__/__types__\";\n\nconst resolvers: Resolvers = {\n  Query: {\n    // All typed⚡️\n    viewer(parent, args, context, info) {\n      return { ... }\n    },\n  }\n};\n\nexport default resolvers;\n```\n\n`graphql-let/schema/loader` is also available to update resolver types. It doesn't transpile anything;\njust detects file modification and passes the content to the next loader.\n\n```diff\n  // webpack.config.ts\n  const config: Configuration = {\n    module: {\n      rules: [\n+       {\n+         test: /\\.graphqls$/,\n+         use: [\n+           { loader: 'graphql-let/schema/loader' },\n+         ]\n+       }\n      ]\n    }\n  }\n```\n\n## FAQ\n\n#### So, it's just a graphql-codegen wrapper generating `d.ts`...?\n\n_Yes._\n\n#### Supported combination of tools? / Tools x + y don't work!\n\nThe above documentation should work basically, but some of the combinations may\nrequire more effort. Please vote by creating issues.\n[Sponsoring me](https://github.com/sponsors/piglovesyou) is another way to get\nmy attention🍩🍦👀\n\nThese are the states/tools for the syntaxes.\n\n| states/tools for syntax                                                      | import GraphQL document as\u003cbr\u003e`import './a.graphql';`                          | Inline GraphQL document as\u003cbr\u003e`import {gql} from 'graphql-let';`\u003cbr\u003e`` gql(`query {}` ); `` |\n| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- |\n| generating `.d.ts`s by command `graphql-let`                                 | ✅                                                                             | ✅                                                                                          |\n| importing GraphQL content from another as\u003cbr\u003e`# import A from './a.graphql'` | ✅                                                                             | ✅                                                                                          |\n| webpack loader `graphql-let/loader`                                          | ✅                                                                             | ✅                                                                                          |\n| Babel Plugin `graphql-let/babel`                                             | ✅                                                                             | ✅                                                                                          |\n| Jest Transformer `graphql-let/jestTransfomer`                                | ✅                                                                             | [Vote by issuing](https://github.com/piglovesyou/graphql-let/issues)                        |\n| Experimental: Resolver Types for\u003cbr\u003eGraphQL schema                           | ✅ by\u003cbr\u003e`import {Resolvers}`\u003cbr\u003e `from 'graphql-let/__generated__/__types__'` | (I think we don't need this)                                                                |\n\n#### Is this a tool only for React?\n\nNo. There are\n[more plugins that also generates `.ts(x)`s from GraphQL documents](https://graphql-code-generator.com/docs/plugins/).\n\n#### Can I use Tagged Template as `` gql`query News { baa }`; ``?\n\nSadly, you need `gql()` instead of `` gql` `  `` because of\n[the limitation of TypeScript](https://github.com/microsoft/TypeScript/issues/33304).\n\n#### What's the extensions `.graphql` and `.graphqls`? Can I use `.gql` or something else?\n\nYou can use what you want. I wanted to recommend distinguishing GraphQL schema\nand GraphQL documents in the extensions, which will lead to a more\nunderstandable configuration for webpack loaders with fewer pitfalls. Another\nreason for `.graphqls` is that it's one of\n[the supported extensions in the internal library](https://github.com/ardatan/graphql-toolkit/blob/d29e518a655c02e3e14377c8c7d3de61f08e6200/packages/loaders/graphql-file/src/index.ts#L9).\n\n#### How to integrate Apollo refetchQueries?\n\n[Query document exports `DocumentNode` named `${QueryName}Document` that you can make use of.](https://github.com/piglovesyou/graphql-let/issues/66#issuecomment-596276493)\n\n#### How to import `.graphql` from another document, especially GraphQL Fragment?\n\nThanks to\n[`graphql-tools/import`](https://www.graphql-tools.com/docs/schema-loading/#using-import-expression),\nthe syntax `# import X from './fragment.graphql'` is supported.\n\nDefine your fragment named as `partial.graphql`\n\n```graphql\nfragment Partial on User {\n    id\n    name\n}\n```\n\nand import it.\n\n```graphql\n# import Partial from './partial.graphql'\nquery Viewer {\n    viewer {\n        ...Partial\n    }\n}\n```\n\n#### `.tsx`es generated in `cacheDir` (`.cache`) throw TypeScript errors of wrong import paths\n\nIt's not a bug. Please exclude `cacheDir` from your TypeScript compilation. The files in `cacheDir` are only intermediates, which will speed your next execution.\n\n```\nYour GraphQL documents -\u003e (call GraphQL code generator API *1) -\u003e .tsx *2 -\u003e (call TypeScript to distribute declarations *3) -\u003e .d.ts\n```\n\nYou're seeing the `*2`. It's used to skip `*1` and `*3`, and recodnized as generated implementations, which graphql-let/loader returns, for example.\n\n## Contribution\n\n-   **[Create an issue](https://github.com/piglovesyou/graphql-let/issues/new)**\n    if you have ideas, find a bug, or anything.\n-   **Creating a PR** is always welcome!\n    -   Running `npm run prepublishOnly` locally will get your local development\n        ready.\n    -   Adding tests is preferable, but not necessary. Maybe someone else will\n        fill it.\n-   [We have a chronic accumulation of dependabot PRs](https://github.com/piglovesyou/graphql-let/pulls/app%2Fdependabot). Please help us fix these version conflicts by cloning the dependabot branches.\n\n## License\n\nApache License Version 2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpiglovesyou%2Fgraphql-let","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpiglovesyou%2Fgraphql-let","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpiglovesyou%2Fgraphql-let/lists"}