babel-plugin-blade

babel-plugin-blade ⛸️

inline GraphQL

The problem

This is a plugin for solving the double declaration problem in GraphQL queries.

What is the "double declaration problem"? Simply it is the bad developer experience of first having to declare what you want to query in the GraphQL template string, and then again when you are using the data in your application. Ommissions are confusing to debug and overfetching due to stale queries is also a problem.

This solution

This plugin gives you createQuery and createFragment functions to wrap around the root data property of whatever GraphQL client you use. It then tracks everything you do with data and generates a GraphQL query based on your usage.

This is accomplished by hooking in to Babel to building up a tree of downstream dependencies on data. For query arguments, the arguments are stripped and an alias generated for that specific query.

Table of Contents

• Installation
• Usage
  • first usage style
• Configure with Babel
  • Via .babelrc (Recommended)
  • Via CLI
  • Via Node API
• Use with babel-plugin-macros
  • APIs not supported by the macro
• Caveats
• Examples
• Inspiration
• Other Solutions
• LICENSE

Installation

This module is distributed via npm which is bundled with node and should be installed as one of your project's devDependencies:

npm install --save-dev babel-plugin-blade

Usage

Add it to your babel config.

first usage style

Before:

import {Connect, query} from 'urql'

const movieQuery = createQuery()
const Movie = ({id, onClose}) => (
  <div>
    <Connect
      query={query(movieQuery, {id: id})}
      children={({data}) => {
        const DATA = movieQuery(data)
        return (
          <div>
            <h2>{DATA.movie.gorilla}</h2>
            <p>{DATA.movie.monkey}</p>
            <p>{DATA.chimp}</p>
          </div>
        )
      }}
    />
  </div>
)

After:

import {Connect, query} from 'urql'

const Movie = ({id, onClose}) => (
  <div>
    <Connect
      query={query(
        `
query movieQuery{
  movie {
    gorilla
    monkey
  }
  chimp
}`,
        {id: id},
      )}
      children={({data}) => {
        const DATA = data
        return (
          <div>
            <h2>{DATA.movie.gorilla}</h2>
            <p>{DATA.movie.monkey}</p>
            <p>{DATA.chimp}</p>
          </div>
        )
      }}
    />
  </div>
)

For more usage examples please see our full API docs here.

Configure with Babel

Via .babelrc (Recommended)

.babelrc

{
  "plugins": ["blade"]
}

Via CLI

babel --plugins blade script.js

Via Node API

require('babel-core').transform('code', {
  plugins: ['blade'],
})

Use with babel-plugin-macros

Once you've configured babel-plugin-macros you can import/require the blade macro at babel-plugin-blade/macro. For example:

import { createQuery } from 'babel-plugin-blade/macro'
import {Connect, query} from 'urql'

const movieQuery = createQuery()
const Movie = () => (
  <div>
    <Connect
      query={query(movieQuery)}
      children={({data}) => {
        const DATA = movieQuery(data)
        return (
          <div>
            <h2>{DATA.movie.gorilla}</h2>
            <p>{DATA.movie.monkey}</p>
            <p>{DATA.chimp}</p>
          </div>
        )
      }}
    />
  </div>
)

      ↓ ↓ ↓ ↓ ↓ ↓

import { Connect, query } from 'urql';

const Movie = () => <div>
    <Connect query={query(`
query movieQuery{
  movie {
    gorilla
    monkey
  }
  chimp
}`)} children={({ data }) => {
    const DATA = data;
    return <div>
            <h2>{DATA.movie.gorilla}</h2>
            <p>{DATA.movie.monkey}</p>
            <p>{DATA.chimp}</p>
          </div>;
  }} />
  </div>;

APIs not supported by the macro

• none! the macro has full coverage of the babel-plugin

You could also use blade.macro if you'd prefer to type less 😀

Caveats

This plugin is still very new, please don't use in production unless you are willing to help me out on fixing any bugs you find!

Examples

• To be written

Inspiration

This is based on babel-plugin-macros.

Other Solutions

I'm not aware of any, if you are please make a pull request and add it here!

LICENSE

MIT