AWS also offers an API Gateway, allowing developers to invoke AWS Lambda functions, which provides enhanced security and performance features like rate limiting. But even with the API Gateway, you have to coordinate these microservices, as your client applications likely each have unique data needs. Data might need to be transformed, filtered, or combined before it is returned to the client.

These orchestration tasks can reduce your productivity and take time and effort away from solving the business problem your application is trying to solve.

Apollo GraphQL is an API orchestration layer that helps teams ship new features faster and more independently by composing any number of underlying services and data sources into a single endpoint. This allows clients on-demand access to precisely what the experience needs, regardless of the source of that data.

This article will teach you how to orchestrate AWS Lambda functions using Apollo GraphQL. Specifically, here’s what we will cover:

• GraphQL Primer

• Tutorial Overview

• Prerequisites

• Section 1: Create the AWS Resources

• Section 2: Create an Apollo Connector

• Section 3: How to Use Apollo Sandbox

• Summary

GraphQL Primer

For those unfamiliar with GraphQL, here’s a primer that offers some background on the challenges GraphQL addresses and how data is typically managed through REST APIs in GraphQL before the emergence of Apollo Connectors. If you’re familiar with GraphQL, feel free to skip this section.

GraphQL is a query language for APIs. This query language and corresponding runtime enable clients to specify exactly the data they require, minimizing over-fetching and under-fetching.

In contrast to REST, which necessitates multiple endpoints for various data requirements, GraphQL streamlines queries into a single request, enhancing performance and reducing network latency.

GraphQL also uses a strongly typed schema. This improves API documentation and makes validation, early error detection, and immersive developer tooling easy.

To illustrate the difference between REST APIs and GraphQL, consider the following REST API call: /user/123

Response:

{
  "id": 123,
  "name": "Alice Johnson",
  "email": "alice@example.com",
  "phone": "555-1234",
  "address": {
    "street": "123 Main St",
    "city": "Springfield",
    "state": "IL",
    "zip": "62704"
  },
  "createdAt": "2022-01-01T12:00:00Z",
  "updatedAt": "2022-05-15T14:30:00Z",
  "isAdmin": false
}

If you were only interested in the name and email, using REST would be a lot of data returned from the network to the client for no reason. Using GraphQL, the GraphQL query to return the name and email would be the following:

query {
  user(id: 123) {
    name
    email
  }
}

The result set is just the data the client needs:

{
  "data": {
    "user": {
      "name": "Alice Johnson",
      "email": "alice@example.com"
    }
  }
}

This is a simple example showing the benefit of not over-fetching data, but GraphQL has many other advantages. One of them is the separation between client and server. Since both parties leverage and respect the GraphQL type schema, both teams can operate more independently with the back end defining where the data resides and the front end only asking for data it needs.

So how does GraphQL know how to populate data for every field in your schema? It does this through resolvers. Resolvers can fetch data from a back-end databases or third-party API such as REST APIs, gRPC, and so on. These functions comprise procedural code compiled and maintained for each field in the schema. Thus, one field can have a resolver that queries a REST API and another can query a gRPC endpoint.

To illustrate resolvers, consider the example above. Let’s add a field, status, that queries a REST API to determine if the user is full-time, part-time, or terminated.

First we have defined our schema as:

type User {
  id: ID!
  name: String!
  email: String!
  status: String!  # Need this from an external REST API
}

type Query {
  user(id: ID!): User
}

The user query in this case will accept a user id and return a type User. The resolver function to support the data fetching resembles the following:

const resolvers = {
  Query: {
    user: async (_, { id }) => {
      // Fetch user details from one REST API
      const userResponse = await fetch(`https://api.company.com/users/${id}`);
      const userData = await userResponse.json();

      // Fetch employee status from another REST API
      const statusResponse = await fetch(`https://api.company.com/employees/${id}/status`);
      const statusData = await statusResponse.json();

      return {
        id: userData.id,
        name: userData.name,
        email: userData.email,
        status: statusData.status, // e.g., "Full-Time", "Part-Time", "Terminated"
      };
    },
  },
};

Notice that not only are there two fetches needed to obtain the information the query requires, but we also need to write procedural code and deploy it.

A better approach would be to declaratively specify to GraphQL where the REST API is located and what data to return. Apollo Connectors is the solution to this challenge, simplifying the process and allowing you to declaratively integrate REST API data without requiring code compilation and maintenance.

Now that you have a general idea of GraphQL and the challenges it addresses, let’s delve into the example we will build out.

Tutorial Overview

In this tutorial, you will create two AWS Lambda functions that return product information, which are described as follows:

Products Request:

POST /2015-03-31/functions/products/invocations

Response:

