@grafoo/babel-plugin

Grafoo Babel Plugin

A premise Grafoo takes is that it should be able to extract an unique identifier from every node on the queries you write. It can be a GraphQL ID field, or more fields that together can form one (eg: an incremental integer and the GraphQL meta field __typename). It is @grafoo/babel-plugin's responsibility to insert those fields on your queries automatically. If you have already used Apollo this should be very familiar to you, as our idFields configuration has the same pourpose of Apollo Cache's dataIdFromObject: to normalize your data.

Install

$ npm i @grafoo/core && npm i -D @grafoo/babel-plugin

Configuration

To configure the plugin is required to specify the option idFields, an array of strings that represent the fields that Grafoo will use to build object identifiers. The option schema, is a path to a GraphQL schema in your file system relative to the root of your project, if not specified the plugin will look for the schema in the root of your project:

{
  "plugins": [
    [
      "@grafoo/babel-plugin",
      {
        "schema": "schema.graphql",
        "idFields": ["id"],
        "generateIds": false
      }
    ]
  ]
}

How to get my schema?

The recommendation for now is to use the get-graphql-schema, by Prisma. In the near future we are planning to introduce a schemaUrl option to this plugin so that this step won't be required anymore.

Transformations

@grafoo/babel-plugin transforms your code in three ways:

• Template tag literals using the default export from submodule @grafoo/core/tag will be compiled to a special object that will assist the client on the caching process.
• Imports from submodule @grafoo/core/tag statements will be removed.
• idFields will be inserted automatically on client instantiation.

  import createClient from "@grafoo/core";
- import graphql from "@grafoo/core/tag";

  function fetchQuery(query, variables) {
    const init = {
      method: "POST",
      body: JSON.stringify({ query, variables }),
      headers: {
        "content-type": "application/json"
      }
    };

    return fetch("http://some.graphql.api", init).then(res => res.json());
  }

- const client = createClient(fetchQuery);
+ const client = createClient(fetchQuery, {
+   idFields: ["id"]
+ });

- const USER_QUERY = graphql`
-   query($id: ID!) {
-     user(id: $id) {
-       name
-       posts {
-         title
-       }
-     }
-   }
- `;
+ const USER_QUERY = {
+   id: "d4b567cd2a8891aa4cd1840f1a53002e", // only if option "generateIds" is true
+   query: "query($id: ID!) { user(id: $id) { id name posts { id title } } }",
+   paths: {
+     "user(id:$id){id name posts{id title}}": {
+       name: "user"
+       args: ["id"]
+     }
+   }
+ };

LICENSE

MIT