The Graphcool Framework: A path to instant GraphQL greatness

Graphcool is a great service. We got a chance to put it through the paces on a recent React Native project, and I was impressed. Graphcool began as a GraphQL Backend-as-a-Service and recently released the (open source!) Graphcool Framework. The Graphcool Framework manages to bring an instant GraphQL backend to your local machine with minimal effort on your part. All you have to do is define the schema.

Running the Graphcool Framework locally enables you to easily manage your project and develop apps the way you’d develop anything else — using your favorite editor and git. When you’re ready to deploy, you can host the API yourself or use Graphcool’s hosted infrastructure.

Let’s take a look and see how easy it is to get going.

Setup

1. Install the graphcool cli: . 2.Initialize a new Graphcool API. For smaller projects, it’s fine to use a subfolder in the main project. For larger projects, or projects that may have many different front-end clients, you’re better off using a separate git repo. In this example, we’re going to keep things separate.

When it’s done, initialize a new git repo & commit the changes.

Running Locally

Running Graphcool locally is optional, but doing so enables you to work anywhere: 🚂 ✈️ ⛺️ ⛱.

  1. Make sure you have Docker installed. Here’s a link for Mac. Other platforms are available under the “Get Docker” menu. If you don’t have Docker yet, you’ll see this when trying to start your local environment:
Oops, no Docker.

2. Start your local Graphcool service using . This will download a few different Docker images, so make sure you’re not tethering to your phone.

Installing local Graphcool Docker containers

3. Deploy those changes to the container using . Doing this the first time will prompt for your default target (typically ).

It will also prompt you for the location to deploy. For staging & production you’ll likely choose one of the “Shared Cluster” options, but we’re going to choose “local”.

If asked for the service name, just keep the default (api in our case).

A successful Graphcool deploy!

Not only did Graphcool Framework configure everything for us, we also have a new type ready for use. Graphcool uses this schema information to build us a CRUD API automatically.

Testing it out

If you’re not familiar with GraphiQL, it is an in-browser IDE for GraphQL that allows you to inspect your schema and try out queries, mutations, and subscriptions. GraphiQL is built-in to Graphcool (it’s is called the playground internally).

Since GraphiQL knows about the entire schema, you get some pretty great autocomplete features. To open it up, just use .

Let’s make sure we can properly query :

And create them:

If we go back to our query, we can see that things have persisted and we’re good to go.

If you want to see detailed information about your schema, just use the green schema tab on the right of the screen.

We get a lot for free!

Custom Functions

Automatic CRUD operations are great, but custom functions are some next level awesomeness. Graphcool has 3 types of custom functions available.

  • Hooks
  • Subscriptions
  • Resolvers

Let’s check our custom resolver function that was added by :

Testing out the default hello function

Define a custom function

Let’s assume for some reason, we want to give users a default if one is not provided. We can leverage Graphcool’s hook for that.

Add the definition to our file. We’ll tell Graphcool to run the function before a is created:

If you want to remove sensitive information from the return payload, there’s a corresponding type.

Create the function

  • First, create the function to run. Make sure and name the file using the same path you specified in .

Deploying our changes

For your local Graphcool server to reflect these changes, just run again.

Running our mutation again, shows that the user does get a properly set to party like its 1999.

Webhooks

There two ways to handle custom functions using Graphcool. We’ve already used the first, which runs a function local to the server. The other option (which is great for integrating with existing systems) is to use a webhook.

First, we define the webhook in just like we defined .

For this example, I’ve set up a demo Heroku app that returns some mock data.

If you want to set up a local server to test the webhook, here’s the express code we’re using:

When testing out webhooks of any kind, it’s a good idea to use ngrok to tunnel a publicly accessible https url back to your local machine.

Finally, create the schema file at the path you specified in above. There’s no need to add a JavaScript file since we’re calling a webhook instead.

Run and let’s try it out.

There’s one slight gotcha to keep in mind. The response from your existing server needs to be wrapped in a top level key to be recognized by GraphQL.

Staging & Production Environments

We’re off and running with a dev environment, but what about and ? Turns out that’s easy! Just use the (or ) option available to most cli commands.

Creating a new staging environment

There’s a Graphcool in your CI!

In a follow up article, we’ll take a look at how to run Graphcool inside a CI service to enable true E2E testing of a React Native app.

The good news for now is that syncing up Graphcool staging deploys with your CI process is pretty painless. It works like this:

  1. run tests

Bonus

By the way, if you have an error in your functions along the way, you get wonderful little error messages when trying to deploy. This combined with makes debugging issues pretty painless.

Nice, informative error messages

Recommended links for additional reading:

graphcool-lib examples
Permission rules examples
Wrapping an existing REST API
Graphcool Reference Docs

Update 11/17/17: Removed as it’s not required for hooks.

More about:

Chris Ball

Chris is CTO at Echobind, a full-service agency specializing in custom web and mobile apps. When he’s not helping developers grow or creating amazing things for clients, you’re likely to find him playing music, cycling, or camping.