{
  "statusCode": 200,
  "body": [
    {
      "id": "RANQi6AZkUXCbZ",
      "name": "OG Olive Putter - Blade",
      "description": "The traditional Block in a blade shape is made from a solid block of Olive wood. The head weight is approximately 360 grams with the addition of pure tungsten weights. Paired with a walnut center-line and white accents colors.",
      "image": "https://keynote-strapi-production.up.railway.app/uploads/thumbnail_IMG_9102_3119483fac.png"
    },
    {
      "id": "RANYrWRy876AA5",
      "name": "Butter Knife Olive Putter- Blade",
      "description": "The traditional Block in a extremely thin blade shape (~1\") is made from a solid block of Olive wood. The head weight is approximately 330 grams with the addition of pure tungsten weights.",
      "image": "https://keynote-strapi-production.up.railway.app/uploads/thumbnail_IMG_9104_97c221e79c.png"
    },...

Product-price request:

POST: /2015-03-31/functions/product-price/invocations

Response:

{
  "default_price": 49900,
  "is_active": true,
  "currency": "usd",
  "billing_schema": "per_unit",
  "recurring": {
    "interval": 0,
    "interval_count": 3
  }
}

To expose these two lambda microservices, you need to create API Gateway triggers. This involves either setting up a distinct API Gateway for each lambda or consolidating them under one or a few API Gateway instances with specified routes for each lambda.

Creating a trigger may feel tedious and repetitive in a microservices setup. But there is an alternative available. You could directly invoke those functions via REST using the InvokeFunction permission assigned to an IAM user. This article will show you this method and guide you through function creation, necessary AWS IAM permissions, and configuring the Apollo Connector to invoke the function.

Prerequisites

To follow along in this tutorial, you will need to have a basic understanding of AWS Lambda functions as well as AWS security. You’ll also need access to the following:

• An AWS account with permissions to create IAM Users and Policies

• An Apollo GraphQL account, you can sign up for a free plan here.

We will also use the following tools:

• VS Code: Microsoft VS Code is a free source code editor from Microsoft

• Apollo Rover CLI: Rover is the command-line interface for managing and maintaining graphs

• Apollo Studio: A web-based portal used for managing all aspects of your graph

• Apollo Connectors Mapping Playground: A website that takes a JSON document and helps developers create the selection mapping used with Apollo Connectors

Section 1: Create the AWS Resources

First, let’s configure our AWS environment, starting with security. In our scenario, we will create an IAM User, “ConnectorUser,” with access to an AWS Policy, “ConnectorLambdaPolicy,” with the minimum permissions needed to access the AWS Lambda functions.

Note that you could create user groups and assign permission policies to those groups in a production environment. But for this article, we are reducing the number of administrative steps to focus on the core integration with GraphQL.

Step 1: Create an AWS Policy

To create a policy, navigate to IAM within the AWS Management console, then select “Policies” under Access Management. Click “Create Policy”. This will open the policy editor page, as shown below:

Choose the “Lambda” service and under the Access level select “InvokeFunction” from the Write drop down menu as shown below:

Under the Resources menu, you can choose either All ARNs or a specific option. It's a best practice to be as granular as possible when defining security configurations. In this example, let’s limit our selection to the “us-east-1” region by clicking on the “Specific” option and then “Add ARNs.” Enter “us-east-1” in the resource region and select “Any function name.”

With the policy created, we can assign an IAM user to that policy.

Step 2: Create the IAM User and Attach a Policy

Click on Users under “Access Management” then Create User. Provide a name for the user, “ConnectorUser”.

Next, select “Attach policies directly,” choose the policy we just created, “ConnectorLambdaPolicy,” and click “Create User.”

Step 3: Create AWS Lambda Functions

In your AWS console, create a new NodeJS AWS Lambda function, “products”.

Select “Node.JS” for the runtime then click “Create function”. Once created, paste in the the function code from this Gist.

Repeat this process, creating another function for, “product-price” and use the function code from this Gist.

Section 2: Create an Apollo Connector

In this section, we will install the Apollo Rover CLI tool, create an Apollo Studio free tier account, and clone the Apollo Connectors repository. If you already have an Apollo environment available, you can skip steps 1 and 2.

Step 1: Install Rover

Rover is the command-line interface for managing and maintaining graphs. It also provides a modern hot-reloading experience for developing and running your connectors locally. If you don’t have Rover installed, install it by following the steps here.

Step 2: Create an Apollo Studio Free Tier Account

Apollo Studio is a cloud-based management platform designed to explore, deliver, and collaborate on graphs. If you do not have an Apollo Studio account, create one on a free plan by navigating here.

Step 3: Clone the Apollo Connectors Repository

To help you start your first Apollo Connector, a GitHub repository provides sample connectors and a template script. When run, this script will create all the necessary files and configurations you need to begin.

Go ahead and clone the repository from here.

Note: While not required, I recommended using VS Code, as this repo leverages VS Code-specific settings files.

Step 4: Create a .env File

Before you run the Create Connectors template script, create a .env locally with a user API key from your Apollo Studio. You can create and obtain this key here. Populating this .env file will add this API key to the connector template you create in the next step.

Step 5: Create Your New Connector from a Template

Execute npm start and provide a location to create the connector template. You can use default values for the remaining questions.

This script will create all the necessary files to run a local Apollo GraphQL instance in the specified directory. Load the newly created connector using VS Code or your preferred code editor. You will return to this editor soon, but first, we need to obtain some access keys from AWS.

Step 6: Create an AWS Access Key

Since we connect to AWS using SigV4, we must create an AWS access key and enter the KEY values in the settings.json file. Return to the AWS IAM Console and select the ConnectorUser you created in Step 1. Create a new access key by clicking on “Create access key”.

You will be presented with multiple options as far as where the use of this key will originate. Since we are first running locally, select “Third-party service” and then continue the wizard until you are presented with the key and secret key as shown below:

Add the access key and secret access key to the settings.json file as “AWS_ACCESS_KEY_ID” and “AWS_SECRET_ACCESS_KEY” respectively.

You'll need to reload the window since VS Code only loads these files under the .vscode directory once.

Note: In this step, we saved the key to the settings.json file. While this is acceptable for development, consider saving environment variables in .env files.

Step 7: Configure the Graph

The supergraph.yaml file is used to define all the subgraphs that are part of this federation. Modify the supergraph.yaml file as follows:

federation_version: =2.10.0
subgraphs:
  awsconnector:
    routing_url: http://lambda
    schema:
      file: connector.graphql

Step 8: Configure Apollo Router

Apollo Router supports AWS SigV4 authentication. To configure the connector to use this, modify the router.yaml file and add an authentication section as follows:

authentication:
  connector:
    sources:
      awsconnector.lambda:   # subgraph name . connector source name
        aws_sig_v4:
          default_chain:
            region: "us-east-1"
            service_name: "lambda"

There are other AWS security configuration options available, including using assume role. The full documentation for subgraph authentication is available here.

Step 9: Build the connector

Now that we have configured the environment variables and authentication information, we are ready to build the connector. Open the connector.graphql file and erase the contents. Next, copy the following extend schema:

extend schema
  @link(
    url: "https://specs.apollo.dev/federation/v2.10"
    import: ["@key"]
  )
  @link(
    url: "https://specs.apollo.dev/connect/v0.1"
    import: ["@source", "@connect"]
  )

  @source(
    name: "lambda"
    http: { baseURL: "https://lambda.us-east-1.amazonaws.com" }
  )

Extend schema is used to link the Apollo Connectors directives into the current schema. In this article we are defining the base URL of our lambda function. If your REST API has HTTP headers that apply to all references of this source, such as Content-Length restrictions, you can add them here in the @source declaration. Next, let’s define the Product schema:

type Product {
  id: ID!
  name: String
  description: String
  image: String
  price: Price
    @connect(
      source: "lambda"
      http: {
        POST: "/2015-03-31/functions/product-price/invocations"
        body: """
        product_id: $this.id
        """
      }
      selection: """
      amount: default_price
      isActive: is_active
      currency
      recurringInterval: recurring.interval -> match(
        [0,"ONE_TIME"],
        [1,"DAILY"],
        [2,"MONTHLY"],
        [3,"ANNUALLY"],
      )
      recurringCount: recurring.interval_count
      """
    )
}

Notice our query Products has an @connect directive that defines, at a minimum, the source name. Here, you can add the HTTP-specific configuration you need for this field, such as Authorizations headers. In this scenario, since we only defined a baseUrl in the extend schema section, we need to put the specific URL for the InvokeFunction, which is /2015-03-31/functions/product-price/invocations.

The selection field allows you to transform and map values returned from the REST API using the mapping definition defined in the selection field. While a complete discussion of selection mapping is beyond the scope of this article, check out the documentation for a detailed look at Mapping GraphQL Responses. Apollo provides a free online tool that makes building mappings intuitive and fast.

Next, let’s define the Price schema and products Query.

type Price {
  amount: Float
  isActive: Boolean
  currency: String
  recurringInterval: RecurringInterval
  recurringCount: Int
}
enum RecurringInterval {
  ONE_TIME
  DAILY
  MONTHLY
  ANNUALLY
}

type Query {
  products: [Product]
    # https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html
    @connect(
      source: "lambda"
      http: { POST: "/2015-03-31/functions/products/invocations" }
      selection: """
      $.body {
        id
        name
        description
        image
      }
      """
    )
}

Now we're ready to run our connector and issue queries to our graph! The complete configuration script is available at this Gist.

Step 10: Run the Connector

If you're using VS Code, the repository includes a tasks.json file that adds a “rover dev” task, which launches Rover locally.

{
    "version": "2.0.0",
    "tasks": [{
        "label": "rover dev",
        "command": "rover", // Could be any other shell command
        "args": ["dev", "--supergraph-config","supergraph.yaml", "--router-config","router.yaml"],
        "type": "shell",
        "problemMatcher": [],
    }]
}

If you are not using VS Code, you can start your graph by executing rover dev –supergraph-config supergraph.yaml –router-config router.yaml from a terminal window.

If everything is configured correctly, you’ll see the following:

Section 3: How to Use Apollo Sandbox

The rover dev command you launched in the previous step configures a local Apollo Router instance for development mode. This mode makes it easy for developers to create, execute, and debug ad-hoc GraphQL queries using the Apollo Sandbox web portal. This portal is located at http://localhost:4000 by default.

Launch the portal and click on the products field. This will populate the Operation pane with all the available fields in the schema. In the operation pane, you can modify and build your GraphQL query. Clicking the Run button (which displays the query name, Products, in our example) will execute the query and show the results in the Response panel, as illustrated in the figure above.

In this example, you can see that data has been returned from our AWS Lambda function. To confirm, you can view the query plan by selecting "Query Plan” from the Response drop-down menu.

The query plan illustrates the orchestration of our two AWS Lambda functions that fetch product and product price data.

A helpful debugging feature is the Connectors Debugger, available in the drop-down as shown in the previous figure.

The Connection Debugger provides a comprehensive view of the HTTP request, including headers, body, response code, and the selection mapping used in the query. If you’re experiencing difficulties running queries, use this debugger – it will save you a lot of time.

Summary

In this article, you learned how to:

• Set up AWS IAM User, Policies, and Lambda functions

• Create an Apollo Connector to obtain data from an AWS Lambda function

• Configure the Apollo Router

• Execute and debug queries using Apollo Sandbox

Integrating AWS Lambda with Apollo Connectors offers a simplified, resolver-free method for incorporating cloud functions into your GraphQL API. By utilizing Apollo Connectors, you can declaratively link REST-based Lambda functions to your supergraph while ensuring secure authentication with AWS SigV4.

You can learn more about Apollo Connectors from the following resources:

1. Tutorial: GraphQL meets REST, with Apollo Connectors

2. Blog: Discover how Apollo Connectors integrate with Apollo Federation through insights from Apollo's Founder & CTO: REST API Orchestration with GraphQL.

3. Blog: Delve into the engineering journey behind Apollo Connectors and the process of their creation: Our Journey to Apollo Connectors

4. Webinar: Apollo Connectors GA Launch Webinar

In this blog, we will be building with a Pokemon GraphQL API that gives us data about different Pokemons.

We will be using Apollo and GraphQL to handle the data fetching, and React for building our front-end application.

No worries if you don't know these technologies, I will be walking you through the basics as you read on.

Prerequisites

You should have these in your computer to follow along:

• Nodejs v18+
• A code editor
• A web browser

Let's create our React app.

React Application Setup

To create your React app, navigate to your terminal, and use the Command Prompt. Open your Command Prompt and choose your preferred location for creating your React project. Let's go with Desktop.

cd Desktop

The above command will navigate to your Desktop.

npm create vite@latest pokemon-app -- --template react

npm create vite@latest will start to build a new project using Vite. But we attached the name of our project (pokemon-app) and the technology or framework our app will be using (-- -- template react).

You can set another template like svelte, vanilla or vue and the project will be created using that framework. Read more about Vite on its official website.

After the Vite installation, run the following commands:

cd pokemon-app
npm install
npm run dev

We'll use the commands above to finish the React setup.

Run the first command, cd pokemon-app, to navigate to the pokeman-app folder.

Run code . to open the folder in your code editor.

modal displaying over VSCode to accept that you trust the authors of the files opened in VSCode

Mark the trust the author checkbox if that pops up.

Open your code editor's terminal. If you are running VSCode on Windows, the shortcut is `Ctrl + `` .

Run the other 2 commands in the terminal one after the other.

npm install

npm run dev

Your project should be running in the browser now.

We will be managing our data fetching using GraphQL and Apollo.

How to Use GraphQL and Apollo

GraphQL is a query language for APIs and a runtime for fulfilling queries with your existing data. It allows you to request only the data you need in your application and nothing more, making it very efficient and flexible.

Apollo is a state management library that allows you to manage local and remote data with GraphQL. It can be used to fetch, cache, and modify application data, all while automatically updating your UI.

Let's install the packages you need.

Installing Packages

Run the command below in your terminal to install the Apollo client.

npm install @apollo/client

Navigate to your main.jsx file and import these:

import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App.jsx";
import {
  ApolloProvider,
  ApolloClient,
  InMemoryCache,
} from "@apollo/client";
import "./index.css";

You have imported React and ReactDOM for DOM manipulation.

ApolloClient is responsible for managing your application's data fetching and state management. It handles sending GraphQL queries and mutations to your GraphQL server and caching the results.

ApolloProvider will be used to wrap your React application to provide the Apollo Client instance to all your components so that your application can access data fetched through Apollo Client.

InMemoryCache is a cache implementation to store the results of GraphQL queries in memory for efficient access and retrieval.

You have also imported index.css to style your application.

How to Create an Apollo Client

const client = new ApolloClient({
  uri: "https://graphql-pokemon2.vercel.app/",
  cache: new InMemoryCache(),
});

The code above creates a new instance of ApolloClient with the some configurations:

1. uri: This specifies the URL of your GraphQL API endpoint. This is the endpoint where your Apollo Client will send GraphQL queries and mutations.
2. cache: This configures the cache implementation for Apollo Client to use an in-memory cache to access data and store the result of GraphQL queries, reducing the need to re-fetch data from the server.

You can now wrap your <App /> component with ApolloProvider:

ReactDOM.createRoot(document.getElementById("root")).render(
  <React.StrictMode>
    <ApolloProvider client={client}>
      <App />
    </ApolloProvider>
  </React.StrictMode>
);

Note that client props was also passed to provide your application with ApolloClient configuration.

Go to your App.jsx component and input this:

import React from "react";
import { PokemonsContainer } from "./components/PokemonsContainer";

export default function App() {
  return (
    <main>
      <PokemonsContainer />
    </main>
  );
}

You imported React and PokemonsContainer will be created. The PokemonsContainer component was wrapped in main tag and will be rendered when the component is pasted in the DOM.

Let's create the PokemonsContainer component in a file located in components folder. That is:

📂 src/components/PokemonsContainer.jsx

Pokemons Container Component

import React from "react";
import { useQuery } from "@apollo/client";
import { Pokemon } from "../components/Pokemon";
import { GET_POKEMONS } from "../graphql/get-pokemons";

The useQuery from @apollo/client is used for executing queries in an Apollo application. To do that, useQuery() is called and a GraphQL query string is passed as a argument. When your component renders, useQuery returns an object from Apollo Client that contains loading, error, and data properties that you can use to render your UI.

Pokemon component was imported to render a user interface for a Pokemon, this will be built shortly.

GET_POKEMONS was also imported. This will contain a GraphQL query.

After importing the above functions, continue building your page.

export function PokemonsContainer() {
  const { loading, error, data } = useQuery(GET_POKEMONS, {
    variables: { first: 5 },
  });

  if (loading) return <p>Loading...</p>;
  if (error) return <p>Error: {error.message}</p>;

  const pokemons = data?.pokemons || [];
  return (
    <div className="container">
      {pokemons &&
        pokemons.map((pokemon) => (
          <Pokemon key={pokemon.id} pokemon={pokemon} />
        ))}
    </div>
  );
}

As mentioned earlier, useQuery returns an object from Apollo Client that contains loading, error, and data properties. They are destructured here so you can access them in the page.

Notice that we're providing a configuration option (variables) to the useQuery hook. { variables: { first: 5 } } was also passed as the second argument. The variables option is an object that contains all of the variables we want to pass to our GraphQL query. In this case, we passed an object { first: 5 } to specify that we want the first five Pokemons.

If the query is still loading, <p>Loading...</p> is returned to signify the user while <p>Error: {error.message}</p> will be returned if there is an error.

The pokemons constant was created to hold the value of the Pokemons property of the data object. If data.pokemons is not available, the pokemons constant will be an empty array.

A div is returned with a classname of container which checks if pokemons is available and maps the array over the Pokemon component.

Let's create the Pokemon component:

📂src/components/Pokemon.jsx

Pokemon Component

import React from "react";

export function Pokemon({ pokemon }) {
  return (
    <div className="pokemon">
      <div className="pokemon__name">
        <p>{pokemon.name}</p>
      </div>
      <div className="pokemon__meta">
        <span>{pokemon.maxHP}</span>
        <span>{pokemon.maxCP}</span>
      </div>
      <div className="pokemon__image">
        <img src={pokemon.image} alt={pokemon.name} />
      </div>
      <div className="pokemon__attacks">
        {pokemon.attacks.special.slice(0, 3).map((attack) => (
          <span key={`${attack.name}-${attack.damage}`}>{attack.name}</span>
        ))}
      </div>
    </div>
  );
}

The structure of an instance of a Pokemon is defined here with the classname for styling. The name, maxHP, maxCP, image and attacks array will be rendered.

Let's create the GET_POKEMONS GraphQL query.

📂src/graphql/get-pokemons

GraphQL Query

import gql from "graphql-tag";

export const GET_POKEMONS = gql`
  query pokemons($first: Int!) {
    pokemons(first: $first) {
      id
      name
      image
      maxHP
      maxCP
      attacks {
        special {
          name
          damage
        }
      }
    }
  }
`;

You imported gql from graphql-tag and created a GraphQL query named GET_POKEMONS.

The pokemons query function was wrapped in strings for the gql function to parse them into query documents.

$first: Int! means that your query is expecting a variable called first, which is an integer, and the ! symbol after the Int means that the variable is required.

Recall that we created the variables object in the PokemonsContainer component, it's here below.

 const { loading, error, data } = useQuery(GET_POKEMONS, {
   variables: { first: 5 },
 });

pokemons(first: $first) was also declared. $first will be assigned to 5 here (we passed in 9 in the above code snippet). Thus, the array will contain only 5 objects. Each object will contain id, name, image, maxHP, maxCP, and attacks object which will contain the special object containing name and damage.

The GraphQL server might contain more properties but will only return the properties listed above. That is one of the cool functionalities of GraqhQL – it gives you only the data you request for.

Styling our Application

Your index.css should contain this:

/* RESETS
=========================================== */
html {
  -webkit-box-sizing: border-box;
  box-sizing: border-box;
}

*,
*:before,
*:after {
  -webkit-box-sizing: inherit;
  box-sizing: inherit;
}

body {
  margin: 20px 0;
  padding: 0 20px;
  line-height: 1;
  font-family: "Segoe UI", Tahoma, Geneva, Verdana, sans-serif;
  color: #202020;
  background-color: #fbfbfb;
  font-smooth: always;
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
}

/* POKEMON APPLICATION
=========================================== */
.container {
  display: flex;
  max-width: 80%;
  margin: auto;
  height: 100vh;
  justify-content: space-between;
  align-items: center;
  gap: 10px;
}

.container p {
  margin: 0;
}

.container .pokemon {
  width: 20%;
  background-color: #fff;
  background-clip: border-box;
  border: 1px solid rgba(0, 0, 0, 0.125);
  border-radius: 0.25rem;
  box-shadow: 0 0.125rem 0.25rem rgba(0, 0, 0, 0.075);
  overflow: hidden;
  /* margin: 5px; */
}

.container .pokemon__name {
  background-color: #ecd018;
  text-align: center;
  padding: 10px;
}

.container .pokemon__name p {
  text-transform: uppercase;
  font-weight: bold;
  color: white;
  letter-spacing: 4px;
  text-shadow: 0px 1px 2px rgba(0, 0, 0, 0.4);
}

.container .pokemon__image {
  padding: 20px;
  min-height: 300px;
  display: flex;
  align-items: center;
  justify-content: center;
}

.container .pokemon__image img {
  max-width: 100%;
  height: auto;
}

.container .pokemon__attacks {
  display: flex;
  padding-left: 10px;
  padding-right: 10px;
  justify-content: space-between;
}

.container .pokemon__attacks span {
  width: 32%;
  background-color: #f16820;
  border-radius: 3px;
  padding: 7px;
  font-weight: 700;
  color: #fff;
  padding-left: 10px;
  padding-right: 10px;
  font-size: 12px;
  margin-bottom: 10px;
  word-wrap: break-word;
  text-align: center;
  line-height: 15px;
}

.container .pokemon__meta {
  display: flex;
  justify-content: space-between;
  margin-top: 10px;
  padding: 0 10px;
}

.container .pokemon__meta span {
  color: white;
  text-shadow: 0px 1px 2px rgba(0, 0, 0, 0.4);
  background-color: #7bb7b7;
  font-weight: bold;
  margin: 0;
  padding: 5px 20px;
  border-radius: 5px;
}

All things done right, you should have this in your browser:

a picture showing the five pokemons data in the browser

You can get the GitHub code here: https://github.com/segunajibola/pokemon-graphql

You can also view the live site hosted on Vercel here: pokemonsapp.vercel.app

Check my portfolio of projects: segunajibola.com

Conclusion

That will be all. I hope you found value here as you learn more about the web.

If you enjoyed this article and want to see more content related to JavaScript and web development, then follow me here, Twitter (X) or connect on LinkedIn. I'd be happy to count you as one of my ever-growing group of awesome friends on the internet.

You can also join my WhatsApp developer community and OpenSource community of 330+ developers learning and building cool projects.

If you also want to support me, you can also buy me a cup of coffee.

Thanks and bye. 👋

The main purpose of this server-client Node.js project is to help other people understand how GraphQL exposes data from the Server and how the Client fetches it.

I have tried to make it as simple as possible - if you want to dive into the code of the project you can find it here.

Now, straight to the point: GraphQL is a query language for APIs developed and open-sourced by Facebook to speed up the request process.

REST has been a popular way to expose data from a server. But instead of having multiple endpoints that return fixed data structures, GraphQL just has a single endpoint. And it is the client's job to specify what data it needs from it.

Table of Contents

• Getting started
• How to Define the Schema
• How to Add the Resolver function
• How to Set up the Server
• How to Set up the Client
• How to Fetch Data from the Server
• How to Display the Data
• Conclusion
• Useful resources
  • Docs 📚
  • Learn 📝
  • Tools 🔧
  • IDEs 💻
  • Extras 🍍

Getting started

The first step is to download and install Node.js in case you haven't already. Once you have it installed let's begin with the directory structure.

The project will be composed of two directories, one for the Client and another for the Server. I have chosen to keep both inside the project root directory, but then you can split it into two separate projects or any way you want.

📁 project
├── 📁 client
└── 📁 server

Now we will initialize the project in the server directory. Change the location to the server folder in your terminal and run npm init to fill in the project info and generate the package.json file.

Or you can npm init -y which tells the generator to use the defaults (instead of asking questions and simply generating an empty npm project without going through an interactive process).

The next step will be to install GraphQL.js and Apollo Server to our server. GraphQL.js will provide two important capabilities:

• Building a type schema, which we will do in the next step.
• Serving queries against that type schema.

To install it just run npm install graphql. I am assuming you are using a version of NPM equal or higher than 5.0.0 so you do not need to add --save when installing a dependency to be saved in the package.json.

Apollo Server, on the other hand, will help us to implement the GraphQL functionalities. It is part of the Apollo Data Graph Platform.

Apollo is a platform for building a data graph, a communication layer that seamlessly connects your application clients (such as React and iOS apps) to your back-end services. Is an implementation of GraphQL designed for the needs of product engineering teams building modern, data-driven applications. - Apollo Documentation

What you need to know about Apollo, at least for now, is that it’s a community that builds on top of GraphQL and provides different tools to help you build your projects. The tools provided by Apollo are mainly 2: Client and Server.

• Apollo Client helps your Frontend communicate with a GraphQL API. It has support for the most popular frameworks such as React, Vue, or Angular and native development on iOS and Android.

• Apollo Server is the GraphQL server layer in your backend that delivers the responses back to the client requests.

Now that you understand Apollo better and why we will use it, let's continue setting up GraphQL.

How to Define the Schema

A GraphQL Schema is at the core of any GraphQL server implementation. It describes the shape of your data, defining it with a hierarchy of types with fields that are populated from your data source. It also specifies which queries and mutations are available, so the client knows about the information that can be requested or sent.

For example, if we wanted to build a music application, our simplest schema, usually defined in a schema.graphql file, would contain two Object types: Song and Author, like this:

type Song {
  title: String
  author: Author
}

type Author {
  name: String
  songs: [Song]
}

Then we would have a Query type to define the available queries: getSongs and getAuthors, each returning a list of the corresponding type.

type Query {
  getSongs: [Song]
  getAuthors: [Author]
}

To keep it as simple as possible, our schema will have just a single Query type which will return a String.

type Query {
  greeting: String
}

We can use any programming language to create a GraphQL schema and build an interface around it, but as I explained before we will use Apollo server to execute GraphQL queries.

So we create a new server.js file in the server directory to define the Schema on it.

📁 project
├── 📁 client
└── 📁 server
    └── 📄 server.js

Now we install apollo-server by running npm install apollo-server.

We have to import the tag function gql from apollo-server to parse the schema this way: const {gql} = require('apollo-server'); and then declare a typeDefs constant which is an abstract syntax tree of the Graphql code.

When a GraphQL server receives a query to process, it generally comes in as a String. This string must be tokenized and parsed into a representation that the machine understands. This representation is called an abstract syntax tree.

If you want to learn more about abstract syntax trees, AST Explorer is an online tool that lets you explore the syntax tree created by a chosen language as a parser.

The server.js file would look like this:

const { gql } = require('apollo-server');

const typeDefs = gql`
  type Query {
    greeting: String
  }
`;

How to Add the Resolver Function

Now that we have defined our Schema, we need a way to answer the client requests for that data: the resolvers.

A resolver is a function that handles the data for each one of the fields of your schema. You can send that data to the client by fetching a back-end database or a third-party API, among others.

They have to match the type definitions of the Schema. In our case, we just have one type definition, Query, which returns a greeting of type String, so we will define a resolver for the greeting field, like so:

const resolvers = {
  Query: {
    greeting: () => 'Hello GraphQL world!👋',
  },
};

As I explained at the beginning, we will keep this example as simple as possible. But keep in mind that in a real case here is where you have to make the queries to the database, external API, or from whichever one you intend to extract the query data.

How to Set up the Server

In the same server.js, we define and create a new ApolloServer object, passing the Schema (typeDefs) and resolvers as parameters.

const { ApolloServer, gql } = require('apollo-server');

const server = new ApolloServer({ typeDefs, resolvers });

Then calling the listen method we start the server on the port that we specify in the params.

server
  .listen({ port: 9000 })
  .then(serverInfo => console.log(`Server running at ${serverInfo.url}`));

We can also destructure the ServerInfo url when logging it.

server
  .listen({ port: 9000 })
  .then(({ url }) => console.log(`Server running at ${url}`));

The server.js file should look like this right now:

const { ApolloServer, gql } = require('apollo-server');

const typeDefs = gql`
  type Query {
    greeting: String
  }
`;

const resolvers = {
  Query: {
    greeting: () => 'Hello GraphQL world!👋',
  },
};

const server = new ApolloServer({ typeDefs, resolvers });
server
  .listen({ port: 9000 })
  .then(({ url }) => console.log(`Server running at ${url}`));

Now if we run node server/server.js we will finally have our GraphQL server up and running!🎉

You can go and check it out on http://localhost:9000/

~/graphql-hello-world-server
> node server/server.js
Server running at http://localhost:9000/

If this is your first time using GraphQL, you may be thinking what is this application I am seeing in front of me if we have not written a single line of client code?.

The answer to that question is the GraphQL Playground.

GraphQL Playground is a graphical, interactive, in-browser GraphQL IDE, created by Prisma and based on GraphiQL. - Apollo docs

But what does that mean? It means that this is an environment where we can perform Queries, Mutations, or Subscriptions to our schema and interact with its data.

If you have worked with RESTful requests before this would be some kind of equivalent to Postman. It's just that here you do not have to download and configure anything, it just comes by default with Apollo!

So let's try it out!

1. On the left panel write the greeting query we defined in our schema.
2. Then press the ▶ button that is in the middle.
3. And Voila! On the right panel appears the data we defined in our resolver to return.

How to Set up the Client

Now that we have our server up and running, let's focus on the client part. We will start by creating a client.html file inside our client folder.

📁 project
├── 📁 client
|   └── 📄 client.html
└── 📁 server
    └── 📄 server.js

The index.html file will have the basics of any HTML file and a loading header <h1>Loading...</h1> to show the user something while we request the data from the server.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Hello World GraphQL Client</title>
  </head>

  <body>
    <h1>Loading...</h1>

    <script src="app.js"></script>
  </body>
</html>

How to Fetch Data from the Server

First off, in the same client folder, we create an app.js file where we will write the client logic to fetch the data from the server.

📁 project
├── 📁 client
|   └── 📄 client.html
|   └── 📄 app.js
└── 📁 server
    └── 📄 server.js

Inside it, we set the server URL to the one from which we will make the request.

const GRAPHQL_URL = 'http://localhost:9000/';

Next, we define our async function fetchGreeting() to fetch the greeting from the server. We will use the fetch API to perform the HTTP request which by default returns a promise to which we can subscribe and get the answer asynchronously.

async function fetchGreeting() {
  const response = await fetch(GRAPHQL_URL, {
    method: 'POST',
    headers: {
      'content-type': 'application/json',
    },
    body: JSON.stringify({
      query: `
        query {
          greeting
        }
      `,
    }),
  });

  const responseBody = await response.json();
  console.log(responseBody);
}

A detail to take into account is that the method of the request is POST. This can confuse us if we are used to working with RESTful because this same request made in RESTful, where we just want to read information from the server, would usually be done with the method GET.

The thing is that with GraphQL we always make POST requests where we pass the query in the payload (body).

Finally, we just call our method fetchGreeting();

const GRAPHQL_URL = 'http://localhost:9000/';

async function fetchGreeting() {
  const response = await fetch(GRAPHQL_URL, {
    method: 'POST',
    headers: {
      'content-type': 'application/json',
    },
    body: JSON.stringify({
      query: `
        query {
          greeting
        }
      `,
    }),
  });

  const responseBody = await response.json();
  console.log(responseBody);
}

fetchGreeting();

If you open the file in your browser and see the console on the developer tools you can see that we actually got the greeting data from the query 🙌!

How to Display the Data

Now that we have successfully gotten the data from the server, lets update the loading title. The first thing we will do is destructure the response and return just the data from it.

Just replace this part of the code:

const responseBody = await response.json();
console.log(responseBody);

With this:

const { data } = await response.json();
return data;

Then we will update the title with the greeting returned inside the data from the response

fetchGreeting().then(({ greeting }) => {
  const title = document.querySelector('h1');
  title.textContent = greeting;
});

So our app.js file will end up having this look:

const GRAPHQL_URL = 'http://localhost:9000/';

async function fetchGreeting() {
  const response = await fetch(GRAPHQL_URL, {
    method: 'POST',
    headers: {
      'content-type': 'application/json',
    },
    body: JSON.stringify({
      query: `
        query {
          greeting
        }
      `,
    }),
  });

  const { data } = await response.json();
  return data;
}

fetchGreeting().then(({ greeting }) => {
  const title = document.querySelector('h1');
  title.textContent = greeting;
});

Our index.html will have the loading title updated with the data fetched from our server!🎉

Conclusion

I hope you enjoyed the post and that this project has helped show you how graphql works under the hood, at least in a very simple way.

I know there are a lot of things that I have not explained or that I could have gone deeper into. But like any hello world project, this was intended for people who are beginners with it, so I wanted to keep it as simple as possible.

I'm looking forward to learning more about GraphQL and using it in future projects. If you've got any questions, suggestions, or feedback in general, don't hesitate to reach out on any of the social networks from my site or by mail.

Useful GraphQL Resources

Here is a collection of links and resources which have been useful for me to improve and learn more about GraphQL

Docs 📚

• Project source code - The Github repository with all the code from the project.
• GraphQL main site - GraphQL main site.
• Apollo documentation - The Apollo platform docs.

Learn 📝

• How to GraphQL - Free and open-source tutorials to learn all around GraphQL to go from zero to production.
• GraphQL by Example - Great course where you learn GraphQL by writing full-stack JavaScript applications with Node.js, Express, Apollo Server, React, Apollo Client.
• Introduction to GraphQL - A series of articles to learn about GraphQL, how it works, and how to use it.

Tools 🔧

• Apollo GraphQL - Main site of the Apollo GraphQL implementation.
• GraphQL Playground - Repository of the GraphQL Playground IDE we used on the project.

IDEs 💻

• JS GraphQL - WebStorm and other IntelliJ-based IDEs plugin to support GraphQL language including tagged template literals in JavaScript and TypeScript.
• GraphQL - GraphQL extension for VSCode adds syntax highlighting, validation, and language features like go to definition, hover information, and autocompletion for GraphQL projects. This extension also works with queries annotated with gql tag.
• GraphQL for VSCode - VSCode GraphQL syntax highlighting, linting, auto-complete, and more!

Extras 🍍

• GraphQL APIs - A list of public GraphQL APIs to test your skills or to build something with them.
• GraphQL: The Documentary - A 30 min video that explores the story of why and how GraphQL appeared, and the impact it's having on big tech companies worldwide, including Facebook, Twitter, Airbnb, and Github.

I hope you enjoyed this article. You can read it too on my site along with others! If you've got any questions, suggestions, or feedback in general, don't hesitate to reach out on any of the social networks from my site.

• What is GraphQL?
• What is Apollo GraphQL?
• Fetching data in Next.js
• What are we going to build?
• Step 0: Creating a new Next.js app
• Step 1: Adding Apollo GraphQL to a Next.js app
• Step 2: Adding data to a Next.js page with getStaticProps
• Step 3: Fetch data with a GraphQL query in Next.js using Apollo Client
• Step 4: Adding SpaceX launch data to the page

What is GraphQL?

GraphQL is a query language and runtime that provides a different way of interacting with an API than what you would expect with a traditional REST API.

When fetching data, instead of making a GET request to a URL to grab that data, GraphQL endpoints take a “query”. That query consists of what data you want to grab, whether it’s an entire dataset or a limited portion of it.

If your data looks something like this:

Movie {
  "title": "Sunshine",
  "releaseYear": "2007",
  "actors": [...],
  "writers": [...]
}

And you only want to grab the title and the year it was released, you could send in a query like this:

Movie {
  title
  releaseYear
}

Grabbing only the data you need.

The cool thing is, you can also provide complex relationships between the data. With a single query, you could additionally request that data from different parts of the database that would traditionally take multiple requests with a REST API.

What is Apollo GraphQL?

Apollo GraphQL at its core is a GraphQL implementation that helps people bring together their data as a graph.

Apollo also provides and maintains a GraphQL client, which is what we’re going to use, that allows people to programmatically interact with a GraphQL API.

Using Apollo’s GraphQL client, we’ll be able to make requests to a GraphQL API similar to what we would expect with a REST-based request client.

Fetching data in Next.js

When fetching data with Next.js, you have a few options for how you want to fetch that data.

First, you could go the client side route and make the request once the page loads. The issue with this is that you’re then putting the burden on the client to take the time to make those requests.

The Next.js APIs like getStaticProps and getServerSideProps allow you to collect data at different parts of the lifecycle, giving us the opportunity to make a completely static app or one that’s server-side rendered. That will serve the data already rendered to the page straight to the browser.

By using one of those methods, we can request data along with our pages and inject that data as props right into our app.

What are we going to build?

We’re going to create a Next.js app that shows the latest launches from SpaceX.

SpaceX launches demo

We’ll use the API maintained by SpaceX Land to make a GraphQL query that grabs the last 10 flights. Using getStaticProps, we’ll make that request at build time, meaning our page will be rendered statically with our data.

Step 0: Creating a new Next.js app

Using Create Next App, we can quickly spin up a new Next.js app that we can use to immediately start diving into the code.

Inside your terminal, run the command:

npx create-next-app my-spacex-launches

Note: you don’t have to use my-spacex-app, feel free to replace that with whatever name you want to give the project.

After running that script, Next.js will set up a new project and install the dependencies.

Once finished, you can start up your development server:

cd my-spacex-launches
npm run dev

This will start a new server at http://localhost:3000 where you can now visit your new app!

New Next.js app

Step 1: Adding Apollo GraphQL to a Next.js app

To get started with making a GraphQL query, we’ll need a GraphQL client. We’ll use the Apollo GraphQL Client to make our queries to the SpaceX GraphQL server.

Back inside of the terminal, run the following command to install our new dependencies:

npm install @apollo/client graphql

This will add the Apollo Client as well as GraphQL, which we’ll need to to form the GraphQL query.

And once installation completes, we’ll be ready to get started Using Apollo Client.

Follow along with the commit!

Step 2: Adding data to a Next.js page with getStaticProps

Before we fetch any data with Apollo, we’re going to set up our page to be able to request data then pass that data as a prop to our page at build time.

Let’s define a new function at the bottom of the page below our Home component called getStaticProps:

export async function getStaticProps() {
  // Code will go here
}

When Next.js builds our app, it knows to look for this function. So when we export it, we’re letting Next.js know we want to run code in that function.

Inside our getStaticProps function, we’re going to be ultimately returning our props to the page. To test this out, let’s add the following to our function:

export async function getStaticProps() {
  return {
    props: {
      launches: []
    }
  }
}

Here, we’re passing a new prop of launches and setting it to an empty array.

Now, back inside of our Home component, let’s add a new destructured argument that will serve as our prop along with a console.log statement to test our new prop:

export default function Home({ launches }) {
  console.log('launches', launches);

If we reload the page, we can see that we’re now logging out our new prop launches which includes an empty array just like we defined.

Logging launches prop

The great thing about this is that given that the getStaticProps function we’re creating is asynchronous, we can make any request we’d like (including a GraphQL query) and return it as props to our page, which is what we’ll do next.

Follow along with the commit!

Step 3: Fetch data with a GraphQL query in Next.js using Apollo Client

Now that our application is prepared to add props to the page and we have Apollo installed, we can finally make a request to grab our SpaceX data.

Here, we’re going to use the Apollo Client, which will allow us to interface with the SpaceX GraphQL server. We’ll make our request to the API using the Next.js getStaticProps method, allowing us to dynamically create props for our page when it builds.

First, let’s import our Apollo dependencies into the project. At the top of the page add:

import { ApolloClient, InMemoryCache, gql } from '@apollo/client';

This is going to include the Apollo Client itself, InMemoryCache which allows Apollo to optimize by reading from cache, and gql which we’ll use to form our GraphQL query.

Next, to use the Apollo Client, we need to set up a new instance of it.

Inside the top of the getStaticProps function, add:

const client = new ApolloClient({
  uri: 'https://api.spacex.land/graphql/',
  cache: new InMemoryCache()
});

This creates a new Apollo Client instance using the SpaceX API endpoint that we’ll use to query against.

With our client, we can finally make a query. Add the following code below the client:

const { data } = await client.query({
  query: gql`
    query GetLaunches {
      launchesPast(limit: 10) {
        id
        mission_name
        launch_date_local
        launch_site {
          site_name_long
        }
        links {
          article_link
          video_link
          mission_patch
        }
        rocket {
          rocket_name
        }
      }
    }
  `
});

This does a few things:

• Creates a new GraphQL query inside of the gql tag
• Creates a new query request using client.query
• It uses await to make sure it finishes the request before continuing
• And finally destructures data from the results, which is where the information we need is stored

Inside of the GraphQL query, we’re telling the SpaceX API that we want to get launchesPast, which are the previous launches from SpaceX, and we want to get the last 10 of them (limit). Inside that, we define the data we’d like to query.

If we take a second to add a new console log statement after that, we can see what data looks like.

Once you refresh the page though, you’ll notice that you’re not seeing anything inside of the browser’s console.

getStaticProps runs during the build process, meaning, it runs in node. Because of that, we can look inside of our terminal and we can see our logs there:

Logging data to the terminal

After seeing that, we know that inside of the data object, we have a property called launchesPast, which includes an array of launch details.

Now, we can update our return statement to use launchesPast:

return {
  props: {
    launches: data.launchesPast
  }
}

And if we add our console.log statement back to the top of the page to see what our launches prop looks like, we can see our launch data is now available as a prop to our page:

Logging props to web console

Follow along with the commit!

Step 4: Adding SpaceX launch data to the page

Now for the exciting part!

We have our launch data that we were able to use Apollo Client to request from the SpaceX GraphQL server. We made that request in getStaticProps so that we could make our data available as the launches prop that contains our launch data.

Digging into the page, we’re going to take advantage of what already exists. For instance, we can start by updating the h1 tag and the paragraph below it to something that describes our page a little bit better.

Updated page title

Next, we can use the already existing link cards to include all of our launch information.

To do this, let’s first add a map statement inside of the page’s grid, where the component we return is one of the cards, with launch details filled in:

<div className={styles.grid}>
  {launches.map(launch => {
    return (
      <a key={launch.id} href={launch.links.video_link} className={styles.card}>
        <h3>{ launch.mission_name }</h3>
        <p><strong>Launch Date:</strong> { new Date(launch.launch_date_local).toLocaleDateString("en-US") }</p>
      </a>
    );
  })}

We can also get rid of the rest of the default Next.js cards including Documentation and Learn.

Page with SpaceX launches

Our page now includes the last 10 launches from SpaceX along with the date of the launch!

We can even click any of those cards, and because we linked to the video link, we can now see the launch video.

Follow along with the commit!

What’s next?

From here, we can include any additional data from inside of our launches array on our page. The API even includes mission patch images, which we can use to show nice graphics for each launch.

You can even add additional data to the GraphQL query. Each launch has a lot of information available including the launch crew and more details about the rocket.

https://api.spacex.land/graphql/

I've put together a comprehensive cheatsheet that goes through all of the core concepts in the Apollo library, showing you how to use it with React from front to back.

Want Your Own Copy?

You can grab the PDF cheatsheet right here (it takes 5 seconds).

Here are some quick wins from grabbing the downloadable version:

• ✓ Quick reference to review however and whenever
• ✓ Tons of useful code snippets based off of real-world projects
• ✓ Read this guide offline, wherever you like. On the train, at your desk, standing in line — anywhere.

Prefer Video Lessons?

A great deal of this cheatsheet is based off of the app built in the React + GraphQL 2020 Crash Course.

If you want some more hands-on video lessons, plus see how to build apps with React, GraphQL and Apollo, you can watch the course right here.

Note: This cheatsheet does assume familiarity with React and GraphQL. If you need a quick refresher on GraphQL and how to write it, a great resource is the official GraphQL website.

Table of Contents

Getting Started

• What is Apollo and why do we need it?
• Apollo Client setup
• Creating a new Apollo Client
• Providing the client to React components
• Using the client directly
• Writing GraphQL in .js files with gql

Core Apollo React Hooks

• useQuery Hook
• useLazyQuery Hook
• useMutation Hook
• useSubscription Hook

Essential Recipes

• Manually setting the fetch policy
• Updating the cache upon a mutation
• Refetching queries with useQuery
• Refetching queries with useMutation
• Accessing the client with useApolloClient

What is Apollo and why do we need it?

Apollo is a library that brings together two incredibly useful technologies used to build web and mobile apps: React and GraphQL.

React was made for creating great user experiences with JavaScript. GraphQL is a very straightforward and declarative new language to more easily and efficiently fetch and change data, whether it is from a database or even from static files.

Apollo is the glue that binds these two tools together. Plus it makes working with React and GraphQL a lot easier by giving us a lot of custom React hooks and features that enable us to both write GraphQL operations and execute them with JavaScript code.

We'll cover these features in-depth throughout the course of this guide.

Apollo Client basic setup

If you are starting a project with a React template like Create React App, you will need to install the following as your base dependencies to get up and running with Apollo Client:

// with npm:
npm i @apollo/react-hooks apollo-boost graphql

// with yarn:
yarn add @apollo/react-hooks apollo-boost graphql

@apollo/react-hooks gives us React hooks that make performing our operations and working with Apollo client better

apollo-boost helps us set up the client along with parse our GraphQL operations

graphql also takes care of parsing the GraphQL operations (along with gql)

Apollo Client + subscriptions setup

To use all manner of GraphQL operations (queries, mutations, and subscriptions), we need to install more specific dependencies as compared to just apollo-boost:

// with npm:
npm i @apollo/react-hooks apollo-client graphql graphql-tag apollo-cache-inmemory apollo-link-ws

// with yarn:
yarn add @apollo/react-hooks apollo-client graphql graphql-tag apollo-cache-inmemory apollo-link-ws

apollo-client gives us the client directly, instead of from apollo-boost

graphql-tag is integrated into apollo-boost, but not included in apollo-client

apollo-cache-inmemory is needed to setup our own cache (which apollo-boost, in comparison, does automatically)

apollo-link-ws is needed for communicating over websockets, which subscriptions require

Creating a new Apollo Client (basic setup)

The most straightforward setup for creating an Apollo client is by instantiating a new client and providing just the uri property, which will be your GraphQL endpoint:

import ApolloClient from "apollo-boost";

const client = new ApolloClient({
  uri: "https://your-graphql-endpoint.com/api/graphql",
});

apollo-boost was developed in order to make doing things like creating an Apollo Client as easy as possible. What it lacks for the time being, however, is support for GraphQL subscriptions over a websocket connection.

By default, it performs the operations over an http connection (as you can see through our provided uri above).

In short, use apollo-boost to create your client if you only need to execute queries and mutations in your app.

It setups an in-memory cache by default, which is helpful for storing our app data locally. We can read from and write to our cache to prevent having to execute our queries after our data is updated. We'll cover how to do that a bit later.

Creating a new Apollo Client (+ subscriptions setup)

Subscriptions are useful for more easily displaying the result of data changes (through mutations) in our app.

Generally speaking, we use subscriptions as an improved kind of query. Subscriptions use a websocket connection to 'subscribe' to updates and data, enabling new or updated data to be immediately displayed to our users without having to reexecute queries or update the cache.

import ApolloClient from "apollo-client";
import { WebSocketLink } from "apollo-link-ws";
import { InMemoryCache } from "apollo-cache-inmemory";

const client = new ApolloClient({
  link: new WebSocketLink({
    uri: "wss://your-graphql-endpoint.com/v1/graphql",
    options: {
      reconnect: true,
      connectionParams: {
        headers: {
          Authorization: "Bearer yourauthtoken",
        },
      },
    },
  }),
  cache: new InMemoryCache(),
});

Providing the client to React components

After creating a new client, passing it to all components is essential in order to be able to use it within our components to perform all of the available GraphQL operations.

The client is provided to the entire component tree using React Context, but instead of creating our own context, we import a special context provider from @apollo/react-hooks called ApolloProvider . We can see how it differs from the regular React Context due to it having a special prop, client, specifically made to accept the created client.

Note that all of this setup should be done in your index.js or App.js file (wherever your Routes declared) so that the Provider can be wrapped around all of your components.

import { ApolloProvider } from "@apollo/react-hooks";

const rootElement = document.getElementById("root");
ReactDOM.render(
  <React.StrictMode>
    <ApolloProvider client={client}>
      <BrowserRouter>
        <Switch>
          <Route exact path="/" component={App} />
          <Route exact path="/new" component={NewPost} />
          <Route exact path="/edit/:id" component={EditPost} />
        </Switch>
      </BrowserRouter>
    </ApolloProvider>
  </React.StrictMode>,
  rootElement
);

Using the client directly

The Apollo client is most important part of the library due to the fact that it is responsible for executing all of the GraphQL operations that we want to perform with React.

We can use the created client directly to perform any operation we like. It has methods corresponding to queries (client.query()), mutations (client.mutate()), and subscriptions (client.subscribe()).

Each method accepts an object and it's own corresponding properties:

// executing queries
client
  .query({
    query: GET_POSTS,
    variables: { limit: 5 },
  })
  .then((response) => console.log(response.data))
  .catch((err) => console.error(err));

// executing mutations
client
  .mutate({
    mutation: CREATE_POST,
    variables: { title: "Hello", body: "World" },
  })
  .then((response) => console.log(response.data))
  .catch((err) => console.error(err));

// executing subscriptions
client
  .subscribe({
    subscription: GET_POST,
    variables: { id: "8883346c-6dc3-4753-95da-0cc0df750721" },
  })
  .then((response) => console.log(response.data))
  .catch((err) => console.error(err));

Using the client directly can be a bit tricky, however, since in making a request, it returns a promise. To resolve each promise, we either need .then() and .catch() callbacks as above or to await each promise within a function declared with the async keyword.

Writing GraphQL operations in .js files (gql)

Notice above that I didn't specify the contents of the variables GET_POSTS, CREATE_POST, and GET_POST.

They are the operations written in the GraphQL syntax which specify how to perform the query, mutation, and subscription respectively. They are what we would write in any GraphiQL console to get and change data.

The issue here, however, is that we can't write and execute GraphQL instructions in JavaScript (.js) files, like our React code has to live in.

To parse the GraphQL operations, we use a special function called a tagged template literal to allow us to express them as JavaScript strings. This function is named gql.

// if using apollo-boost
import { gql } from "apollo-boost";
// else, you can use a dedicated package graphql-tag
import gql from "graphql-tag";

// query
const GET_POSTS = gql`
  query GetPosts($limit: Int) {
    posts(limit: $limit) {
      id
      body
      title
      createdAt
    }
  }
`;

// mutation
const CREATE_POST = gql`
  mutation CreatePost($title: String!, $body: String!) {
    insert_posts(objects: { title: $title, body: $body }) {
      affected_rows
    }
  }
`;

// subscription
const GET_POST = gql`
  subscription GetPost($id: uuid!) {
    posts(where: { id: { _eq: $id } }) {
      id
      body
      title
      createdAt
    }
  }
`;

useQuery Hook

The useQuery hook is arguably the most convenient way of performing a GraphQL query, considering that it doesn't return a promise that needs to be resolved.

It is called at the top of any function component (as all hooks should be) and receives as a first required argument—a query parsed with gql.

It is best used when you have queries that should be executed immediately, when a component is rendered, such as a list of data which the user would want to see immediately when the page loads.

useQuery returns an object from which we can easily destructure the values that we need. Upon executing a query, there are three primary values will need to use within every component in which we fetch data. They are loading, error, and data.

const GET_POSTS = gql`
  query GetPosts($limit: Int) {
    posts(limit: $limit) {
      id
      body
      title
      createdAt
    }
  }
`;

function App() {
  const { loading, error, data } = useQuery(GET_POSTS, {
    variables: { limit: 5 },
  });

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error!</div>;

  return data.posts.map((post) => <Post key={post.id} post={post} />);
}

Before we can display the data that we're fetching, we need to handle when we're loading (when loading is set to true) and we are attempting to fetch the data.

At that point, we display a div with the text 'Loading' or a loading spinner. We also need to handle the possibility that there is an error in fetching our query, such as if there's a network error or if we made a mistake in writing our query (syntax error).

Once we're done loading and there's no error, we can use our data in our component, usually to display to our users (as we are in the example above).

There are other values which we can destructure from the object that useQuery returns, but you'll need loading, error, and data in virtually every component where you execute useQuery. You can see a full list of all of the data we can get back from useQuery here.

useLazyQuery Hook

The useLazyQuery hook provides another way to perform a query, which is intended to be executed at some time after the component is rendered or in response to a given data change.

useLazyQuery is very useful for things that happen at any unknown point of time, such as in response to a user's search operation.

function Search() {
  const [query, setQuery] = React.useState("");
  const [searchPosts, { data }] = useLazyQuery(SEARCH_POSTS, {
    variables: { query: `%${query}%` },
  });
  const [results, setResults] = React.useState([]);

  React.useEffect(() => {
    if (!query) return;
    // function for executing query doesn't return a promise
    searchPosts();
    if (data) {
      setResults(data.posts);
    }
  }, [query, data, searchPosts]);

  if (called && loading) return <div>Loading...</div>;

  return results.map((result) => (
    <SearchResult key={result.id} result={result} />
  ));
}

useLazyQuery differs from useQuery, first of all, in what's returned from the hook. It returns an array which we can destructure, instead of an object.

Since we want to perform this query sometime after the component is mounted, the first element that we can destructure is a function which you can call to perform that query when you choose. This query function is named searchPosts in the example above.

The second destructured value in the array is an object, which we can use object destructuring on and from which we can get all of the same properties as we did from useQuery, such as loading, error, and data.

We also get an important property named called, which tells us if we've actually called this function to perform our query. In that case, if called is true and loading is true, we want to return "Loading..." instead of our actual data, because are waiting for the data to be returned. This is how useLazyQuery handles fetching data in a synchronous way without any promises.

Note that we again pass any required variables for the query operation as a property, variables, to the second argument. However, if we need, we can pass those variables on an object provided to the query function itself.

useMutation Hook

Now that we know how to execute lazy queries, we know exactly how to work with the useMutation hook.

Like the useLazyQuery hook, it returns an array which we can destructure into its two elements. In the first element, we get back a function, which in this case, we can call it to perform our mutation operation. For next element, we can again destructure an object which returns to us loading, error and data.

import { useMutation } from "@apollo/react-hooks";
import { gql } from "apollo-boost";

const CREATE_POST = gql`
  mutation CreatePost($title: String!, $body: String!) {
    insert_posts(objects: { body: $body, title: $title }) {
      affected_rows
    }
  }
`;

function NewPost() {
  const [title, setTitle] = React.useState("");
  const [body, setBody] = React.useState("");
  const [createPost, { loading, error }] = useMutation(CREATE_POST);

  function handleCreatePost(event) {
    event.preventDefault();
    // the mutate function also doesn't return a promise
    createPost({ variables: { title, body } });
  }

  return (
    <div>
      <h1>New Post</h2>
      <form onSubmit={handleCreatePost}>
        <input onChange={(event) => setTitle(event.target.value)} />
        <textarea onChange={(event) => setBody(event.target.value)} />
        <button disabled={loading} type="submit">
          Submit
        </button>
        {error && <p>{error.message}</p>}
      </form>
    </div>
  );
}

Unlike with queries, however, we don't use loading or error in order to conditionally render something. We generally use loading in such situations as when we're submitting a form to prevent it being submitted multiple times, to avoid executing the same mutation needlessly (as you can see in the example above).

We use error to display what goes wrong with our mutation to our users. If for example, some required values to our mutation are not provided, we can easily use that error data to conditionally render an error message within the page so the user can hopefully fix what's going wrong.

As compared to passing variables to the second argument of useMutation, we can access a couple of useful callbacks when certain things take place, such as when the mutation is completed and when there is an error. These callbacks are named onCompleted and onError.

The onCompleted callback gives us access to the returned mutation data and it's very helpful to do something when the mutation is done, such as going to a different page. The onError callback gives us the returned error when there is a problem with the mutation and gives us other patterns for handling our errors.

const [createPost, { loading, error }] = useMutation(CREATE_POST, {
  onCompleted: (data) => console.log("Data from mutation", data),
  onError: (error) => console.error("Error creating a post", error),
});

useSubscription Hook

The useSubscription hook works just like the useQuery hook.

useSubscription returns an object that we can destructure, that includes the same properties, loading, data, and error.

It executes our subscription immediately when the component is rendered. This means we need to handle loading and error states, and only afterwards display/use our data.

import { useSubscription } from "@apollo/react-hooks";
import gql from "graphql-tag";

const GET_POST = gql`
  subscription GetPost($id: uuid!) {
    posts(where: { id: { _eq: $id } }) {
      id
      body
      title
      createdAt
    }
  }
`;

// where id comes from route params -> /post/:id
function PostPage({ id }) {
  const { loading, error, data } = useSubscription(GET_POST, {
    variables: { id },
    // shouldResubscribe: true (default: false)
    // onSubscriptionData: data => console.log('new data', data)
    // fetchPolicy: 'network-only' (default: 'cache-first')
  });

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error!</div>;

  const post = data.posts[0];

  return (
    <div>
      <h1>{post.title}</h1>
      <p>{post.body}</p>
    </div>
  );
}

Just like useQuery, useLazyQuery and useMutation, useSubscription accepts variables as a property provided on the second argument.

It also accepts, however, some useful properties such as shouldResubscribe. This is a boolean value, which will allow our subscription to automatically resubscribe, when our props change. This is useful for when we're passing variables to our you subscription hub props that we know will change.

Additionally, we have a callback function called onSubscriptionData, which enables us to call a function whenever the subscription hook receives new data. Finally, we can set the fetchPolicy, which defaults to 'cache-first'.

Manually Setting the Fetch Policy

What can be very useful about Apollo is that it comes with its own cache, which it uses to manage the data that we query from our GraphQL endpoint.

Sometimes, however, we find that due to this cache, things aren't updated in the UI in the way that we want.

In many cases we don't, as in the example below, where we are editing a post on the edit page, and then after editing our post, we navigate to the home page to see it in a list of all posts, but we see the old data instead:

// route: /edit/:postId
function EditPost({ id }) {
  const { loading, data } = useQuery(GET_POST, { variables: { id } });
  const [title, setTitle] = React.useState(loading ? data?.posts[0].title : "");
  const [body, setBody] = React.useState(loading ? data?.posts[0].body : "");
  const [updatePost] = useMutation(UPDATE_POST, {
    // after updating the post, we go to the home page
    onCompleted: () => history.push("/"),
  });

  function handleUpdatePost(event) {
    event.preventDefault();
    updatePost({ variables: { title, body, id } });
  }

  return (
    <form onSubmit={handleUpdatePost}>
      <input
        onChange={(event) => setTitle(event.target.value)}
        defaultValue={title}
      />
      <input
        onChange={(event) => setBody(event.target.value)}
        defaultValue={body}
      />
      <button type="submit">Submit</button>
    </form>
  );
}

// route: / (homepage)
function App() {
  const { loading, error, data } = useQuery(GET_POSTS, {
    variables: { limit: 5 },
  });

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error!</div>;

  // updated post not displayed, still see old data
  return data.posts.map((post) => <Post key={post.id} post={post} />);
}

This not only due to the Apollo cache, but also the instructions for what data the query should fetch. We can changed how the query is fetched by using the fetchPolicy property.

By default, the fetchPolicy is set to 'cache-first'. It's going to try to look at the cache to get our data instead of getting it from the network.

An easy way to fix this problem of not seeing new data is to change the fetch policy. However, this approach is not ideal from a performance standpoint, because it requires making an additional request (using the cache directly does not, because it is local data).

There are many different options for the fetch policy listed below:

{
  fetchPolicy: "cache-first"; // default
  /* 
    cache-and-network
    cache-first
    cache-only
    network-only
    no-cache
    standby
  */
}

I won't go into what each policy does exactly, but to solve our immediate problem, if you always want a query to get the latest data by requesting it from the network, we set fetchPolicy to 'network-first'.

const { loading, error, data } = useQuery(GET_POSTS, {
  variables: { limit: 5 },
  fetchPolicy: "network-first"
});

Updating the cache upon a mutation

Instead of bypassing the cache by changing the fetch policy of useQuery, let's attempt to fix this problem by manually updating the cache.

When performing a mutation with useMutation. We have access to another callback, known as update.

update gives us direct access to the cache as well as the data that is returned from a successful mutation. This enables us to read a given query from the cache, take that new data and write the new data to the query, which will then update what the user sees.

Working with the cache manually is a tricky process that a lot of people tend to avoid, but it's very helpful because it saves some time and resources by not having to perform the same request multiple times to update the cache manually.

function EditPost({ id }) {
  const [updatePost] = useMutation(UPDATE_POST, {
    update: (cache, data) => {
      const { posts } = cache.readQuery(GET_POSTS);
      const newPost = data.update_posts.returning;
      const updatedPosts = posts.map((post) =>
        post.id === id ? newPost : post
      );
      cache.writeQuery({ query: GET_POSTS, data: { posts: updatedPosts } });
    },
    onCompleted: () => history.push("/"),
  });

  // ...
}

We first want to read the query and get the previous data from it. Then we need to take the new data. In this case, to find the post with a given id and replace it with newPost data, otherwise have it be the previous data, and then write that data back to the same query, making sure that it has the same data structure as before.

After all this, whenever we edit a post and are navigated back to the home page, we should see that new post data.

Refetching queries with useQuery

Let's say we display a list of posts using a GET_POSTS query and are deleting one of them with a DELETE_POST mutation.

When a user deletes a post, what do we want to happen?

Naturally, we want it to be removed from the list, both the data and what is displayed to the users. When a mutation is performed, however, the query doesn't know that the data is changed.

There are a few ways of updating what we see, but one approach is to reexecute the query.

We can do so by grabbing the refetch function which we can destructure from the object returned by the useQuery hook and pass it down to the mutation to be executed when it is completed, using the onCompleted callback function:

function Posts() {
  const { loading, data, refetch } = useQuery(GET_POSTS);

  if (loading) return <div>Loading...</div>;

  return data.posts.map((post) => (
    <Post key={post.id} post={post} refetch={refetch} />
  ));
}

function Post({ post, refetch }) {
  const [deletePost] = useMutation(DELETE_POST, {
    onCompleted: () => refetch(),
  });

  function handleDeletePost(id) {
    if (window.confirm("Are you sure you want to delete this post?")) {
      deletePost({ variables: { id } });
    }
  }

  return (
    <div>
      <h1>{post.title}</h1>
      <p>{post.body}</p>
      <button onClick={() => handleDeletePost(post.id)}>Delete</button>
    </div>
  );
}

Refetching Queries with useMutation

Note that we can also utilize the useMutation hook to reexecute our queries through an argument provided to the mutate function, called refetchQueries.

It accepts an array of queries that we want to refetch after a mutation is performed. Each queries is provided within an object, just like we would provide it to client.query(), and consists of a query property and a variables property.

Here is a minimal example to refetch our GET_POSTS query after a new post is created:

function NewPost() {
  const [createPost] = useMutation(CREATE_POST, {
    refetchQueries: [
      { 
        query: GET_POSTS, 
        variables: { limit: 5 } 
      }
    ],
  });

  // ...
}

Using the client with useApolloClient

We can get access to the client across our components with the help of a special hook called use Apollo client. This execute the hook at the top of our function component and we get back the client itself.

function Logout() {
  const client = useApolloClient();
  // client is the same as what we created with new ApolloClient()

  function handleLogout() {
    // handle logging out user, then clear stored data
    logoutUser();
    client.resetStore().then(() => console.log("logged out!"));
    /* Be aware that .resetStore() is async */
  }

  return <button onClick={handleLogout}>Logout</button>;
}

And from there we can execute all the same queries, mutations, and subscriptions.

Note that there are a ton more features that come with methods that come with the client. Using the client, we can also write and read data to and from the cache that Apollo sets up (using client.readData() and client.writeData()).

Working with the Apollo cache deserves its own crash course in itself. A great benefit of working with Apollo is that we can also use it as a state management system to replace solutions like Redux for our global state. If you want to learn more about using Apollo to manage global app state you can check out the following link.

I attempted to make this cheatsheet as comprehensive as possible, though it still leaves out many Apollo features that are worth investigating.

If you want to more about Apollo, be sure to check out the official Apollo documentation.

Download the cheatsheet

Want a quick reference of all of these concepts?

Click to grab the complete PDF cheatsheet

Become a Professional React Developer

React is hard. You shouldn't have to figure it out yourself.

I've put everything I know about React into a single course, to help you reach your goals in record time:

Introducing: The React Bootcamp

It’s the one course I wish I had when I started learning React.

Click below to try the React Bootcamp for yourself:

Click to get started

Within an afternoon, you will gain the core skills to build your own React and GraphQL projects.

Why you should learn React with GraphQL ?

React is the go-to library for building amazing app experiences with JavaScript. GraphQL, on the other hand, is a tool that gives us a better, more straightforward means of getting and changing our data.

That data could be from a standard database (as we'll be using in our app) or as React frameworks like Gatsby have made possible, even from static files such as markdown files. Regardless of how it's stored, GraphQL makes working with data in our apps better.

We'll see how to leverage the powers of React and GraphQL by creating a social blogging app from start to finish, where you can create, read, edit and delete posts.

You can click here to access the course.

What tools we'll be using ?️

The crash course is meant for developers who are somewhat familiar with React (including the core React Hooks, such as useState and useEffect), but aren't familiar with GraphQL yet.

Basic React knowledge is assumed, but GraphQL knowledge is not required. We'll cover all the core GraphQL concepts you need along the way.

Throughout the course, we'll utilize the following technologies to create our app:

• React (to build our user interface)
• GraphQL (to get and change data in a declarative way)
• Apollo Client (to allow us to use React and GraphQL together)
• Hasura (to create and manage our GraphQL API + database)

To top it off, we'll be using the online IDE CodeSandbox. This will allow us to code our entire application within the browser in realtime, without the need to create any files, folders, or install dependencies on our own.

Creating a GraphQL API from scratch

To get started working with GraphQL, we'll see how to make an entire GraphQL API from scratch that will communicate with our database.

Fortunately, using the (free) service Hasura, this process is very simple and straightforward. Within seconds, we'll see how to create and deploy a complete GraphQL API to the web, which is connected to a Postgres database that will take care of storing our app data.

Click to watch this lecture

Getting familiar with GraphQL

In the second lecture, we'll cover how to write in the GraphQL language using our API's built-in console called GraphiQL.

First, we will create a table in our database for all of our posts data. After which, Hasura will automatically create the queries and mutations we need, which are the names of GraphQL operations that allow us to get and change data in our database.

Throughout this lesson, we'll get very familiar performing queries and mutations in GraphiQL, which will enable us to get entire sets of posts and individual posts, as well as to create, update, and delete our individual post data.

Click to watch this lecture

Connecting React with our GraphQL API using Apollo Client

Now that we're comfortable with using GraphQL and understand its core features, we'll see how to connect it with our React client.

The way that we connect our React app with the GraphQL API we created is through a library called Apollo. We'll see how to set up the Apollo client, by providing the GraphQL endpoint, which points to our API, like so:

import ApolloClient from "apollo-boost";

const client = new ApolloClient({
  uri: "https://react-graphql.herokuapp.com/v1/graphql"
});

With our newly created client, we have the ability to execute any GraphQL operation through React. To do this, however, we need to pass our client to our entire to all of our React components. We do that with the help of the Apollo provider, as you see below:

Click to watch this lecture

Getting posts with useQuery

After setting up our client, we'll see how to execute different GraphQL operations with them, using some special React hooks that come with the package @apollo/react-hooks.

The hook that allows us to query for data with GraphQL is called useQuery. With it, we'll first see how to get and display all of our post data in our homepage.

Additionally, we'll learn how to write our GraphQL queries directly in our JavaScript files with the help of a special function called gql.

import React from "react";
import { useQuery } from "@apollo/react-hooks";
import { gql } from "apollo-boost";

export const GET_POSTS = gql`
  query getPosts {
    posts {
      id
      title
      body
      createdAt
    }
  }
`;

function App() {
  const { data, loading } = useQuery(GET_POSTS);

  if (loading) return <div>Loading...</div>;
  if (data.posts.length === 0) return <Empty />;

  return (
    <>
      <header className={classes.header}>
        <h2 className={classes.h2}>All Posts</h2>
        <Link to="/new" className={classes.newPost}>
          New Post
        </Link>
      </header>
      {data.posts.map(post => (
        <Post key={post.id} post={post} />
      ))}
    </>
  );
}

Creating and editing new posts with useMutation

After that, we'll see how to create new posts with the useMutation hook. In order to do this, we'll take a look at how to work with GraphQL variables to pass our mutation dynamic values that will change with each execution.

Following that we'll take a look at how to edit our posts. To do so, we'll need to fetch an individual post and display it within our form, so that our user can make changes to the data. Then we'll need to execute a mutation that will perform the update, based on the posts id.

Click to watch this lecture

Handle loading and errors

In the following lecture, we'll cover some essential patterns for handling the process of loading our data.

It's important to do so when we execute a mutation, to make sure we don't submit our forms multiple times as our mutation is being executed. We'll also take a look at how to handle errors in the event that our mutation is not executed correctly.

Click to watch this lecture

Deleting posts

Finally, we'll cover how to delete posts from our app. First, we'll confirm that the user wants to actually delete the post that they've made, then perform the mutation.

Additionally, we'll take a look at how to update our UI in response to mutations with the helpful refetch function that Apollo gives us. It will enable us to re-execute a query on demand. In this case, we'll do it after the delete mutation has been successfully performed.

Click to watch this lecture

Become a Professional React Developer

React is hard. You shouldn't have to figure it out yourself.

I've put everything I know about React into a single course, to help you reach your goals in record time:

Introducing: The React Bootcamp

It’s the one course I wish I had when I started learning React.

Click below to try the React Bootcamp for yourself:

Click to get started

Apollo Client is a complete state management library for JavaScript apps. It's a powerful tool since it can be used on both the back end and front end side.

In this tutorial, we will use it on the front end and back end by building an Apollo GraphQL Server with Node JS. Then we will consume the data on the client-side using React JS.

If you're new to GraphQl, this tutorial might help you. Otherwise, let's get started.

• Building the server with Apollo, Node, and GraphQl
• GraphQl Schema
• GraphQl resolvers
• Creating the Apollo Server
• Building the Client-side with React
• Connecting React to Apollo
• Fetching the data
• Showing the data

Building the server with Apollo, Node, and GraphQl

In this guide, I will use the Github API to have data to show, and that operation will be done by the GraphQl server built with Apollo and Node JS.

To make this happen, we need to run the following command on the terminal to set up a new Node JS project:

  yarn init

Once the set up is done, we can now install the necessary packages by running this command:

  yarn add apollo-server graphql axios

Great, we now have all we need to build a server. So first let's create a new file app.js in the root which will be the entry point of our server.

Next, we need to define a Graphql schema that mirrors the way our data should look.

GraphQl Schema

A schema describes the shape of your data graph. It defines a set of types with fields that are populated from your back-end data stores. So, let's add a new schema in the app.js file.

• app.js

const { ApolloServer, gql } = require("apollo-server")
const axios = require("axios")

const typeDefs = gql`
  type User {
    id: ID
    login: String
    avatar_url: String
  }

  type Query {
    users: [User]
  }
`

As you can see we don't use all data provided by the Github API. We just need the id that will be used as a reference key on the React App, the login, and the avatar_url. We also have a query users that returns an array of users.

Now that we have a GraphQL schema, it's time to build the corresponding resolvers to complete the query operation.

GraphQl resolvers

A resolver is a collection of functions that helps generate a response from a GraphQL query. So, let's add a new resolver in the app.js file.

• app.js

const resolvers = {
  Query: {
    users: async () => {
      try {
        const users = await axios.get("https://api.github.com/users")
        return users.data.map(({ id, login, avatar_url }) => ({
          id,
          login,
          avatar_url,
        }))
      } catch (error) {
        throw error
      }
    },
  },
}

A resolver has to match the appropriate schema by name. Therefore, here users refers to the users query defined in our schema. It's a function that fetches the data from the API with the help of axios and returns as expected the id, the login, and the avatar_url.

And that operation can take time to complete. That's why async/await is used here to handle it.

With that, we can now create the Apollo Server in the next section.

Creating the Apollo Server

If you remember, in the app.js file, we had imported ApolloServer from the apollo-server package. It's a constructor that receives an object as an argument. And that object must contain the schema and the resolver to be able to create the server.

So, let's tweak app.js a bit with ApolloServer.

• app.js

const server = new ApolloServer({
  typeDefs,
  resolvers,
})
//  typeDefs: typeDefs,
//  resolvers: resolvers
server.listen().then(({ url }) => console.log(`Server ready at ${url}`))

Here, we pass as a parameter an object that holds the schema and the resolver to ApolloServer to create the server and then listens to it. With that in place, we now have a functional server to work with.

You can already play with it and send queries with the help of GraphQL playground by running this command:

  yarn start

You can now preview it on http://localhost:400

• The complete app.js file

const { ApolloServer, gql } = require("apollo-server")
const axios = require("axios")

const typeDefs = gql`
  type User {
    id: ID
    login: String
    avatar_url: String
  }

  type Query {
    users: [User]
  }
`

const resolvers = {
  Query: {
    users: async () => {
      try {
        const users = await axios.get("https://api.github.com/users")
        return users.data.map(({ id, login, avatar_url }) => ({
          id,
          login,
          avatar_url,
        }))
      } catch (error) {
        throw error
      }
    },
  },
}

const server = new ApolloServer({
  typeDefs,
  resolvers,
})

server.listen().then(({ url }) => console.log(`Server ready at ${url}`))

A server alone does not do much. We need to add a start script in the package.json file to, as you guessed, start the server.

• package.json

  // first add nodemon: yarn add nodemon --dev
  "scripts": {
    "start": "nodemon src/index.js"
  }

With that, we have a server to fetch data from the Github API. So now it's time to move to the client-side and consume the data.

Let's do it.

Building the Client-side with React

The first thing we have to do is create a fresh React App by running the following command in the terminal:

npx create-react-app client-react-apollo

Next, we need to install the Apollo and GraphQl packages:

  yarn add apollo-boost @apollo/react-hooks graphql

Now, we can connect Apollo with our React App by updating the index.js file.

Connecting React to Apollo

• index.js

import React from 'react';
import ReactDOM from 'react-dom';
import ApolloClient from 'apollo-boost'
import { ApolloProvider } from '@apollo/react-hooks';

import App from './App';
import './index.css';
import * as serviceWorker from './serviceWorker';

const client = new ApolloClient({
  uri: 'https://7sgx4.sse.codesandbox.io'
})


ReactDOM.render(
  <React.StrictMode>
    <ApolloProvider client={client}>
      <App />
    </ApolloProvider>
  </React.StrictMode>,
  document.getElementById('root')
);

serviceWorker.unregister();

As you can see, we start by importing ApolloClient and ApolloProvider. The first helps us inform Apollo about which URL to use when fetching data. And if no uri is passed to ApolloClient, it will take the current domain name plus /graphql.

The second is the Provider which expects to receive the client object to be able to connect Apollo to React.

That said, we can now create a component that shows the data.

Fetching the data

• App.js

import React from "react"
import { useQuery } from "@apollo/react-hooks"
import gql from "graphql-tag"
import "./App.css"

const GET_USERS = gql`
  {
    users {
      id
      login
      avatar_url
    }
  }
`

Here, we have a simple GraphQL query that fetches the data. That query will be passed later to useQuery to tell Apollo which data to fetch.

• App.js

const User = ({ user: { login, avatar_url } }) => (
  <div className="Card">
    <div>
      <img alt="avatar" className="Card--avatar" src={avatar_url} />
      <h1 className="Card--name">{login}</h1>
    </div>
    <a href={`https://github.com/${login}`} className="Card--link">
      See profile
    </a>
  </div>
)

This presentational component will be used to display a user. It receives the data from the App component and displays it.

Showing the data

• App.js

function App() {
  const { loading, error, data } = useQuery(GET_USERS)

  if (error) return <h1>Something went wrong!</h1>
  if (loading) return <h1>Loading...</h1>

  return (
    <main className="App">
      <h1>Github | Users</h1>
      {data.users.map(user => (
        <User key={user.id} user={user} />
      ))}
    </main>
  )
}

export default App

The useQuery hook provided by Apollo receives the GraphQL query and returns three states: the loading, the error, and the data.

If the data are successfully fetched, we pass it to the User component. Otherwise we throw an error.

• The complete App.js file

import React from "react"
import { useQuery } from "@apollo/react-hooks"
import gql from "graphql-tag"
import "./App.css"

const GET_USERS = gql`
  {
    users {
      id
      login
      avatar_url
    }
  }
`

const User = ({ user: { login, avatar_url } }) => (
  <div className="Card">
    <div>
      <img alt="avatar" className="Card--avatar" src={avatar_url} />
      <h1 className="Card--name">{login}</h1>
    </div>
    <a href={`https://github.com/${login}`} className="Card--link">
      See profile
    </a>
  </div>
)

function App() {
  const { loading, error, data } = useQuery(GET_USERS)

  if (error) return <h1>Something went wrong!</h1>
  if (loading) return <h1>Loading...</h1>

  return (
    <main className="App">
      <h1>Github | Users</h1>
      {data.users.map(user => (
        <User key={user.id} user={user} />
      ))}
    </main>
  )
}

export default App

Great! With that, we are now done building a full-stack Apollo GraphQL app using React and Node JS.

Preview the Apollo GraphQL Server here

Preview the React App here

Find the source code here

You can find other great content like this on my blog

Thanks for reading!

You can get a lot done in 2 minutes, like microwaving popcorn, sending a text message, eating a cupcake, and hooking up a GraphQL server.

Yup. If you have an old Express.js RESTful API lying around or you're interested in incrementally adopting GraphQL, we only need 2 minutes to hook it up with a fresh new GraphQL Server.

Ready? Set. Go!

Let's say that your server looked something like the following.

import express from 'express';
import { apiRouter } from './router';

const app = express();
const port = process.env.PORT || 5000;

// Existing routes for our Express.js app
app.use('/api/v1', apiRouter);

app.listen(port, () => console.log(`[App]: Listening on port ${port}`))

At the root of your project, npm install apollo-server-express as a dependency.

npm install apollo-server-express --save

Go to where your Express app is defined and import ApolloServer and gql from apollo-server-express.

import { ApolloServer, gql } from 'apollo-server-express'

Next, create an instance of an ApolloServer with the simplest possible GraphQL type definitions and resolvers.

const server = new ApolloServer({
  typeDefs: gql`
    type Query {
      hello: String
    }
  `,
  resolvers: {
    Query: {
      hello: () => 'Hello world!',
    },
  }
})

Lastly, use ApolloServer's applyMiddleware method to pass in our Express.js server.

server.applyMiddleware({ app })

Boom. That's it!

Your code should look something like this.

import express from 'express';
import { v1Router } from './api/v1';
import { ApolloServer, gql } from 'apollo-server-express'

const app = express();
const port = process.env.PORT || 5000;

const server = new ApolloServer({
  typeDefs: gql`
    type Query {
      hello: String
    }
  `,
  resolvers: {
    Query: {
      hello: () => 'Hello world!',
    },
  }
})

server.applyMiddleware({ app })

app.use('/api/v1', v1Router);

app.listen(port, () => {
  console.log(`[App]: Listening on port ${port}`)
})

If you navigate to localhost:5000/graphql, you should be able to see your GraphQL schema in the GraphQL playground.

Note: If you want to change the URL that the GraphQL endpoint sits at from /graphql to something else, you can pass in a path option to server.applyMiddleware() with the URL you want, like path: '/specialUrl'. Check out the docs for full API usage.

How simple was that? Is your popcorn finished? ?

Summary

Here's what we did.

1. Install apollo-server-express
2. Create a new ApolloServer
3. Connect your GraphQL Server with server.applyMiddleware

I personally really love the fact that Apollo Server is non-intrusive and can be tacked on any project as an alternative way to communicate between services and applications.

Where to go from here

If you're new to Apollo and GraphQL, a great way to learn is to actually build something in real life. For that reason, I highly recommend checking out the Apollo Fullstack Tutorial (you can also learn in TypeScript now ?).

I'm Khalil Stemmler, a Developer Advocate at Apollo GraphQL. I teach advanced TypeScript, GraphQL, and Node.js best practices for large-scale applications. Feel free to ping me on Twitter if you need help with anything Apollo, TypeScript, or architecture-related. Cheers ?

The NRG stack for faster development

You've probably never heard of either Vulcan.js or Apollo Universal Starter Kit – at least not yet.

But I am pretty sure you've heard about React, Node.js and GraphQL. Okay, that’s what we call an understatement: you’ve likely seen millions of tweets, blog articles, meetups and podcasts about those three and their magical powers.

Sums up 2017-2020 in one tweet

There are a lot of good reasons why those technologies are praised by web developers. Yet, if you ever tried to write a modern full-stack JavaScript application from scratch, you may have noticed the amount of boilerplate it can produce.

This is especially annoying with generic features: setting up authentication, setting up the database, setting up the main App component, setting up the settings…

Both Vulcan.js and AUSK aim to make you a fast and efficient full-stack JavaScript developer. Both rely on a modular architecture, with React for the UI, Node for the backend, and Apollo graphQL for the client/server communication layer. Both provide tons of pre-coded modules so you can focus on valuable features.

However, they each take very different approaches to the problem, so I thought you might enjoy a comparison.

First of all let’s introduce the competitors.

Disclaimer: I am a contributor of Vulcan.js, however I used both of those technologies for my client’s projects so I’ll stay as objective as can be.

Apollo UNIVERSAL Starter Kit

Okay, when they say universal, they mean UNIVERSAL. Have you ever seen a JavaScript boilerplate that includes a Scala server for big work? And a full React Native setup with Expo? They even close the eternal (and annoying) Angular versus React debate by supporting both.

Technologies included in AUSK: Node, Scala, React, Angular and React Native, all tied by GraphQL. Kind of the Oscar ceremony of modern web development.

I don’t have much else to say. I mean, look again at this stack, that’s a web developer’s wildest dream!

I actually have something to add: it also includes Bootstrap and Ant Design as styling frameworks, Knex to connect to SQL database (MongoDB connection is not included but easily doable), and it’s written in TypeScript. All core features of a JS/GraphQL application are provided in the boilerplate (menu, auth, etc.)+ a few higher level modules that serve as examples.

Link: https://github.com/sysgears/apollo-universal-starter-kit

Vulcan: beyond universal, isomorphic

Remember Meteor and Telescope? I know the JS ecosystem moves fast, but this golden era was like only 2 or 3 years ago.

Meteor was the first framework to fully exploit the combination of server-side and client-side JavaScript, by allowing to write isomorphic code that runs on both environment. Telescope was a Meteor boilerplate app meant to fully enjoy its package-oriented architecture.

Though still used in many professional apps and known by a whole lot of developers, Meteor is crippled by some technical limitations that prevents a wider usage: its webpack-incompatible build system, its package manager that is now surpassed by NPM, or its RAM-consuming real-time data exchange protocol.

And I am yet to discover a framework that makes devs half as productive as Meteor. But don’t worry, there’s now a serious contender. You get it : Vulcan !

The use of Apollo GraphQL and a rational package-oriented architecture allow Vulcan to overcome Meteor's limitations while enjoying the same advantages: fully modular architecture, declarative programming, isomorphism and so on.

Vulcan is meant to be the Rails of the JavaScript ecosystem. Easy to get started with but complete enough to write any app.

Check my previous article for a more complete description of Vulcan patterns targeting development speed.

Link: http://vulcanjs.org/

#1: Framework VS Boilerplate

First major difference between these tools: AUSK is a boilerplate, while Vulcan is a framework. Where does the distinction lie, you may wonder?

Vulcan, a framework

A framework is meant to make you a more efficient developer on a daily basis by providing a specific set of functions and helpers. It is usually designed to stay separate from your app. You can update your app from time-to-time whenever a new version of the framework is published.

We usually distinguish frameworks and librairies based on the level of specialization. A framework usually allows delivering business-level features, while a library is a more specialized technical tool. But both mostly works the same.

The limitation with frameworks or libs is that you may feel lost when they abandon you. What do you do when the bug is not in your app, but in React or Apollo?

My rule of thumb is that when using a framework, you should be ready to contribute to its development, at least by opening issues whenever you encounter a bug.

AUSK, a boilerplate

A boilerplate is a well written piece of code with a fully working development environment. That’s all. With a boilerplate it’s harder to keep up with updates because the boilerplate code is not clearly separated from your app. Kind of like Create React App after you eject.

It usually provides only few custom methods. You will feel faster in the first month and you will benefit from a battle-tested architecture, but your cruise speed will end up being mostly the same than without a boilerplate.

A boilerplate is far more freedom than a framework but also less impact on your efficiency.

#2 Learning Curve

Vulcan: GraphQL made easy

Vulcan can be a good way to get a first grasp of GraphQL because… you don’t need to actually write GraphQL. The framework generates the GraphQL schema and resolvers for you based on your data model. Using developer tools like GraphiQL or GraphQL Voyager, you can visualize and play around with the schema to get a grasp of how your features translate into GraphQL.

The second step is to understand the logic of Vulcan itself. A live tutorial is included in the “Vulcan Starter” app to help you in the process.

AUSK: for purists

AUSK architecture is far closer to what Express developers are used to. Think of your canonical Express app, but with GraphQL installed and a package-based architecture. No surprises.

This also means that you’ll need to grasp the basics of GraphQL to use AUSK, in addition of course to Node, Express and React and whatever database you use (but the same goes for Vulcan). Luckily, it provides a few examples to help you in the process, including creating and listing data and even uploading files.

Conclusion: Full-stack devs have a lot to master

The JavaScript ecosystem is maturing more and more, which also means it is harder to learn and understand for beginners.

To fully enjoy those technologies, you’ll need at least some knowledge of modern JavaScript and React development.

Don’t expect to be fully productive at day one. That said, there are pleeenty of courses, free or paid, to learn modern full-stack JavaScript development. Studying AUSK and Vulcan can be an incredible source of inspiration.

#3 Development speed

Vulcan: automate all the things

When well used, Vulcan is just incredibly fast at delivering features. This is because it relies on automated generation a lot, so it can produces the most relevant parts of an app in a matter of hours as long as your data model is correctly defined.

This pattern is called declarative programming: you “declare” how your app works and let the framework do the job. It’s difficult to implement but can be extremely powerful.

AUSK: more freedom

Since AUSK is boilerplate-focused, it’s a bit tougher to add basic features as it’s a multi-step process:

• write your GraphQL schema
• same for resolvers, mutations
• same for your database model (using Knex or Mongoose)
• same for your React components
• …

However, if you need to write a custom feature, it’s gonna be easier with AUSK than with Vulcan. So if you have very few data models but complex features, AUSK will be more efficient than Vulcan.

Hopefully there are ongoing work to make AUSK more declarative, through an innovative Domain Driven Design inspired schema system, domain-schema.

Conclusion: select the right tool for the right use case

There’s no magical universal technology for full-stack JS development. The development speed with each framework depends a lot on the underlying use case. I tend to prefer Vulcan for data-oriented platforms and professional tools, and AUSK for B2C SaaS platforms that require more custom features.

#4 Community, support and maturity

Vulcan: heir of Meteor

Vulcan is a framework from Sacha Greif, who is a long time Meteor developer and very invested in the JavaScript community (State of JS and State of CSS among other things).

There is an active Slack where beginners and other enthusiasts can quickly find answers to their questions.

AUSK: an actively maintained project

AUSK is maintained by SysGears, in particular by Victor Vlasenko, the founder of the company.

The project is associated with Gitter. During my latest freelance mission with AUSK, Victor responded very quickly to my issues and questions. He even merged the Storybook support after I gave it a shot.

Conclusion: small but rich communities

Both technologies are used in production in multiple projects, so they are already safe to use. The communities are growing actively and beginner-friendly.

If you need to build a team, don’t expect to find freelancers that precisely know those technologies, they are too specific. Instead focus on finding full-stack JavaScript developers who will be able to quickly learn them. Alternatively, you can go to the source and find true specialists among the Vulcan or AUSK communities.

#5 Deployment

Not much to compare, both frameworks allow deployment on platforms offering free services like Zeit Now and Heroku as well as deployment on your own custom server.

#6 Code scalability and modular patterns

Vulcan: share efforts

One advantage of a framework is effort sharing. End usage is clearer, and thus allows us to integrate various optimizations within the framework itself.

Vulcan provides patterns like callbacks/hooks, enhancement and central registration to fully benefit from its package-oriented architecture. For example, we are able to add Material UI to an app, including SSR, without changing a single line of code in the Vulcan Core module.

More precisely, Vulcan provides different register methods for each data structure, like registerComponent , and also callbacks, like router.wrapper that allow to wrap the root App React component. You only need to import your file once at the package entry level ( main files).

AUSK: start on the right track, finish by yourself

The modular architecture limits the temptation of writing spaghetti code. It favors code reuse across applications. Each package possesses an index.ts file that declares relevant middlewares, startup functions, graphQL functions shared with other modules.

The well-named module module provides classes for each environment to register a new module, like ServerModule and ClientModule . That’s the only module that is actually used directly at the app level.

export default new ServerModule({
    onAppCreate: [ callback1, callback2]
})

Internally all modules will be merged into one big module, that will eventually be used to create the app. For example, all onAppCreate callbacks will be run one after the other.

That’s a relatively clean pattern and a very smart architecture. I mean, even the module manager is a module, isn’t that beautiful?

But the rest is up to you. Nice, you’ll be able to optimize everything! So, are you going to loose couple your GraphQL resolvers and your Mongo database? Using which tools? How do you convert your GraphQL schema into Mongo projections? Are you going to write connectors, use DataLoader?

Here’s the point: writing a scalable app is hard. Very hard. If you want to learn, then good for you. I am very glad to use AUSK for this very reason, doing things by yourself is the best way to learn.

Conclusion: are you risk-averse?

For both AUSK and Vulcan, code scalability means a modular architecture. Whenever code becomes too complex or unreadable, the solution is easy: cut it into smaller, simpler pieces.

Vulcan architecture is bolder, everything can be modular. This ambition comes at a risk, it may sometimes be difficult to get who registered what and when.

AUSK modular patterns are easier to read, but also a bit less powerful. It may for example be difficult to add complex global features without touching the core package code. Yet they are definitely sufficient for most use cases, you don’t have to be a modularity purist to write good apps.

#6 Mobile

Vulcan: with Cordova

Meteor, which Vulcan is based on, embeds Cordova. So your web app can be bundled as a mobile application with a single command line.

However Vulcan does not provide tools for native apps. Of course you can still create an independent React Native app and plug it to Vulcan. Improvements on the auth system (currently the last piece of Vulcan really relying on Meteor) are planned in the months to come to facilitate such connections.

AUSK: with React Native

Combining both a setup for “vanilla” React and React Native is one of the best features of AUSK. After all, it’s a Universal starter kit! I don’t do much mobile myself but it’s reassuring to be able to quickly create a native mobile app sharing the same server as my web interface.

Conclusion: AUSK is better at mobile-first

AUSK will be more suited if you specifically need to write a mobile app. Nonetheless Vulcan allows to build a mobile app from your code in just one command-line, which is okay if the mobile version is more secondary to you.

#7 Change the UI: a tough issue

Creating a fullstack framework that allows instantaneous UI library change is a dream only achieved during the era of CSS. Remember those websites that allowed to switch theme by clicking on a single button?

“What logo can we pick for our nice CSS-in-JS lib?” “I don’t know, kind of a badass warrior woman?” “Yeah it makes total sense” — creators of Emotion, probably

Then the JS nations attacked. Using React components, it is very difficult to provide such a feature (except for trivial color changes), because style and design is now very tied to the underlying React/Angular/Vue components.

Each React UI lib has its own way to define a button, without even speaking about theming. That’s a problem for full-stack technologies like AUSK and Vulcan, because picking a styling framework is a matter of taste. They can’t just propose a definitive choice and force you to stick to it. Bootstrap is no longer at monopoly and each developer has their own favorite lib.

To tackle this issue, both have a similar approach. They wrote a canonical set of components with Bootstrap, then tried to allow the replacement of those components with another lib like Ant Design or Material UI.

It makes the code weird. For example, AUSK Button will take a color prop, because it is how Bootstrap work. If you switch to Ant Design, you will also need to use the color prop, even if Ant Design uses a type prop instead.

Since UI framework selection usually happens only once, being obligated to use a non-canonical set of props during all the developments seems a very high price for multiple UI framework support.

During development, I’d suggest to avoid using those pre-coded components for custom UI as much as possible. They are cool to build the example and generic features provided by the boilerplate/framework, but not that much when it comes to write the custom parts of your app.

Instead use the underlying components provided by Ant Design or Bootstrap or Material UI depending on your choice, and try to write your own UI lib. You could checkout Storybook to help you in the process, as it is included in both AUSK and Vulcan.

#8 FREE FIGHT

If I were to retain differentiating features specific to each of these technologies, they would be these.

Vulcan

The schema system. To my best knowledge, no framework is able to generate the database structure, the server entry points, the client/server communication layer, and a production-ready frontend (forms, lists etc.) from a single JSON schema.

Vulcan.js can do that while using the latest JS technologies.

AUSK

I did not manage to pick only one, so my loved features of AUSK would be TypeScript and React Native.

There has been debates for a few years around the benefits of statically typed JavaScript, whether to prefer Flow or TypeScript… And TypeScript definitely won the fight. Working with TypeScript is possible in Vulcan but, due to the use of Meteor, is currently feels unnatural and compilation is slow. AUSK uses TypeScript as a default and that’s awesome.

And React Native… well, there are also debates whether using React to write mobile apps is relevant. You may choose to stick to a responsive web app, but at least you know everything is setup for you, given that configuring a dev env for React Native is not always an easy task.

So, have you made your choice?

There are so many points that should be taken into consideration like performance, security, DevOps, auth management… Picking the right tool to build your JavaScript app is certainly not an easy choice. I hope that this article gave you valuable insights to help you in this decision.

If you still feel hesitant, reach me out on Vulcan's Slack, I’d be glad to answer them :)

You can also direct any question on AUSK to Victor Vlasenko and his team at SysGears, and join Vulcan’s dedicated Slack to access the Vulcan community.

My last advice will be that simple: give both Vulcan and AUSK a shot, they are worth your time!

Thanks to Sacha Greif and Victor Vlasenko for reviewing this article.

I am the co-founder of the French company Lebrun Burel Knowledge Engineering (LBKE) —  https://www.lbke.fr

Always happy to talk about code, machine learning, innovation and entrepreneurship!

In my previous article, I explained why it makes sense to decouple the front-end part of a website from its back-end services. I introduced GraphQL, Apollo and other tools that enable such abstraction and make maintenance of production websites a nice experience.

In this article, I will show you a boilerplate that already has all these tools set up and saves you a lot of time when starting the development.

Check out the live demo of the boilerplate

Boilerplate to Speed Up the Start

Let’s start with the tools I used:

• Node.js — runtime
• Express — web application framework
• Apollo server — middleware service with GraphQL support
• Apollo client — GraphQL client
• Kentico Cloud tools — headless CMS
• Pug — template engine

Schema and Resolvers Code

The first step in building the site is to create or generate a schema. I already mentioned in the previous article that I am using Content-as-a-Service platform Kentico Cloud for content storage. The content that is stored there is already structured within defined model structures. Therefore I can quickly generate the schema using the schema generator:

kc-generate-gql-schema — projectId {projectID} — createModule

But it’s also possible to define all the models manually in the following syntax.

const TYPE_DEFINITION = `

type SystemInfo {
id: String!
name: String!
codename: String!
language: String!
type: String!
lastModified: String!
}

interface ContentItem {
system: SystemInfo!
}
...
type FactAboutUsContentType implements ContentItem {
system: SystemInfo!
description: RichTextElement
title: TextElement
image: AssetElement
}
...`module.exports = {
TYPE_DEFINITION
}

(See the whole file on GitHub.)

The model generator lists all the system types including links, texts, datetime fields, images and others (SystemInfo above), followed by the data models of each of the custom content models (FactAboutUsContentType). We will need to use the type definition as a module, hence the last argument createModule.

The next step is to create GraphQL queries and resolvers. As the content API is read-only, the queries are quite simple and limited to fetch all items or items grouped by type:

const queryTypes = type Query { items: [ContentItem], itemsByType(type: String!, limit: Int, depth: Int, order: String): [ContentItem] };

(See the whole file on GitHub.)

And right after the definition, we can create a resolver for the headless CMS API:

const deliveryClient = new DeliveryClient(deliveryConfig);
const resolvers = {
...
Query: {
items: async () => {
const response = await deliveryClient.items()
.getPromise();
return response.items;
},
itemsByType: async (_, { type, limit, depth, order }) => {
const query = deliveryClient.items()
.type(type);
limit && query.limitParameter(limit);
depth && query.depthParameter(depth);
order && query.orderParameter(order);
const response = await query.getPromise();
return response.items;
}
},
};

(See the whole file on GitHub.)

Did you notice that the queries always return generic type ContentItem even though there are more specific types like FactAboutUsContentType that inherit ContentItem defined? If you did, great job! Defining a specific query for every single type would be inefficient (there would be so many of them). Therefore both our queries return ContentItem data. But how do we ensure the right models are returned at runtime?

Every content item that comes from the headless CMS contains information about its type. You can see the string property Type in the definition of SystemInfo data model above.

{
"system": {
"type": "fact_about_us"
...
}
...
}

Now we know that the content item is of type fact_about_us which corresponds to generated data model FactAboutUsContentType. Therefore we need to translate the type name to pascal case and ensure that GraphQL uses the right data model. We can ensure this using a special resolver for the generic data model:

...
const resolvers = {
ContentItem: {
__resolveType(item, _context, _info) {
// fact_about_us -> FactAboutUs
const type = convertSnakeCaseToPascalCase(item);
// FactAboutUs -> FactAboutUsContentType
return type + 'ContentType';
}
},
...

(See the whole file on GitHub.)

And add a simple function to translate the type name to the data model name:

...
// fact_aboutus -> FactAboutUs
const convertSnakeCaseToPascalCase = (item) => {
return item.system.type
.split('')
.map((str) => str.slice(0, 1).toUpperCase() + str.slice(1, str.length))
.join('');
}
...

(See the whole file on GitHub.)

You see that for the implementation of the resolver you need to know the target service API, or in this case the specifics of the SDK. The developer working on the front-end only needs to know the GraphQL schema regardless of the services you use.

Putting It All Together

To bring our data models, queries and resolvers to life, we need to create the Apollo server instance in the main app.js file and connect it with Express and our GraphQL schema definitions:

const { TYPE_DEFINITION } = require('./graphQL/types');
const { queryTypes, resolvers } = require('./graphQL/queries');
const app = express();
const apolloServer = new ApolloServer({
introspection: true,
playground: true,
typeDefs: [
TYPE_DEFINITION,
queryTypes
],
resolvers
});
apolloServer.applyMiddleware({
app,
path: graphQLPath
});

(See the whole file on GitHub.)

In this code, we are telling Apollo which schema to use. The definitions are provided in the typeDefs array and correspond to previously created queries and resolvers.

The rest of the code in app.js (omitted here, but you may take a look at the whole file on GitHub) is related to Pug templating and routing engine. Pug enables building pages and routes in MVC structure, so it’s easy and straightforward. Take a look at the routes/index.js file (file on GitHub) that contains the definition of the only route in the boilerplate project:

...
router.get('/', async function (_req, res, _next) {
const result = await apolloClient.query({
query: gql{ itemsByType(type: "article", limit: 3, depth: 0, order: "elements.post_date") { ... on ArticleContentType { title { value } summary { value } teaser_image { assets { name url } } } } }
});
res.render('index', {
articles: result.data.itemsByType,
...
});
});module.exports = router;

Yes! Finally, a GraphQL query. You see it requests all articles ordered by post_date and specifies which data fields should be provided in the response (title, summary, teaser_image).

Note here that in the query we need to specify which data model we are expecting because not all children of ContentItem must contain requested fields (for example summary or teaser_image). By … on ArticleContentType we are basically creating a switch case that will return defined fields (title, summary and teaser_image) if the returned content item is of type ArticleContentType.

The Apollo Client sends this request to the Apollo Server which forwards it to the Kentico Cloud resolver. The resolver translates the GraphQL query into the REST API. The content takes the same way back to Pug which renders the page according to template in views/index.pug.

How does it all work together? Take a look at the live demo.

Spare Some Time for a Beer

All the tools I’ve used and shown you are easy to put together, but why reinvent the wheel? When you want to start implementing a website using Apollo and React or any other JavaScript framework, remember this boilerplate to save yourself some time and effort. If you find anything missing or wish to enhance it, feel free to raise an issue or add it directly to the code base.

Do you have experience using Apollo and GraphQL to separate concerns? Would you recommend it to others? Let me know in comments.

Let’s build an Apollo GraphQL Server with TypeScript and Webpack HMR!

Prerequisites ?

• Node.js with NPM installed on your computer. At the time of writing, Node.js version 6 or above is required by Apollo Server.
• Preferably basic understanding of the…

Using Apollo Server and Postgres — Sequelize, we’ll create a proof of concept exploiting the info parameter of the resolver function for a 94% reduction in database load on Type queries*.

If you are already familiar with the Apollo Server resolver signature and its info parameter and want to skip to the hack, click here. Thanks to my inquisitive friend Sloan Brantley Gwaltney for tipping me off to the info parameter’s potential.

Background — The resolver function signature

Apollo Server provides the following resolver function signature from their docs:

fieldName(obj, args, context, info) { result }

Back in April, I wrote some notes on the signature to teach to some teammates who were new to GraphQL / Apollo Server. Below is my (slightly) modified version of the signature:

(instance, arguments, context, info) { ...returning data... }

**instance**

obj / root / instance
— GraphQL Type associated with the resolver
— only used in Type custom field resolvers (for other Types / renamed fields)
— exists as an instance of the Type’s corresponding database Model

ex:
Type: User
Model: User, instance is ‘user’
Type custom field resolver:
user => user.property/.relationshipGetter()

**arguments**

arguments / Input object
— arguments to the Query or Mutation
— typically in the form of an Input Type object [defined in the Schema]
— Inputs are reusable objects that may contain many fields, a subset of which are appropriate for each resolver
— flexible inputs that can be used for both Query and Mutation resolvers
— destructuring in the resolver allows selectivity of the Input object fields

ex:
UserInput: { id, username, avatar, githubID }
resolver: (root, { id }) => User.findById(id);
// destructures 1 of 4 UserInput fields

**context**

context / ctx
— the context object is injected at runtime in the Apollo middleware declaration of app.js
— it is the most versatile of the resolver parameters
— allows you to pass in things like utility functions, database models, authenticated User, and so on
— by passing these in the context, you no longer need ‘require’ statements for models and helpers. They are accessible directly from the resolver.
— typically defined as a nesting object with each subcontext having its own object

**info**

no idea?

…That was until a serendipitous conversation with Sloan led to discussing this useless parameter. Sloan mentioned that it contained information about the incoming Query. This got my gears turning on improving resolver efficiency.

The info parameter

The info object holds details about your entire API Schema and other bits that I assume Apollo Server uses for processing. In particular, it holds information about the Query itself — specifically the set of Type fields requested.

Sequelize and the Tale of Gross Inefficiency

As it turns out, when Sequelize (and I believe every other OR/DM*) resolves rows or documents, it does so in their entirety. On the front / receiving end the data is indeed trimmed to specifications. But on the back end, the process appears to be:

DB query for **entire** row/doc → map / custom resolver requested fields → filter data and resolve requested fields

This was proven with a Postgres echo I ran from Sequelize on a User query:

SELECT "id", "role", "email", ...wtf Sequelize..., "timezone", "country_id", "city_id", "created_at", "updated_at" FROM "users" AS "User" WHERE "User"."github_username" = 'the-vampiire' LIMIT 1;

The Postgres query selects all 17 fields while the API Query itself only requests 1:

user(username:”the-vampiire”) { id }

Digging Into the info Object

With a bit of digging into the info object, I was able to get to my target: the requested fields. My theory was that if I knew the fields, I could pass them in as the attributes property of the Sequelize query object to reduce the load on the Postgres server.

info.fieldNodes[].selectionSet.selections[].name.value

notes

• fieldNodes is an array with the 0th element is the first query. My guess is that it’s an array to support batch queries.
• selections is an array with objects for each requested field of the Type
• the field name itself is buried under selections.name.value

The Hack

So what does all of this mean? Well with a couple of lines of code, a Model (from the context of course!), and the info argument, I wrote the following utility and proof of concept. It uses the Sequelize attributes property of the query object to get data only from the requested columns.

Using this utility resulted in a 94% decrease in the size of the query. This, of course, scales with the number of fields requested.

One of the major known benefits of using a GraphQL API is that it allows the front end to request a payload of the exact shape and size needed.

Using my utility allows the back end to reflect the same benefits by similarly reducing the load on the database server.

The first and last lines of the mapAttributes function ensure only directly mapped Model fields are passed as attributes to the query object.

This prevents errors that arise from requesting fields that do not exist as columns on the Model.

These would arise from fields that require custom Type field resolvers (like Type relationships or custom Type field names).

Proof of Concept

User Type query: user(username:”the-vampiire”) { id }

before → all 17 fields of the User table are queried

SELECT "id", "role", "email", ...wtf Sequelize..., "timezone", "country_id", "city_id", "created_at", "updated_at" FROM "users" AS "User" WHERE "User"."github_username" = 'the-vampiire' LIMIT 1;

after → only the single requested field is queried

Executing (default): SELECT "status", "id" FROM "users" AS "User" WHERE "User"."github_username" = 'the-vampiire' LIMIT 1;

This hack is officially abided by The Dude

Caveats*

• I have not tested this with Mongoose or other popular OR/DMs, but in principle, the effect should be the same. The mapAttributes function and query object would just need a few customizations.
• I have not tested this with batch queries with different fields being requested (it may affect the fieldNodes property of info).
• Does not work with custom Type field resolvers for renamed fields
• The benefits will scale by the ratio of requested Type fields to total fields on the corresponding Model.

— Vamp

Introduction

One of Web Development’s biggest strengths — and weaknesses — is its approach to modularity. A key programming mantra is to choose something (a function, a package) to do a single job and to do it well. The downside to this approach is that a single project can involve juggling dozens of separate technologies and concepts, each focusing on something specific.

So choosing Apollo Client to handle my local state as well as my remote data seems like a no brainer. Why deal with Redux’s boilerplate and idioms when I’ve already got Apollo/GraphQL set up to get data from my backend?

While this article is going to deal with setting up Apollo to handle local state, it’s not going to be an introduction to the tech. (This legit howtographql tutorial is a good start for that).

Note: The finished repo can be found here. You can pore through the code if you get stuck or feel confused.

Getting set up

We’ll start by cloning the corresponding repo from here. This repo contains a simple react website, with a sidebar, header, and a body. It’s pretty static in nature, no dynamic content (…yet). By the end of this tutorial, we’ll have Apollo managing the state of the website. Clicking an item in the sidebar will change the state of the website, which in turn updates the header to display the new data.

If you check package.json you’ll see that we’ve only got the basics, plus some additional packages pertaining to our parcel setup.

After cloning the repo, run your standard commands in your command line interface.

> yarn
> yarn dev

To install all of your packages and to whip up a local server, go to localhost:1234 and you’ll hopefully see the demo website in all of its glory. It’s static right now, so clicking around won’t do a thing.

What we want to do first and foremost is to get Apollo in our project, so install these packages. apollo-client lets us configure our instance of Apollo, and react-apollo is the driver that allows us to integrate it into our React application. Due to an issue with parcel (I think) we’ll also need to install graphql.

> yarn add apollo-client react-apollo graphql

Create a new directory src/apollo, crack open an index.js file, and add the following:

import ApolloClient from ‘apollo-client’;
export const client = new ApolloClient({});

This initializes our Apollo Client, which we will then use to wrap our React application by adding the following inside of our src/index.js file.

import { ApolloProvider } from ‘react-apollo’;
import { client } from ‘./apollo’;

const WrappedApp = (
  <ApolloProvider client={client} >
    <App />
  </ApolloProvider>
);

ReactDOM.render(WrappedApp, document.getElementById(‘root’));
// Don’t be a sap. Wrap your app.

We now have Apollo ready to use in our app. Everything builds when we restart our dev server, but we get an error when we try and access it in the browser. The console will tell us that we need to specify the link and cache properties for our Apollo client, so let’s do that.

> yarn add apollo-link apollo-cache-inmemory apollo-link-state

The previous line adds the new Apollo dependencies to our application while the following code resolves the console errors we were getting. So go back to apollo/index.js and update it so the file looks like this:

import ApolloClient from ‘apollo-client’;
import { InMemoryCache } from ‘apollo-cache-inmemory’;
import { ApolloLink } from ‘apollo-link’;
import { withClientState } from ‘apollo-link-state’;

const cache = new InMemoryCache();
const stateLink = withClientState({
  cache
});

export const client = new ApolloClient({
  cache,
  link: ApolloLink.from([
    stateLink,
  ]),
})

Let’s create an instance of our cache. The cache is Apollo’s normalized data store that stores the results of the query in a flattened data structure. We will read from the cache when we make our GraphQL query, and we’ll write to the cache when we make our mutation resolver.

You can see we’ve also added link to our client object. The ApolloLink.from()method lets us modularly configure how our queries are sent over HTTP. We can use this to handle errors and authorization, and to provide access to our backend. We’re not going to be doing any of this in the tutorial, but we will set up our client state here. So we create const stateLink above and pass in our cache. We’ll add our default state and resolvers here later.

Going back to the browser, you’ll see our lovely static site displaying in all of its magnificence. Let’s add some default state to our project and fire off our first query.

Inside of the Apollo directory, create a new directory called defaults and add an index.js inside of it. The file will contain the following:

export default {
  apolloClientDemo: {
    __typename: ‘ApolloClientDemo’,
    currentPageName: ‘Apollo Demo’,
  }
}

We create an object which acts as the default state of our site. apolloClientDemo is the name of the data structure we want to access when we make our queries. The __typename is the mandatory identifier that our cache uses, and the currentPageName is the specific item of data that our header will use to — you guessed it — display the current page name.

We’ll need to add this to our apollo/index.js file:

import defaults from ‘./defaults’;

const stateLink = withClientState({
  cache,
  defaults,
});

Let’s clear this up a little bit. import and default are both keywords associated with importing modules, but coincidentally the name of the object we’re exporting from ./defaults is also called defaults (so don’t be thinking that I’m using import/export wrong). Treat this import line as if it was just any regular ol’ named import.

With that out of the way, let’s go make a query!

How to make a query

Add the following package to your project:

> yarn add graphql-tag

and create a new directory src/graphql. In there, create two new files: index.js and getPageName.js. The GraphQL directory will house all the queries and mutations. We’ll create our query in getPageName.js by writing the following:

import gql from ‘graphql-tag’;

export const getPageNameQuery = gql`
  query {
    apolloClientDemo @client {
      currentPageName
    }
  }
`;

export const getPageNameOptions = ({
  props: ({ data: { apolloClientDemo } }) => ({
    apolloClientDemo
  })
});

So we’re exporting two variables, the query and the options. If you’ve used GraphQL before, then the query will look familiar. We’re querying against the apolloClientDemo data structure, retrieving back nothing more than the currentPageName. You’ll notice that we’ve added the @client directive to our query. This tells Apollo to query our local state instead of sending the request to the backend.

Below you’ll see that we’re exporting some options. This is simply defining how we want the data to look when we map the results to the props. We’re destructuring the GraphQL response and sending it to our view so it looks like this:

props: {
  currentPageName: ‘Apollo Demo’,
}
// and not this
props: {
  data: {
    apolloClientDemo: {
      currentPageName: ‘Apollo Demo’,
    }
  }
}

Go to the graphql/index.js file and export the query as follows:

export { getPageNameQuery, getPageNameOptions } from ‘./getPageName’;

Again, while this isn’t completely necessary for a small demo/project, this file is handy should your application grow larger. Having your queries exported from a single centralized location keeps everything organized and scalable.

Add to your Header.js:

import React from 'react';
import { Query } from 'react-apollo';
import { getPageNameQuery } from '../graphql';

const Header = () => (
    <Query query={getPageNameQuery}>
        {({ loading, error, data }) => {
            if (error) return <h1>Error...</h1>;
            if (loading || !data) return <h1>Loading...</h1>;

            return <h1>{data.apolloClientDemo.currentPageName}</h1>
        }}
    </Query>
);

export default Header;

This is our first use of Apollo’s new Query Component, which was added in 2.1. We import Query from react-apollo and use it to wrap the rest of our component. We then pass the getPageNameQuery as a value in the query prop. When our component renders, it fires off the query and gives the rest of the component access to the data, which we destructure to gain access to loading, errors, and data.

The Query Component uses the render props pattern to give the rest of our component access to the information returned from the query. If you’ve used the React Context API in 16.3, then you’ve seen this syntax before. Otherwise it’s worth checking out the official React docs here, as the Render Props pattern is becoming increasingly popular.

In our component, we do a few checks to see if there were any errors when firing the query or if we’re still waiting for data to be returned. If either of these scenarios are true, we return the corresponding HTML. If the query was fired correctly, the component will dynamically display the title of the current page. As we haven’t added our mutation yet, it will only display the default value. But you can change whatever’s in the default state and the website will reflect that.

Now all that’s left to do is mutate the data in the Apollo cache by clicking on the sidebar item.

_A refreshing image to break up the text. [Jeff Sheldon](https://unsplash.com/@ugmonk?utm_source=medium&utm_medium=referral" rel="noopener" target="blank" title=")

Mutations

Things get a little more complicated when dealing with mutations. We no longer just retrieve data from the Apollo store, but we update it too. The architecture of mutation is as follows:

> User clicks sidebar item

> Sends variable to mutation

> Fires mutation with variable

> Gets sent to the instance of Apollo

> Finds corresponding resolver

> Applies logic to the Apollo store

> Sends data back to header

If that’s difficult to remember, then use this handy mnemonic created using a mnemonic generator: Urban Senile Fauns Groped Faithless Aslan Solemnly. (easy…)

Start by creating a file graphql/updatePageName.js.

import gql from ‘graphql-tag’;

export const updatePageName = gql`
  mutation updatePageName($name: String!) {
    updatePageName(name: $name) @client {
      currentPageName
    }
  }
`;

and export it just like we did with the query.

export { updatePageNameMutation } from ‘./updatePageName’;

You’ll notice a few differences regarding the mutation. First off we’ve changed the keyword from query to mutation. This lets GraphQL know the type of action we’re performing. We’re also defining the name of the query and adding types to the variables we’re passing in. Inside here we’re specifying the name of the resolver we’ll be using to carry out the changes. We’re also passing through the variable and adding the @client directive.

Unlike the query, we can’t just add the mutation to our view and expect anything to happen. We’ll have to go back to our Apollo directory and add our resolvers. So go ahead and create a new directory apollo/resolvers, and files index.js and updatePageName.js. Inside of updatePageName.jsadd the following:

import gql from ‘graphql-tag’;

export default (_, { name }, { cache }) => {
  const query = gql`
    query GetPageName {
      apolloClientDemo @client {
        currentPageName
      }
    }
  `;

  const previousState = cache.readQuery({ query });

  const data = {
    apolloClientDemo: {
      …previousState.apolloClientDemo,
      currentPageName: name,
    },
  };

  cache.writeQuery({
    query,
    data,
  });

  return null;
};

There are a lot of interesting things going on in this file. Fortunately, it’s all very logical and doesn’t add many new concepts to what we’ve seen before.

So by default, when a resolver gets called, Apollo passes in all of the variables and the cache. The first argument is a simple ‘_’ because we don’t need to use it. The second argument is the variables object, and the final argument is the cache.

Before we can make changes to the Apollo store, we’ll need to retrieve it. So we make a simple request to get the current content from the store and assign it to previousState. Inside of the data variable, we create a new object with the new information we want to add to the store, which we then write to. You can see that we’ve spread the previous state inside of this object. This is so that only the data we explicitly want to change gets updated. Everything else remains as it is. This prevents Apollo from needlessly updating components whose data hasn’t changed.

Note: while this isn’t completely necessary for this example, it’s super useful when queries and mutations handle larger amounts of data, so I’ve kept it in for the sake of scalability.

Meanwhile in the resolvers/index.js file…

import updatePageName from ‘updatePageName’;

export default {
  Mutation: {
    updatePageName,
  }
};

This is the shape of object that Apollo expects when we pass in our resolvers in to stateLink back in apollo/index.js:

import resolvers from ‘./resolvers’;

const stateLink from = withClientState({
  cache,
  defaults,
  resolvers,
});

All that’s left to do is add the mutation to our sidebar component.

// previous imports
import { Mutation } from ‘react-apollo’;
import { updatePageNameMutation } from ‘../graphql’;

class Sidebar extends React.Component {
  render() {
    return (
      <Mutation mutation={updatePageNameMutation}>
        {updatePageName => (
          // outer div elements
          <li className=“sidebar-item” onClick={() => updatePageName({ variables: { name: ‘React’} })}>React</li>
          // other list items and outer div elements
        )}
      </Mutation>
    );
  }
}

export default Sidebar;

Like our resolver file, there’s a lot going on in this file — but it’s new. We import our Mutation component from react-apollo, wrap it around our component, and pass the updatePageNameMutation inside of the mutation prop.

The component now has access to the updatePageName method which fires the mutation whenever it’s called. We do this by adding the method as a handler to the <li>’s onClick property. The method expects to receive on object containing the variables as a parameter, so pass in the name you want to update the header to. If everything works, you should be able to run your dev server and click the sidebar items, which should then change our header.

Wrapping up

Hooray! Hopefully everything worked out. If you got stuck, then check out the repo here. It contains all of the finished code. If you’re thinking of using local state management in your next React app, then you can fork this repo and continue from there. If you’re interested in having this article/topic spoken about at a meetup or conference, then send a message my way!

There’s a lot more I wanted to cover in this tutorial, such as async resolvers (think Redux thunk), type checking/creating a schema, and a mutation update. So who knows… maybe I’ll drop another article sometime soon.

I really hope that this tutorial was useful for you. I’d like to shout out Sara Vieira’s youtube tutorial too, as it helped me get my head around Apollo Client. If I haven’t done my job well enough by leaving you scratching your head, then follow the link. And finally, feel free to hit me up on social media, I’m a big music and tech fan so talk geek to me.

Thanks for reading!

If you’re interested in hosting me at a conference, meetup or as a speaking guest for any engagement then you can DM me on twitter!

You can check out my other articles below:

How to use Apollo’s brand new Query components to manage local state

[Add a touch of Suspense to your web app with React.lazy()](http://Add a touch of Suspense to your web app with React.lazy())

No need to wait for the holidays, start Decorating now

Managing local state with Apollo and Higher Order Components

The React Conference drinking game

Develop and Deploy your own React monorepo app in under 2 hours, using Lerna, Travis and Now

How to mock up your GraphQL API with realistic values

In my last article, I took the original Apollo LaunchPad Posts and Authors API and broke it down into domains and components. I wanted to illustrate how one could organize a large GraphQL project using graphql-tools.

Now I’d like the API to return mock data when I query it. How?

The original source

In the original Apollo Launchpad example, we used static data structures and simple mapping resolvers to provide output for queries.

For instance, given this query:

# Welcome to GraphiQL

query PostsForAuthor {
  author(id: 1) {
    firstName
    posts {
      title
      votes
    }
  }
}

The output would be:

{
  "data": {
    "author": {
      "firstName": "Tom",
      "posts": [
        {
          "title": "Introduction to GraphQL",
          "votes": 2
        }
      ]
    }
  }
}

The resolvers object has functions that take care of mapping authors to posts and visa-versa. It’s not truly a mock, though.

The problem is that the more relationships and the more complex the entities become, the more code needs to go into the resolvers. Then more data needs to be provided.

When it comes to testing, tests are likely to sometimes reveal problems in the data or in the resolvers. You really want focus testing of the API itself.

Using mocks

There are three Node.js modules that make mocking an API quick and easy. The first is part of the graphql-tools module. Using this module, a beginning step is to require or import the method addMockFunctionsToSchema from the module into the root schema.js file:

import {
    makeExecutableSchema,
    addMockFunctionsToSchema
} from 'graphql-tools';

Then, after creating an executable schema by calling createExecutableSchema, you add your mocks like so:

    addMockFunctionsToSchema({
        schema: executableSchema,
    })

Here’s a full listing of the root schema.js:

// This example demonstrates a simple server with some relational data: Posts and Authors. You can get the posts for a particular author,
// and vice-versa Read the complete docs for graphql-tools here: http://dev.apollodata.com/tools/graphql-tools/generate-schema.html

import {
    makeExecutableSchema,
    addMockFunctionsToSchema
} from 'graphql-tools';

import {
    schema as authorpostsSchema,
    resolvers as authorpostsResolvers
} from './authorposts';

import {
    schema as myLittleTypoSchema,
    resolvers as myLittleTypeResolvers
} from './myLittleDomain';

import {
    merge
} from 'lodash';

const baseSchema = [
    `
    type Query {
        domain: String
    }
    type Mutation {
        domain: String
    }
    schema {
        query: Query,
        mutation: Mutation
    }`
]

// Put schema together into one array of schema strings and one map of resolvers, like makeExecutableSchema expects
const schema = [...baseSchema, ...authorpostsSchema, ...myLittleTypoSchema]

const options = {
    typeDefs: schema,
    resolvers: merge(authorpostsResolvers, myLittleTypeResolvers)
}

const executableSchema = makeExecutableSchema(options);

addMockFunctionsToSchema({
    schema: executableSchema
})

export default executableSchema;

So what’s the output? Executing the same query as before yields:

{
  "data": {
    "author": {
      "firstName": "Hello World",
      "posts": [
        {
          "title": "Hello World",
          "votes": -70
        },
        {
          "title": "Hello World",
          "votes": -77
        }
      ]
    }
  }
}

Well, that’s kind of dumb. Every string is “Hello World”, votes are negative, and there will always be exactly two posts per author. We’ll fix that, but first…

Why use mocks?

Mocks are often used in unit tests to separate the functionality being tested from the dependencies that those functions rely on. You want to test the function (the unit), not a whole complex of functions.

At this early stage of development, mocks serve another purpose: to test the tests. In a basic test, you want to ensure first that the test is calling the API correctly, and that the results returned have the expected structure, properties, and types. I think the cool kids call this “shape”.

This offers more limited testing than a queryable data structure, because reference semantics are not enforced. id is meaningless. Nonetheless, mocks offer something to structure your tests around

Realistic mocking

There’s a module called casual that I really like. It provides reasonable and variable values for a lot of common data types. If you are demonstrating your new API in front of jaded colleagues, it actually looks like you’ve done something special.

Here’s a wish list for mock values to display:

1. Author’s first name should be first-name-like
2. Post titles should be variable lorem ipsum text of limited length
3. votes should be positive or zero
4. the number of posts should vary between 1 and 7

First thing is to create a folder called mocks. Next, we’ll add an index.js file to that folder with the mock methods. Finally, the custom mocks will be added to the generated executable schema.

The casual library can generate values by data type (String, ID, Int, …) or by property name. Also, graphql-tools MockList object will be used to vary the number of items in a list — in this case posts. So let’s start.

Import both casual and MockList into /mocks/index.js:

import casual from 'casual';
import {
    MockList
} from 'graphql-tools';

Now let create a default export with the following properties:

export default {
    Int: () => casual.integer(0),

    Author: () => ({
        firstName: casual.first_name,
        posts: () => new MockList([1, 7])
    }),

    Post: () => ({
        title: casual.title
    })
}

The Int declaration takes care of all integer types appearing in our schema and it will ensure that Post.votes will be positive or zero.

Next, Author.firstName will be a reasonable first name. MockList is used to ensure the number of posts associated with each Author will be between 1 and 7. Finally, casual will generate a lorem ipsum title for each Post.

Now the generated output varies each time the query is executed. And it looks credible:

{
  "data": {
    "author": {
      "firstName": "Eldon",
      "posts": [
        {
          "title": "Voluptatum quae laudantium",
          "votes": 581
        },
        {
          "title": "Vero quos",
          "votes": 85
        },
        {
          "title": "Doloribus labore corrupti",
          "votes": 771
        },
        {
          "title": "Qui nulla qui",
          "votes": 285
        }
      ]
    }
  }
}

Generating custom values

I just scratched the surface of what casual can do, but it is well-documented and there’s nothing much to add.

Sometimes, though, there are values that have to conform to a standard format. I would like to introduce one more module: randexp.

randexp allows you to generate values conforming to the regexp expression you provide it. For instance, ISBN numbers have the format:

/ISBN-\d-\d{3}-\d{5}-\d/

Now I can add Books to the schema, add books to Author, and generate ISBN and title for each Book:

// book.js
export default `
  type Book {
    ISBN: String
    title: String
}

mocks.js:

import casual from 'casual';
import RandExp from 'randexp';
import {
    MockList
} from 'graphql-tools';
import {
    startCase
} from 'lodash';

export default {
    Int: () => casual.integer(0),

Author: () => ({
        firstName: casual.first_name,
        posts: () => new MockList([1, 7]),
        books: () => new MockList([0, 5])
    }),

Post: () => ({
        title: casual.title
    }),

Book: () => ({
        ISBN: new RandExp(/ISBN-\d-\d{3}-\d{5}-\d/)
            .gen(),
        title: startCase(casual.title)
    })
}

And here’s a new query:

query PostsForAuthor {
  author(id: 1) {
    firstName
    posts {
      title
      votes
    }
    books {
      title
      ISBN
    }
  }
}

Sample response:

{
  "data": {
    "author": {
      "firstName": "Rosemarie",
      "posts": [
        {
          "title": "Et ipsum quo",
          "votes": 248
        },
        {
          "title": "Deleniti nihil",
          "votes": 789
        },
        {
          "title": "Aut aut reprehenderit",
          "votes": 220
        },
        {
          "title": "Nesciunt debitis mollitia",
          "votes": 181
        }
      ],
      "books": [
        {
          "title": "Consequatur Veniam Voluptas",
          "ISBN": "ISBN-0-843-74186-9"
        },
        {
          "title": "Totam Et Iusto",
          "ISBN": "ISBN-6-532-70557-3"
        },
        {
          "title": "Voluptatem Est Sunt",
          "ISBN": "ISBN-2-323-13918-2"
        }
      ]
    }
  }
}

So that’s the basics of mocking using graphql-tools plus a couple of other useful modules .

Note: I use snippets throughout this post. If you want to follow along in a broader context, sample code is here.

The Full source is on GitHub for your perusal.

Give me a hand if you found this article informative.