Skip to content

Commit

Permalink
Improve identity template literal tag docs (#254)
Browse files Browse the repository at this point in the history
This PR improves the identity template literal tag docs:

- Tweaked the text from saying tags are “always” used in Apollo projects to “often”, as there are situations  where tags are not necessary like when making server side queries via `node-fetch` that come up in real world projects.
- Replaced the manual copy paste fake tag code with the suggestion to use [`fake-tag`](https://npm.im/fake-tag). This utility is easy to install and use and has tests covering Interpolations and escapes. It has been reasonably battle tested.
- Mentioned the `/* GraphQL */` comment tag enhancement issue (#224).

See earlier discussion: #224 (comment)

Co-authored-by: Jon Wong <j@jnwng.com>
  • Loading branch information
jaydenseric and jnwng committed Dec 27, 2019
1 parent 4f83993 commit a1a7517
Show file tree
Hide file tree
Showing 2 changed files with 11 additions and 16 deletions.
2 changes: 2 additions & 0 deletions CHANGELOG.md
Expand Up @@ -2,6 +2,8 @@

### vNEXT

- Improve identity template literal tag docs. [PR #254](https://github.com/apollographql/eslint-plugin-graphql/pull/254) by [Jayden Seric](https://github.com/jaydenseric).

### v3.1.1

- Update the `required-fields` rule to handle inline fragments without field ancestors. [PR #240](https://github.com/apollographql/eslint-plugin-graphql/pull/240) by [Henry Q. Dineen](https://github.com/henryqdineen)
Expand Down
25 changes: 9 additions & 16 deletions README.md
Expand Up @@ -56,28 +56,21 @@ There's an example on how to use a `.graphqlconfig` file further down.

### Identity template literal tag

This plugin relies on GraphQL queries being prefixed with a special tag. In Relay and Apollo, this is always done, but other clients often take query strings without a tag. In this case, you can define an identity tag that doesn't do anything except for tell the linter this is a GraphQL query:
This plugin relies on GraphQL queries being prefixed with a special tag. In Relay and Apollo this is done often, but some other clients take query strings without a tag. In this case, [`fake-tag`](https://npm.im/fake-tag) can be used to define an identity tag that doesn't do anything except for tell the linter this is a GraphQL query:

```js
global.gql = (literals, ...substitutions) => {
let result = "";
import gql from "fake-tag";

// run the loop only for the substitution count
for (let i = 0; i < substitutions.length; i++) {
result += literals[i];
result += substitutions[i];
const QUERY_VIEWER_NAME = gql`
query ViewerName {
viewer {
name
}

// add the last literal
result += literals[literals.length - 1];

return result;
}
}
`;
```

Code snippet taken from: <https://leanpub.com/understandinges6/read#leanpub-auto-multiline-strings>

Note: The linter rule could be extended to identify calls to various specific APIs to eliminate the need for a template literal tag, but this might just make the implementation a lot more complex for little benefit.
Fake tags won’t be necessary [once `/* GraphQL */` comment tags are supported](https://github.com/apollographql/eslint-plugin-graphql/issues/224).

### GraphQL literal files

Expand Down

0 comments on commit a1a7517

Please sign in to comment.