Merge pull request apollographql#3373 from detrohutt/patch-2

doc(recipes/babel): add inline-import-graphql-ast

Author: Sashko Stubailo

docs/source/recipes/babel.md

@@ -9,6 +9,8 @@ To avoid this runtime overhead, you can precompile your queries created with `gr
 1. Using [babel-plugin-graphql-tag](#using-babel-plugin-graphql-tag)
 2. Using [graphql-tag.macro](#using-graphql-tagmacro)
 
+If you prefer to keep your GraphQL code in separate files (`.graphql` or `.gql`) you can use [babel-plugin-inline-import-graphql-ast](https://github.com/detrohutt/babel-plugin-inline-import-graphql-ast). 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.
@@ -69,9 +71,52 @@ const query = gql`
 `;
 ```
 
+## Using babel-plugin-graphql-tag
+
+Install the plugin in your dev dependencies:
+
+```
+# with npm
+npm install --save-dev babel-plugin-inline-import-graphql-ast
+
+# or with yarn
+yarn add --dev babel-plugin-inline-import-graphql-ast
+```
+
+Then add the plugin in your `.babelrc` configuration file:
+
+```
+{
+  "plugins": [
+    "inline-import-graphql-ast"
+  ]
+}
+```
+
+Now any `import` statements importing from a GraphQL file type will return a ready-to-use GraphQL DocumentNode object.
+
+```javascript
+import React, { Component } from 'react';
+import { graphql } from 'react-apollo';
+import myImportedQuery from './productsQuery.graphql';
+// or for files with multiple operations:
+// import { query1, query2 } from './queries.graphql';
+
+class QueryingComponent extends Component {
+  render() {
+    if (this.props.data.loading) return <h3>Loading...</h3>;
+    return <div>{`This is my data: ${this.props.data.queryName}`}</div>;
+  }
+}
+
+export default graphql(myImportedQuery)(QueryingComponent);
+```
+
 ## Fragments
 
-Both approaches work with fragments. 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:
+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:
 
 ```js
 import gql from 'graphql-tag';
@@ -97,3 +142,5 @@ const query = gql`
   ${fragments.hello}
 `;
 ```
+
+With `babel-plugin-inline-import-graphql-ast`, 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 GraphQL `#import` syntax. See the [README](https://github.com/detrohutt/babel-plugin-inline-import-graphql-ast) for more information.