Skip to content

Commit 9b719a7

Browse files
GreenGremlinJonathan Felchlinhwillson
authored
Cleaning up the README a bit (#246)
* Cleaning up the README a bit * Slight wording/formatting tweaks Co-authored-by: Jonathan Felchlin <[email protected]> Co-authored-by: hwillson <[email protected]>
1 parent 6d001fb commit 9b719a7

File tree

1 file changed

+130
-68
lines changed

1 file changed

+130
-68
lines changed

‎README.md‎

Lines changed: 130 additions & 68 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ Helpful utilities for parsing GraphQL queries. Includes:
1212

1313
### gql
1414

15-
This is a template literal tag you can use to concisely write a GraphQL query that is parsed into the standard GraphQL AST:
15+
The `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.
1616

1717
```js
1818
import gql from 'graphql-tag';
@@ -25,34 +25,68 @@ const query = gql`
2525
}
2626
}
2727
`
28+
```
29+
30+
The above query now contains the following syntax tree.
31+
32+
```js
33+
{
34+
"kind": "Document",
35+
"definitions": [
36+
{
37+
"kind": "OperationDefinition",
38+
"operation": "query",
39+
"name": null,
40+
"variableDefinitions": null,
41+
"directives": [],
42+
"selectionSet": {
43+
"kind": "SelectionSet",
44+
"selections": [
45+
{
46+
"kind": "Field",
47+
"alias": null,
48+
"name": {
49+
"kind": "Name",
50+
"value": "user",
51+
...
52+
}
53+
}
54+
]
55+
}
56+
}
57+
]
58+
}
59+
```
60+
61+
#### Fragments
62+
63+
The `gql` tag can also be used to define reusable fragments, which can easily be added to queries or other fragments.
64+
65+
```js
66+
import gql from 'graphql-tag';
2867

29-
// query is now a GraphQL syntax tree object
30-
console.log(query);
31-
32-
// {
33-
// "kind": "Document",
34-
// "definitions": [
35-
// {
36-
// "kind": "OperationDefinition",
37-
// "operation": "query",
38-
// "name": null,
39-
// "variableDefinitions": null,
40-
// "directives": [],
41-
// "selectionSet": {
42-
// "kind": "SelectionSet",
43-
// "selections": [
44-
// {
45-
// "kind": "Field",
46-
// "alias": null,
47-
// "name": {
48-
// "kind": "Name",
49-
// "value": "user",
50-
// ...
68+
const userFragment = gql`
69+
fragment User_user on User {
70+
firstName
71+
lastName
72+
}
73+
`
5174
```
5275

53-
You can easily explore GraphQL ASTs on [astexplorer.net](https://astexplorer.net/#/drYr8X1rnP/1).
76+
The above `userFragment` document can be embedded in another document using a template literal placeholder.
77+
78+
```js
79+
const query = gql`
80+
{
81+
user(id: 5) {
82+
...User_user
83+
}
84+
}
85+
${userFragment}
86+
`
87+
```
5488

55-
This package is the way to pass queries into [Apollo Client](https://github.com/apollographql/apollo-client). If you're building a GraphQL client, you can use it too!
89+
**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._
5690

5791
#### Why use this?
5892

@@ -64,78 +98,100 @@ That's where this package comes in - it lets you write your queries with [ES2015
6498

6599
This 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.
66100

67-
### Babel preprocessing
68101

69-
GraphQL queries can be compiled at build time using [babel-plugin-graphql-tag](https://github.com/gajus/babel-plugin-graphql-tag). Pre-compiling queries decreases the script initialization time and reduces the bundle size by potentially removing the need for `graphql-tag` at runtime.
102+
### Importing graphQL files
70103

71-
#### TypeScript
72-
Try this custom transformer to pre-compile your GraphQL queries in TypeScript: [ts-transform-graphql-tag](https://github.com/firede/ts-transform-graphql-tag).
104+
_To add support for importing `.graphql`/`.gql` files, see [Webpack loading and preprocessing](#webpack-loading-and-preprocessing) below._
73105

74-
#### React Native, Next.js
106+
Given a file `MyQuery.graphql`
75107

76-
Additionally, in certain situations, preprocessing queries via the webpack loader is not possible. [babel-plugin-import-graphql](https://www.npmjs.com/package/babel-plugin-import-graphql) will allow one to import graphql files directly into your JavaScript by preprocessing GraphQL queries into ASTs at compile-time.
108+
```graphql
109+
query MyQuery {
110+
...
111+
}
112+
```
77113

78-
E.g.:
79-
```javascript
80-
import myImportedQuery from './productsQuery.graphql'
114+
If 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.
81115

82-
class ProductsPage extends React.Component {
116+
```graphql
117+
import MyQuery from 'query.graphql'
118+
```
119+
120+
#### Importing queries by name
121+
122+
You can also import query and fragment documents by name.
123+
124+
```graphql
125+
query MyQuery1 {
126+
...
127+
}
128+
129+
query MyQuery2 {
83130
...
84131
}
85132
```
86133

87-
#### Create-React-App
134+
And in your JavaScript:
88135

89-
`[email protected]` does support the ability to preprocess queries using [evenchange4/graphql.macro](https://github.com/evenchange4/graphql.macro).
136+
```javascript
137+
import { MyQuery1, MyQuery2 } from 'query.graphql'
138+
```
90139

91-
If you're using an older version of `create-react-app`, check out [react-app-rewire-inline-import-graphql-ast](https://www.npmjs.com/package/react-app-rewire-inline-import-graphql-ast) to preprocess queries without needing to eject.
140+
### Preprocessing queries and fragments
92141

93-
### Webpack preprocessing with `graphql-tag/loader`
142+
Preprocessing GraphQL queries and fragments into ASTs at build time can greatly improve load times.
94143

95-
This package also includes a [webpack loader](https://webpack.js.org/concepts/loaders). There are many benefits over this approach, which saves GraphQL ASTs processing time on client-side and enable queries to be separated from script over `.graphql` files.
144+
#### Babel preprocessing
96145

97-
```js
98-
loaders: [
99-
{
100-
test: /\.(graphql|gql)$/,
101-
exclude: /node_modules/,
102-
loader: 'graphql-tag/loader'
103-
}
104-
]
105-
```
146+
GraphQL 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.
106147

107-
then:
148+
#### TypeScript preprocessing
108149

109-
```js
110-
import query from './query.graphql';
150+
Try this custom transformer to pre-compile your GraphQL queries in TypeScript: [ts-transform-graphql-tag](https://github.com/firede/ts-transform-graphql-tag).
111151

112-
console.log(query);
113-
// {
114-
// "kind": "Document",
115-
// ...
116-
```
152+
#### React Native and Next.js preprocessing
117153

118-
Testing 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).
154+
Preprocessing 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.
119155

120-
#### Support for multiple operations
156+
E.g.:
121157

122-
With the webpack loader, you can also import operations by name:
158+
```javascript
159+
import myImportedQuery from './productsQuery.graphql'
123160

124-
In a file called `query.gql`:
125-
```graphql
126-
query MyQuery1 {
161+
class ProductsPage extends React.Component {
127162
...
128163
}
164+
```
129165

130-
query MyQuery2 {
166+
#### Webpack loading and preprocessing
167+
168+
Using 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.
169+
170+
_**Example webpack configuration**_
171+
172+
```js
173+
{
174+
...
175+
loaders: [
176+
{
177+
test: /\.(graphql|gql)$/,
178+
exclude: /node_modules/,
179+
loader: 'graphql-tag/loader'
180+
}
181+
],
131182
...
132183
}
133184
```
134185

135-
And in your JavaScript:
136-
```javascript
137-
import { MyQuery1, MyQuery2 } from 'query.gql'
138-
```
186+
#### Create React App
187+
188+
Preprocessing GraphQL imports is supported in **create-react-app** >= v2 using [evenchange4/graphql.macro](https://github.com/evenchange4/graphql.macro).
189+
190+
For **create-react-app** < 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).
191+
192+
#### Testing
193+
194+
Testing 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).
139195

140196
### Warnings
141197

@@ -152,13 +208,19 @@ disableFragmentWarnings()
152208
This package exports an `experimentalFragmentVariables` flag that allows you to use experimental support for [parameterized fragments](https://github.com/facebook/graphql/issues/204).
153209

154210
You can enable / disable this with:
211+
155212
```js
156213
import { enableExperimentalFragmentVariables, disableExperimentalFragmentVariables } from 'graphql-tag';
157214
```
158215

159216
Enabling this feature allows you declare documents of the form
217+
160218
```graphql
161219
fragment SomeFragment ($arg: String!) on SomeType {
162220
someField
163221
}
164222
```
223+
224+
### Resources
225+
226+
You can easily generate and explore a GraphQL AST on [astexplorer.net](https://astexplorer.net/#/drYr8X1rnP/1).

0 commit comments

Comments
 (0)