Getting Started With Relay

We know what you are thinking, what the heck is Relay and why do I care? Arenʼt there enough frameworks already?

Relay is a framework meant to complement both GraphQL and React. If you think about it, a lot of developer productivity goes towards fetching data. React is a nice way to think about the UI as separate components.

Each component has clean cut separation of concerns. The problem at hand is how do you feed it data? One can dream up any push and pull solution to do this. This may involve Ajax slapped with a framework or two. Or, you could bridge client-side components with Relay. If you are already knee deep in React and GraphQL, Relay will offer a nice way to bridge the two.

In this take, letʼs walk through a quick way to get started with Relay. I will start from scratch and put in place a solution with Relay. We will cover each step of the way, so feel free to follow along.

So letʼs get this party started. I mentioned Relay is the bridge between React and GraphQL to fetch data. Turns out, there is a starter kit to get you off the ground.

First, clone the repo into the local dev environment with git clone. If you are not familiar with git, there is good documentation out there.

Once cloned, the first thing is to install dependencies:

npm install

Phew, with 424 dependencies per the time of this writing. We are ready to update-schema:

npm run update - schema

Relay has to keep track of schema changes in GraphQL. This is one way it keeps an eye on the schema and bridges the data.

At the end, letʼs start the web server.

npm start

If all goes well with your local machine, you should see this nice little demo:

For those following along, here is the git commit. So far, we have the Relay starter kit working.

The next step is to create our schema.

For the schema, I am thinking of a list of ferocious cats. Inside data\schema draw up an image field in the widgetType:

image: {

    type: GraphQLString,

    description: 'An image of a cat'

}

GraphQL is a declarative, strong-typed and product-centric query language. Notice the GraphQLString type for the image. Feel free to leave the rest of the widget intact. As far as fields, we still need an id, name and an image.

It is time to fill up the GraphQL with data. Go to data\database and fill this GraphQL schema with new data:

const imageUrl = [

    'http://bit.ly/28WswxC',

    'http://bit.ly/28VXOoZ',

    'http://bit.ly/2919Fo6'

];



var widgets = ['Panther', 'Cougar', 'Lion'].map((name, i) = & gt; {

    var widget = new Widget();



    widget.name = name;

    widget.id = `${i}`;

    widget.image = imageUrl[i];



    return widget;

});

This grabs the list of cat names and iterates with a map. Gives it an id based on the index i and a URL that comes from imageUrl. The imageUrl is an array with a list of images for each cat.

We are ready to test the new schema changes, type this up in the console:

npm run update - schema

npm start

With data and schema changes complete, feel free to check out the commit. Since I practice extreme programming, clean up unnecessary code in another commit.

For the front end, Relay creates a bridge to React components through a container. A container defines a viewer with a GraphQL declarative query to feed it data. Below is what the container looks like:

Relay.createContainer(App, {

    fragments: {

        viewer: () = & gt;Relay.QL `

fragment on User

widgets(first: 10)

edges

node

id,

name,

image

}

}

}

}

`

    }

});

Here Relay.QL defines a GraphQL query on what data to expect. If you glance at it, notice we are only interested in the first 10 widgets. It needs to know what to return, so tell it we want the id, name, and image for each ferocious cat. The rest gets fetched by Relay, no funky XHR coding is necessary.

With the data fetching complete, itʼs time to wire up React. I have an App React component ready to make use of this data. So letʼs build the list of cats:

<h1>Ferocious Cats</h1>

<ul>

    <ul>{this.props.viewer.widgets.edges.map(edge =>

        <li>

            <h3>{edge.node.name}</h3>

            <img alt="{edge.node.name}" src="{edge.node.image}" 

                       width="200px" />

        </li>

    </ul>

</ul>

)}

This leverages the JSX syntax. As shown, take the results from the Relay container and use it. Relay makes this complex data fetching seamless.

The front end is complete, feel free to check out the commit from this little hackathon.

With both back end and front end complete. Itʼs time to fire up the demo, this time just start the server:

npm start

Youʼll notice webpack picks up all the changes and bundles them up. At the end, you should see this little demo:

This wraps up the demo. If you open up the network tab in the browser, notice the graphql Ajax request that gets the data. All this happens behind the scenes for you with no extra coding. If you examine the JSON it gets back, all the data you need to render each component is in this request.

I encourage you to leave the dev tools open in the browser. Go through the HTML that gets rendered. Check out the rest of the requests in the network tab.

As shown, Relay leverages React and GraphQL and brings it all together. It gives you a nice layer of abstraction on top that bridges these two. Facebook open sourced Relay circa August 2015 and it is gaining traction.

I hope this guide gives you what you need to get started with Relay.