Compiling queries with Transpilers
If you prefer co-locating your GraphQL queries in your Javascript files, you typically use the graphql-tag library to write them. That requires to process the query strings into a GraphQL AST, which will add to the startup time of your application, especially if you have many queries.
To avoid this runtime overhead, you can precompile your queries created with graphql-tag
using transpilers like Babel and SWC . Here are possible ways you can do this:
Using babel-plugin-graphql-tag
Using graphql-tag-swc-plugin
Using graphql-tag.macro
Using ts-transform-graphql-tag for TypeScript
If you prefer to keep your GraphQL code in separate files (.graphql
or .gql
) you can use babel-plugin-import-graphql . This plugin still uses graphql-tag
under the hood, but transparently. You simply import
your operations/fragments as if each were an export from your GraphQL file. This carries the same precompilation benefits as the above approaches.
Using babel-plugin-graphql-tag
This approach will allow you to use the graphql-tag
library as usual, and when processing the files with this babel plugin, the calls to that library will be replaced by the precompiled result.
Install the plugin in your dev dependencies:
1# with npm
2npm install --save-dev babel-plugin-graphql-tag
3
4# or with yarn
5yarn add --dev babel-plugin-graphql-tag
Then add the plugin in your .babelrc
configuration file:
1{
2 "plugins": [
3 "graphql-tag"
4 ]
5}
And that's it! All the usages of import gql from 'graphql-tag'
will be removed, and the calls to gql
will be replaced by the compiled version.
Using graphql-tag-swc-plugin
This plugin is the same as babel-plugin-graphql-tag but for swc , a fast rust based babel alternative.
Install the plugin in your dev dependencies:
1# with npm
2npm install --save-dev graphql-tag-swc-plugin
3
4# or with yarn
5yarn add --dev graphql-tag-swc-plugin
Then add the plugin in your .swcrc
configuration file:
1{
2 jsc: {
3 experimental: {
4 plugins: [
5 ["graphql-tag-swc-plugin",
6 {
7 importSources: ["@apollo/client", "graphql-tag"],
8 gqlTagIdentifiers: ["gql"]
9 },
10 ],
11 ],
12 },
13 },
14}
For more information on configuration and features, please checkout the graphql-tag-swc-plugin
documentation.
Using graphql-tag.macro
This approach is a bit more explicit, since you change all your usages of graphql-tag
for graphql-tag.macro
, which exports a gql
function that you can use the same way as the original one. This macro requires the babel-macros plugin, which will do the same as the previous approach but only on the calls that come from the macro import, leaving regular calls to the graphql-tag
library untouched.
Why would you prefer this approach? Mainly because it requires less configuration (babel-macros
works with all kinds of macros, so if you already had it installed you don't have to do anything else), and also because of the explicitness. You can read more about the rationale of using babel-macros
in this blog post .
To use it, provided that you already have babel-macros installed and configured , you just need to change this:
1import gql from 'graphql-tag';
2
3const query = gql`
4 query HelloWorld {
5 hello {
6 world
7 }
8 }
9`;
to this:
1import gql from 'graphql-tag.macro'; // <-- Use the macro
2
3const query = gql`
4 query HelloWorld {
5 hello {
6 world
7 }
8 }
9`;
Using babel-plugin-import-graphql
Install the plugin in your dev dependencies:
1# with npm
2npm install --save-dev babel-plugin-import-graphql
3
4# or with yarn
5yarn add --dev babel-plugin-import-graphql
Then add the plugin in your .babelrc
configuration file:
1{
2 "plugins": [
3 "import-graphql"
4 ]
5}
Now any import
statements importing from a GraphQL file type will return a ready-to-use GraphQL DocumentNode object.
1import React, { Component } from 'react';
2import { graphql } from '@apollo/react-hoc';
3import myImportedQuery from './productsQuery.graphql';
4// or for files with multiple operations:
5// import { query1, query2 } from './queries.graphql';
6
7class QueryingComponent extends Component {
8 render() {
9 if (this.props.data.loading) return <h3>Loading...</h3>;
10 return <div>{`This is my data: ${this.props.data.queryName}`}</div>;
11 }
12}
13
14export default graphql(myImportedQuery)(QueryingComponent);
Using ts-transform-graphql-tag
Install the plugin in your dev dependencies:
1# with npm
2npm install --save-dev ts-transform-graphql-tag
3
4# or with yarn
5yarn add --dev ts-transform-graphql-tag
Read the ts-transform-graphql-tag documentation for Webpack or FuseBox usage instructions.
Fragments
All of these approaches support the use of fragments.
For the first two approaches, you can have fragments defined in a different call to gql
(either in the same file or in a different one). You can then include them into the main query using interpolation, like this:
1import gql from 'graphql-tag';
2// or import gql from 'graphql-tag.macro';
3
4const fragments = {
5 hello: gql`
6 fragment HelloStuff on Hello {
7 universe
8 galaxy
9 }
10 `
11};
12
13const query = gql`
14 query HelloWorld {
15 hello {
16 world
17 ...HelloStuff
18 }
19 }
20
21 ${fragments.hello}
22`;
With babel-plugin-import-graphql
, you can just include your fragment in your GraphQL file along-side whatever uses it, or even import it from a separate file using the #import
syntax. See the README for more information.