Forem: Sean Connolly

Flutter GraphQL: Quick start with Fauna

Sean Connolly — Fri, 07 May 2021 03:51:13 +0000

Flutter GraphQL: Quick start

Flutter is a UI toolkit for building mobile, web and desktop applications from a single codebase.

GraphQL is a powerful query language designed to make APIs fast, flexible, and developer-friendly.

Fauna makes it easy to create a GraphQL API backed by a scalable and secure transactional database.

In this series of articles, we’ll cover how to build a Flutter application powered by a Fauna GraphQL API.

Part 1: Quick start

In this article:

Why GraphQL with Flutter?
Why Fauna with Flutter?
Create a GraphQL API in minutes
Create data with a GraphQL mutation
Find a single item with a GraphQL query
Fetch multiple items with a GraphQL query
Set up a GraphQL client in Flutter
Populate a Flutter ListView with a GraphQL query

Why GraphQL with Flutter?

I do not intend to write another GraphQL vs. REST comparison article, but it is beneficial to understand the benefits you should expect from using GraphQL in Flutter apps. Maintaining a clear understanding of what works well with GraphQL is essential to getting the most out of it.

Optimal data size

When you fetch data with GraphQL, you specify exactly the structure you need for each query. If your screen only needs a few properties, you can greatly reduce bandwidth and latency to optimize the end user experience.

Data aggregation

Many applications need to fetch many different types of resources to display useful information on a screen. For example, in a screen that displays a list of spaceships in your galactic starfleet, you may need to display information about each ship, the ship’s crew, the ship’s passengers, the planets where they are docked, etc. GraphQL allows you to specify what you need from each resource in a single query and takes care of the complexity of aggregation for you.

Intelligent caching

In GraphQL, every resource is globally identifiable with a unique identifier and type classification. Client libraries can use this information to intelligently cache objects for later use. Two separate queries for the same data? No problem, the second query can be resolved straight from the cache without writing any additional code to manage that state.

Development flexibility

Because clients specify the exact data needed in each query, frontend developers can easily add or remove properties from the query to fetch the data required. This means you don’t need to make changes to your backend API (or wait for somebody else to do it) if the display requirements of your screens change.

Why Fauna GraphQL with Flutter?

Many concepts in this series will work for any GraphQL backend, but as you follow along, I hope you see the benefits of using Fauna with your Flutter apps.

Easy to get started

You can create a globally distributed, failsafe, secure, and scalable GraphQL API up and running in just a few minutes.

Productive data modeling

Fauna supports documents, relations, and graphs providing great data modeling flexibility that can be easily enhanced as your application evolves.

Zero infrastructure management

Fauna provides an API, not just a database, so you don’t need to manage any infrastructure.

Power when you need it

Fauna’s auto generated GraphQL API will help you get started. As your needs evolve, you can add custom queries and mutations with all the power of FQL, Fauna’s comprehensive query language.

Flutter + GraphQL Course

We are working on a comprehensive online course for Flutter developers who want to build amazing Flutter apps with GraphQL.

Whether you have worked with Flutter and GraphQL before or are just getting started, there will be something in this course for you.

Learn more at GraphQL for Flutter Developers.

Create a Fauna GraphQL API in minutes

In the first section of this tutorial, we will create a new GraphQL API for Spaceships Flutter, an app that helps us manage a fleet of galactic spaceships.

Create a GraphQL schema definition file

First, copy this text into a file called schema-definition.gql.

type Spaceship {
  name: String!
}

We refer to this file as a schema definition file because it provides the minimum set of information that allows Fauna to create collections, indexes, etc. and then make those available via GraphQL API.

The Spaceship type above defines our first resource type. For now, our spaceships only need a name, which is a string. The exclamation point on String! means this field is a required, non-nullable field.

Import the GraphQL schema definition file into Fauna

If you haven’t already, register an account with Fauna.
From the Fauna dashboard, select New Database.
Enter flutter_spaceships for the name and select Save.
In the left navigation, select GraphQL.
Select Import Schema and upload the schema-definition.gql file we created earlier.
When the upload is complete, you should land in the GraphQL Playground, which means you are ready to move on to the next step.

Explore the GraphQL API

The GraphQL API is now available for us to start using, but what exactly did Fauna just do with that uploaded file?

Since we are here in the GraphQL Playground, let’s view the docs by selecting the Docs tab.

This view informs us of all of the operations available in the GraphQL API. The first section lists the available queries, operations that allow us to read data from our database. The next section lists mutations, operations that allow us to change the data in our database through creations, updates, and deletions.

These are all standard CRUD (Create - Read - Update - Delete) operations that Fauna implements for us based on the definition of our schema that we provided in the prior step.

All of this was generated by Fauna simply by defining the Spaceship type:

type Spaceship {
  name: String!
}

This single type definition generated 4 operations:

findSpaceshipById
createSpaceship
updateSpaceship
deleteSpaceship

Now that we’ve explored the GraphQL API, let’s start using it to build our space fleet.

Create data with GraphQL mutations

Our fleet won’t be much of a fleet without some spaceships. Eventually we will be able to add spaceships from our Flutter app, but for now we will continue to use Fauna’s GraphQL Playground to write and execute mutations.

Since we are adding a spaceship, we need to create data. Let’s inspect the createSpaceship mutation.

We can see that the createSpaceship mutation accepts a single parameter called data, which is of type SpaceshipInput. SpaceshipInput includes a name property, which is the exact property we specified when we defined the Spaceship type in our original schema definition.

With that, we can enter this mutation into the input of the GraphQL Playground.

mutation {
  createSpaceship(data: { name: "Serenity" }) {
    _id
    _ts
    name
  }
}

Since the createSpaceship mutation returns a Spaceship, we can specify the information about the created spaceship that we want to retrieve after the mutation completes. _id and _ts are properties that Fauna adds to every type in its database; they capture the document’s unique identifier and creation timestamp respectively.

And as soon as we execute the mutation, we have a spaceship in our system.

Feel free to add a few more spaceships to your fleet. We will fetch and display these in a Flutter ListView later.

Find a single item with a GraphQL query

Now that there is a spaceship in our system, how do we find it again later?

If we inspect the docs in the GraphQL Playground again, we can see the findSpaceshipById query is just what we need. We can also see that this query takes only one argument, the id of the spaceship we want to find.

In the prior mutation we requested the spaceship’s _id in the sub selection, so let’s copy that _id into the findSpaceshipById query to demonstrate how we can easily lookup a document with its unique identifier.

query {
  findSpaceshipByID(id: "enter-id-here") {
    _id
    name
  }
}

Replace the id value with the _id from the prior mutation response and execute the query in the GraphQL Playground. You should see a result like this:

Fetch multiple items with a GraphQL query

In our Spaceships Flutter app, we are not going to ask users to enter spaceship ids in order to view their fleet. Instead, we will want to display a list of spaceships in the fleet. Currently we can only get a single spaceship if we know its unique id, so how do we get a list of spaceships?

First we need to update our GraphQL schema by adding another type to the schema-definition.gql file we uploaded earlier.

type Spaceship {
  name: String!
}

type Query {
  spaceships: [Spaceship!]!
}

The Query type is a special type in GraphQL. It defines all of the top-level entry points that are available for clients to execute queries against. Here we are adding a spaceships query that will return a list of Spaceship items. The square brackets around [Spaceship!]! indicate this return type is a GraphQL array.

In the GraphQL Playground, there is an Update Schema action that will prompt you to upload the latest schema definition. Select schema-definition.gql again to update the schema.

After the upload is complete, inspect the docs again to see that a new spaceships query was added.

Notably, the final schema generated by Fauna is not exactly as it was defined. Instead of returning an array like we defined, the spaceships query returns a SpaceshipPage!. We can also see that the spaceships query accepts two inputs: _size and _cursor.

The return type and the additional inputs are here to allow us (well actually force us) to use pagination when fetching lists of items. Data sets in any system can grow very large and limiting the amount of data fetched in each query helps optimize server resources, latency, and bandwidth.

If we don’t specify a _size, Fauna will use its default limit of 64, which is fine for us for now since our fleet hasn’t exceeded that yet.

Go ahead and execute this query in the GraphQL Playground.

query {
  spaceships {
    data {
      _id
      name
    }
  }
}

Our GraphQL API is ready and has what we need to start building our Flutter app.

Set up a GraphQL client in Flutter

In this section we are going to create a new Flutter project and use the Ferry GraphQL client to connect to our GraphQL API. There are a few other Flutter GraphQL clients available on pub.dev but I believe Ferry is the best option available and is easy to get started with.

If you haven’t worked with Flutter before, follow the Get started steps.

First, create a new Flutter project by running this command in your terminal:

flutter create flutter_spaceships

Next, we need to add a few dependencies to our project. This can be done by replacing pubspec.yaml with this:

name: flutter_spaceships
description: A new Flutter project.

publish_to: 'none'
version: 1.0.0+1

environment:
  sdk: '>=2.7.0 <3.0.0'

dependencies:
  flutter:
    sdk: flutter
  ferry: ^0.9.4
  ferry_flutter: ^0.4.0
  gql_http_link: ^0.3.2
  flutter_dotenv: ^3.1.0
  cupertino_icons: ^1.0.0

# This one is important to prevent build_runner errors
dependency_overrides:
  analyzer: ^0.40.4

dev_dependencies:
  flutter_test:
    sdk: flutter
  ferry_generator: ^0.3.3
  build_runner: ^1.10.1

flutter:
  uses-material-design: true
  assets:
    - .env

Your IDE may automatically download these packages. If not, you can also run:

flutter pub get

Most GraphQL APIs will require some kind of authorization token. We are not going to implement user authentication in this app, so for now we will use a single token and manage it with a .env file.

Note: Production apps should almost always implement user authentication. We are only skipping it for this tutorial because it takes extra work to set up that isn’t directly related to getting started with GraphQL.

First, you need to get a token from Fauna. From the Fauna dashboard, navigate to Security and then select New Key.

From here, we’ll select the Server role. You don’t need to specify a key name, but I called mine “development”.

Note: We are using the Server key for this tutorial but you would not typically want to include a Server key in your production app. You either want to implement proper user authentication or implement another role with limited access. I put together A Brief Guide on Public Roles in Fauna in case you need it.

After you save your key, copy it and paste it into a new file named .env in the root of your project like so:

# .env
FAUNA_KEY=your-key-goes-here

Note: If you commit this project to source control, be sure to add the .env to your .gitignore.

Next, open the main.dart file.

We won’t preserve any of the boilerplate in this file that was created when we first ran flutter pub create, so go ahead and delete all of that.

At the top of the file, let’s add a few import statements.

import 'package:flutter/material.dart';
import 'package:flutter_dotenv/flutter_dotenv.dart' as DotEnv;
import 'package:ferry/ferry.dart';
import 'package:gql_http_link/gql_http_link.dart';

The flutter_dotenv package will help us read the FAUNA_KEY environment variable we stored in our .env file.

Then we are importing Ferry, our GraphQL client, and then gql_http_link, which will allow us to access our GraphQL API over HTTP.

Next, we will instantiate the Ferry GraphQL client in the main function.

void main() async {
  await DotEnv.load();
  final client = Client(
    link: HttpLink("https://graphql.fauna.com/graphql", defaultHeaders: {
      'Authorization': 'Bearer ${DotEnv.env["FAUNA_KEY"]}',
    }),
  );
  runApp(App(client));
}

You can see that we only need to provide two things to interact with the GraphQL API: the endpoint and the Authorization header that includes the FAUNA_KEY we created earlier. Without the header, Fauna will not permit our app to access the API.

In a more complicated app, you would most likely use something like get_it or provider to make it easier to access the client. To keep this example simple and focused on working with GraphQL, we will simply pass it down to the App widget, which we will create next.

class App extends StatelessWidget {
  final Client _client;
  App(this._client);

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Spaceships’,
      theme: ThemeData(
        primarySwatch: Colors.indigo,
        visualDensity: VisualDensity.adaptivePlatformDensity,
      ),
      home: HomeScreen(_client), // We will implement this later
    );
  }
}

This App is very similar to the default one created when we started the project. The main difference is that we added the _client as a constructor argument so that we can pass it to the HomeScreen, which is where we will execute a GraphQL query and display some data.

But before we can build the HomeScreen widget, we need to write our GraphQL query and make it executable in our Flutter app.

Write a GraphQL query in a Flutter app

The home screen in our Flutter app will display a list of spaceships, answering the question:

What spaceships are in my fleet?

Thankfully, we already proved that we can answer this question when we were writing queries in Fauna’s GraphQL Playground.

Go ahead and copy this content into a file called spaceships.graphql (it should live in /lib as well).

# lib/spaceships.graphql
query GetSpaceships {
  spaceships {
    data {
      _id
      name
    }
  }
}

If you compare this query to the one we previously wrote, you will note one important difference. In this one, we added an operation name to our query: GetSpaceships. As we will see in a moment, the operation name is required for Ferry’s type generation.

Generate Dart classes from a GraphQL query

One of the benefits of Ferry, and why I prefer it over some other GraphQL Flutter clients, is its support for code generation and fully typed data access. This allows us to confidently read and write data with the added convenience of IDE autocompletion.

The first step toward code generation with Ferry is adding our GraphQL schema to the project. To get this, we need to download a schema file from Fauna. Ferry will use this schema file to generate Dart classes from our data schema.

In the GraphQL Playground we were using before, just under the Docs tab is a Schema tab. Select Schema, then Download and then SDL to download the file.

Save the file in your /lib directory like so:

If you open schema.graphql, what you see is a reflection of what we see when we open the Docs tab in Fauna’s GraphQL playground. It’s the same information, just in a different format that can be read by Ferry to generate Dart classes.

Next, we need to create a build.yaml file at the root of our project and populate it with this content:

targets:
  $default:
    builders:
      gql_build|schema_builder:
        enabled: true
      gql_build|ast_builder:
        enabled: true
      gql_build|data_builder:
        enabled: true
        options:
          schema: flutter_spaceships|lib/schema.graphql
      gql_build|var_builder:
        enabled: true
        options:
          schema: flutter_spaceships|lib/schema.graphql
      gql_build|serializer_builder:
        enabled: true
        options:
          schema: flutter_spaceships|lib/schema.graphql

      ferry_generator|req_builder:
        enabled: true
        options:
          schema: flutter_spaceships|lib/schema.graphql

Note: If you used a different project name other than flutter_spaceships, be sure to replace the schema declarations with whatever you chose.

We just added a fair amount of config, but thankfully you don’t need to understand all of it to make use of it. The important thing is that we now have the correct pieces in place to generate our types by running a single command:

flutter pub run build_runner build --delete-conflicting-outputs

Here we are making use of the build_runner package that we included in our dependencies when we first created the Flutter project.

After that runs successfully, you should see several new files in your project that end with .gql.dart or .gql.g.dart. Notably, several of these are prefixed with spaceships and contain classes specifically generated from the spaceships.graphql query we previously added.

Now let’s see how we can make use of these classes and fetch some data in our Flutter app.

Populate a ListView with a GraphQL query

Since our home screen will display a list of spaceships, the ListView widget is a good choice. But before we can populate our list, we need to import our newly generated classes.

# lib/main.dart
import 'package:ferry_flutter/ferry_flutter.dart';
import 'spaceships.req.gql.dart';
import 'spaceships.var.gql.dart';
import 'spaceships.data.gql.dart';

Ferry Flutter provides an Operation widget that makes it easier to work with GraphQL in Flutter apps. To use this widget, we will implement the HomeScreen widget like so:

class HomeScreen extends StatelessWidget {
  final Client _client;

  HomeScreen(this._client);

  @override
  Widget build(BuildContext context) {
    return Operation<GGetSpaceshipsData, GGetSpaceshipsVars>(
      client: _client,
      operationRequest: GGetSpaceshipsReq(),
      builder: (context, response, error) {
        return Scaffold(
          appBar: AppBar(
            title: Text("Flutter Space Fleet"),
          ),
          body: response.loading
              ? Text('Loading...')
              : SpaceshipList(response.data.spaceships),
        );
      },
    );
  }
}

The Operation widget is making use of a few classes prefixed with GGetSpaceship. Earlier we mentioned the importance of the operation name in the GraphQL query we defined in spaceships.graphql and here we see how Ferry used it to generate unique classes just for that query.

By passing GGetSpaceshipsReq as the operationRequest, we are telling the Operation widget to execute our GraphQL query and then provide the results of the query to the widgets built inside the builder method. On the first build, the data will not be present yet as Ferry waits for a network response, so we display basic loading text.

After the network response is received, we can then render the data in the SpaceshipList, which is defined below.

class SpaceshipList extends StatelessWidget {
  final GGetSpaceshipsData_spaceships _spaceships;
  SpaceshipList(this._spaceships);

  @override
  Widget build(BuildContext context) {
    return ListView.builder(
      itemCount: _spaceships.data.length,
      itemBuilder: (context, i) {
        final spaceship = _spaceships.data[i];
        return ListTile(
          title: Text(spaceship.name),
          trailing: Text('🚀'),
        );
      },
    );
  }
}

GGetSpaceshipsData_spaceships may look like a funny name for a type, but it’s structure makes sense when you look again at the query that generated these types:

query GetSpaceships {
  spaceships {
    data {
      _id
      name
    }
  }
}

Since GraphQL queries can be nested, Ferry will generate new classes to capture these structures.

Since the data property under spaceships is a GraphQL array, it becomes a list in our Flutter app, meaning we can iterate, map filter, etc. just like any other list.

In our case, we are making use of ListView.builder, which can work with any list including our GraphQL generated list. If you inspect the class of the spaceship variable that we define in the itemBuilder, you can see another class generated by Ferry: GGetSpaceshipsData_spaceships_data.

Do you see the pattern yet?

query GetSpaceships {
  spaceships {
    data {
      _id
      name
    }
  }
}

When we get to the leaf nodes of the query (the innermost nodes: _id and name) we find data in a format that we can display. The name field is a String and can be displayed for each spaceship in the list.

Summary

In the first part of this series, we created a GraphQL API in Fauna and were able to integrate it in a Flutter app.

With most of the setup out of the way, adding new widgets that also require data from the GraphQL API will only need a few steps:

Write a query in a .graphql file.
Build classes with build_runner.
Build a widget that uses the Operation widget and displays the data.

Find the full source code on GitHub: https://github.com/seanconnollydev/flutter_spaceships

In the next post of this series, we will explore how to add and edit spaceships with GraphQL mutations and see how the normalized cache keeps our application state up to date.

Why I'm building a GraphQL course for Flutter developers

Sean Connolly — Fri, 09 Apr 2021 04:13:34 +0000

I recently made the decision to create a course that teaches developers how to leverage GraphQL in their Flutter applications.

The idea for the course emerged during my recent experience working on a Flutter project that primarily used REST APIs but could have benefited greatly from embracing GraphQL.

Is REST really easy?

The most common argument I hear from developers who want to use REST over GraphQL is that "REST is easy" and "GraphQL is complicated."

In my experience REST only appears easier on the surface. In other words...

The API is just the tip of the iceberg

While the REST API may be easy to get started with, it leaves you with a number of additional problems to solve on your own:

Caching
Type safety
Optimistic updates
N + 1 (or making many API calls to get the data you need)
Over-fetching
Data aggregation

These are all solvable with REST but require additional code you need to write and maintain.

With GraphQL you can leave it to the GraphQL server and smart client libraries like graphql_flutter or ferry to solve all of this for you.

So by investing some time up front getting started with GraphQL and all it has to offer, you can do more with less.

A GraphQL API is only a few clicks away

Some of the perception that "GraphQL is complicated" stems from complicated server implementations. Having built a few custom Apollo Server APIs, I agree that the backend of GraphQL can be complicated.

Thankfully, there are easier ways to get started with a fast, scalable GraphQL API. My choice backend these days is Fauna, with this description from their site:

Fauna is a flexible, developer-friendly, transactional database available as a secure, cloud API with native GraphQL. Never again worry about database provisioning, maintenance, scaling, sharding, replication, or correctness.

Without writing any code, you can have a GraphQL API up and running in just a few minutes.

I have paired Next.js + Fauna GraphQL in multiple projects with amazing results in productivity, performance, and scale. I am excited to bring these same benefits to other Flutter developers with their applications.

Flutter is powerful and fun

A while back, I spent about a month evaluating Flutter vs. React Native. Since then it's been all Flutter all the time and I love it.

Sure, Flutter isn't perfect but no development toolkit is. The reason why I love Flutter is because it lowered the entry barrier enough for me (previously and still a web developer) to step into mobile app development.

Flutter is similar enough to React that I can reapply my existing skills in all kinds of new ways and that's pretty exciting.

Flutter + GraphQL = Excellent developer experience

One thing Flutter developers love and continue to want is a great developer experience. Flutter offers a great developer experience and I believe pairing Flutter with GraphQL makes the experience even better.

Want updates on this course? Follow me on Twitter I will keep you posted on its progress.

How to make an online multiplayer game with JavaScript and Fauna

Sean Connolly — Wed, 17 Mar 2021 03:46:50 +0000

Several months ago, I decided to build an online multiplayer game. I have friends and family who live far away but we all love to play games together, so we are always on the lookout for games we can play online while we chat on Zoom.

After trying several online multiplayer games in the browser, I decided to try building my own. I have been writing JavaScript and React for many years, so I was confident that I could build a decent game UI.

But since my game needed to support multiple players, I also needed a database and an API that I could use to connect people to a game session.

There are many databases and API services out there, but one option really caught my eye:

Fauna 😍

What is Fauna?

Fauna is a developer-friendly data API, so it stores your data and provides multiple ways to access your data.

If you love to build things but don’t like to deal with complicated database infrastructure, Fauna is an excellent choice.

Fauna is also one of the easiest ways to set up a GraphQL API and GraphQL has many benefits for all kinds of applications, both large and small. I chose to use GraphQL for my game application, but it’s up to you as you can use Fauna with or without GraphQL.

I was so smitten with Fauna’s ease of use and their GraphQL capability, I chose it for my first real-time game even before they supported real-time streaming (spoiler: real-time is supported now!).

Why Fauna for building multiplayer games?

Easy to get started: Fauna’s billing model makes it pain-free to get started with any project, games included.

Zero operational overhead: Fauna is available instantly as a serverless utility and delivers limitless capacity. No need to worry about downtime or scaling if your game suddenly spikes in popularity.

Real-time streaming: Online multiplayer games need fast interactions and Fauna’s real-time capability is incredibly easy to implement.

Effortless concurrency: With online multiplayer games, you usually need to worry about multiple users trying to write to the same document or database table. Fauna’s optimistic calculations handle concurrency for you.

How online multiplayer browser games work

Consider one of the most basic online multiplayer games you could build: Rock Paper Scissors.

In Rock Paper Scissors, 2 players simultaneously make a selection (rock, paper, or scissors). Then, both selections are revealed and a winner is declared, unless of course both players make the same choice and the result is a tie. To keep things interesting, our game will repeat this sequence until one player wins 3 times, also referred to as “Best of 3.”

If we were to capture this game sequence as a JSON object, it might look something like this:

{
  "selections": [
    [
      { "playerId": "1", "selection": "Rock" },
      { "playerId": "2", "selection": "Paper" }
    ],
    [
      { "playerId": "1", "selection": "Scissors" },
      { "playerId": "2", "selection": "Paper" }
    ],
    [
      { "playerId": "1", "selection": "Paper" },
      { "playerId": "2", "selection": "Rock" }
    ],
    [
      { "playerId": "1", "selection": "Rock" },
      { "playerId": "2", "selection": "Scissors" }
    ]
  ]
}

The game sequence itself is an array of rounds where each round is captured as a 2-item array that captures each player’s selection for that round.

We can also describe this document with GraphQL schema:

type GameSession {
  selections: [[PlayerSelection]]
}

enum SelectionType {
  Rock
  Paper
  Scissors
}

type PlayerSelection @embedded {
  playerId: ID!
  selection: SelectionType!
}

It’s okay if you aren’t familiar with GraphQL syntax. In a bit we will see how this schema definition allows us to query our Fauna database for the latest game state. If you want to dig further into GraphQL with Fauna you may want to check out Simple GraphQL with Fauna or Get started with Next.js + Fauna in 5 minutes.

This data structure is enough to capture our game state and store it in Fauna, but how do we allow multiple players to interact with this data from their browser?

Both browsers can communicate with our Fauna database but they cannot communicate with each other directly. So in order for each player to know the current state of the game, the browser needs a way to know when data has been updated in the database.

But how can the browser know when the database is updated?

Before real-time streaming, long polling was the only option

One way for the browser to know when the database is updated is to just periodically ask for the latest game state.

A GraphQL query to fetch the latest game state would look like this:

query GetGameSession($id: ID!) {
  findGameSessionById(id: $id) {
    id
    selections
  }
}

Using Apollo Client with React, we can execute the query like so:

// GET_GAME_SESSION is the query defined above
const { data, loading, error } = useQuery(GET_GAME_SESSION, { variables: { id: 'the_game_session_id' } });

By default, useQuery makes a single request. If I want to set that up for long polling, I just need to set a pollInterval to tell Apollo how frequently to poll.

// GET_GAME_SESSION is the query defined above
const { data, loading, error } = useQuery(GET_GAME_SESSION, { variables: { id: 'the_game_session_id' }, pollInterval: 2000 });

This is relatively easy to set up, especially if you are already familiar with Apollo Client, but there are a few drawbacks to long polling that you should be aware of.

First, long polling is only as fast as your poll interval. If you poll every 5 seconds, there could be a 4.99 second delay from when your opponent makes a selection to when you see an update in your UI.

Second, long polling is resource intensive as each request requires use of the network and your database. Fauna’s metered billing is cost effective, but you still want to use it wisely. If you try to minimize latency by keeping the poll interval shorter, you are then forcing the browser to execute more queries. Not only does this incur additional data transfer on the player’s browser but it also incurs load and possibly real dollar cost in your Fauna database.

Thankfully, Fauna has a better solution for you: real-time streaming.

Real-time streaming with Fauna

Fauna now supports real-time data streaming, an ideal solution for online multiplayer games (and many other applications!).

For any document in your Fauna database, you can establish a connection and subscribe to events to know anytime the document is updated.

I like to think of streams as “data over time”. In the diagram below, each tick represents an event where each event provides new data about the state of the game. When a player makes a selection, a new event occurs and Fauna notifies both players of the updated game state.

Earlier, we queried our game state through GraphQL so you might be wondering if Fauna supports GraphQL subscriptions, which are the GraphQL way to fetch real-time data. For now, Fauna does not support GraphQL subscriptions, but fear not! There are still options that allow you to leverage Fauna’s real-time streaming both with and without GraphQL.

Realtime data without GraphQL subscriptions

Until Fauna supports GraphQL subscriptions, you have a few choices to fetch real-time data with Fauna.

Pure streams (no GraphQL)

You may already be using GraphQL in other areas of your application. In this case you can still use GraphQL in those areas but use Fauna’s JavaScript SDK to stream data in only the areas where you need it.

import { Client, query as q } from 'faunadb';

const ref = q.Ref(q.Collection('GameSession'), 'the_game_session_id');

const subscription = client.stream
  .document(ref, { fields: ['document'] })
  .on('start', (data, event) => console.log(data))
  .on('snapshot', (data, event) => console.log(data))
  .on('version', (data, event) => console.log(data))
  .start();

In this example, we are subscribing to 2 events on a document in our Fauna database.

The start event provides a timestamp. Events that occur after this should always have a timestamp equal to or later than this event.
The snapshot event provides the initial state of the document at the start of the stream.
The version event provides details about changes any time the document is modified.

If we were to log out these events for a game of Rock Paper Scissors, it might look like this:

// From the "start" event
1615437123500000

// From the "snapshot" event
{
  ts: 1615437122453000,
  ref: Ref,
  data: {
    selections: [[]]
  }
}

// From the 1st "version" event
{
  document: {
    data: {
      selections: [
        {
          playerId: "292739620242719232",
          selection: "Rock"
        }
      ]
    }
  }
}

// From the 2nd "version" event
{
  document: {
    data: {
      selections: [
        {
          playerId: "292739620242719232",
          selection: "Rock"
        },
        {
          playerId: "292739632882254349",
          selection: "Paper"
        }
      ]
    }
  }
}

GraphQL refetch

Consider the scenario where our Rock Paper Scissors game takes off like a rocket 🚀 and we want to allow players to create player accounts that allow them to make friends, track winning streaks, etc. Well, we would need to add another document type to capture these player accounts in our system.

To add player accounts, we could add this to our GraphQL schema:

type PlayerAccount {
  name: String!
  email: String!
}

With the addition of more document structures, it is even more helpful to leverage GraphQL’s aggregation capability, which allows us to fetch multiple documents in a single query.

query GetGameSession($id: ID!) {
  findGameSessionById(id: $id) {
    id
    selections
    playerAccounts {
      id
      name
      email
    }
  }
}

Now that we are again fetching data through GraphQL and we don’t want to go back to long polling, we can simply tell Apollo Client to run the query again anytime changes are made to the document.

First, we can set up a useQuery like so.

const { refetch } = useQuery(GET_GAME_SESSION, { skip: true, variables: { id: 'the_game_session_id' } });

We pass skip: true to tell Apollo to skip the initial query as we don’t want to fetch data until the stream starts (more on this in a moment). Also note we are no longer getting the data straight from this query and instead getting a function called refetch, which allows us to rerun the query whenever we need to.

Now, we can again initialize the stream, except when our application is notified of document changes, we call refetch to fetch the latest GraphQL.

const RockPaperScissors = () => {
  const [gameSession, setGameSession] = useState();
  const { refetch } = useQuery(GET_GAME_SESSION, { skip: true, variables: { id: 'the_game_session_id' } });

  const fetchData = async () => {
    try {
      const { data } = await refetch();
      setGameSession(data);
    } catch (err) {
      console.error(err);
    }
  };

  useEffect(() => {
    const ref = q.Ref(q.Collection('GameSession'), 'the_game_session_id');

    const subscription = client.stream
      .document(ref, { fields: ['document'] })
      .on('start', fetchData)
      .on('version', fetchData)
      .start();

    return () => {
      subscription.close();
    };
  }, []);

  return <div>UI goes here</div>;
};

Initialize with GraphQL + update with stream

There are a few downsides to executing a GraphQL refetch every time your document is updated.

First, the refetch adds additional latency for the player. Below is a list of logged durations for the refetch. So even though we know new data is available, we still force the user to wait an additional 100-500ms to reflect changes to the UI. This may be okay for a simple game of Rock Paper Scissors, but other games might require more speed.

Second, additional queries also incur cost. If you are trying to minimize your costs, you want to avoid as many unnecessary API reads as you can.

To eliminate the need for the refetch, we can instead execute a single GraphQL query to fetch all of our aggregate data and then use streaming to continuously update our game state.

const RockPaperScissors = () => {
  const [gameSession, setGameSession] = useState();
  const { refetch } = useQuery(GET_GAME_SESSION, { skip: true, variables: { id: 'the_game_session_id' } });

  const fetchData = async () => {
    try {
      const { data } = await refetch();
      setGameSession(data);
    } catch (err) {
      console.error(err);
    }
  };

  // We added this to update data locally rather than refetch
  const handleVersion = (data) => {
    setGameSession((gs) =>
      Object.assign({}, gs, {
        selections: data.document.data.selections,
      }),
    );
  };

  useEffect(() => {
    const ref = q.Ref(q.Collection('GameSession'), 'the_game_session_id');

    const subscription = client.stream
      .document(ref, { fields: ['document'] })
      .on('start', fetchData)
      .on('version', handleVersion)
      .start();

    return () => {
      subscription.close();
    };
  }, []);

  return <div>UI goes here</div>;
};

This is a bit more code and state in your application, but it can be worth it for the faster experience and reduced costs.

Complex game logic: In the browser or the backend?

While we’ve been using Fauna to store and access our game data, one thing we haven’t seen is any real game logic. In our Rock Paper Scissors game, there isn’t much logic but we do need a way to evaluate the selections from the two players and determine a winner.

In plain English:

Rock beats Scissors
Scissors beats Paper
Paper beats Rock

One thing we need to decide is where this determination should happen and it really boils down to 2 choices:

Application code (running in the browser)
Fauna

While Fauna’s query language, FQL, is very powerful and efficient for accessing data, it can be cumbersome to write complex logic with it. It can be challenging to get game logic right and often requires lots of iteration and debugging. Debugging FQL is possible, but more difficult than debugging JavaScript running in a browser. With JavaScript, you can use dev tools to set breakpoints and console.log your way to victory. Most modern web frameworks like React also support near-instant feedback cycles, which can save you a significant amount of time.

On the other hand, pushing your game logic down to Fauna centralizes your logic to one place. If you wanted to support more than one client (like a native mobile app), then you may want to consider pushing as much logic to Fauna as possible. Another benefit to pushing your logic to Fauna is it makes it easier to store derived information like game winners for future use. If you wanted to understand how often Rock wins compared to other choices, it would be much easier to query if you also determined and stored win/loss information in your Fauna document.

In this case, I chose to write scoring logic as a JavaScript function in my application code like so:

function score(gameSession, currentPlayerId) {
  const scoredSelectionsList = gameSession.selections
    ?.filter((s) => s.length == 2)
    .reverse()
    .map((selections) => {
      const currentPlayerSelection = selections.find((s) => s.playerId === currentPlayerId).selection;
      const opponentSelection = selections.find((s) => s.playerId !== currentPlayerId).selection;

      const scoredSelections = {
        result: 'Tie',
        currentPlayer: currentPlayerSelection,
        opponent: opponentSelection,
      };

      if (currentPlayerSelection == 'Rock') {
        if (opponentSelection == 'Scissors') scoredSelections.result = 'Win';
        if (opponentSelection == 'Paper') scoredSelections.result = 'Loss';
      }

      if (currentPlayerSelection == 'Paper') {
        if (opponentSelection == 'Rock') scoredSelections.result = 'Win';
        if (opponentSelection == 'Scissors') scoredSelections.result = 'Loss';
      }

      if (currentPlayerSelection == 'Scissors') {
        if (opponentSelection == 'Paper') scoredSelections.result = 'Win';
        if (opponentSelection == 'Rock') scoredSelections.result = 'Loss';
      }

      return scoredSelections;
    });

  const currentPlayerScore = scoredSelectionsList.reduce((prev, curr) => {
    if (curr.result == 'Win') return prev + 1;
    return prev;
  }, 0);

  const opponentScore = scoredSelectionsList.reduce((prev, curr) => {
    if (curr.result == 'Loss') return prev + 1;
    return prev;
  }, 0);

  return {
    currentPlayer: currentPlayerScore,
    opponent: opponentScore,
    selections: scoredSelectionsList,
  };
}

It might help to look at a sample input and output for this function.

Sample scoring input:

// currentPlayerId:
"292824494445167112"

// gameSession:
{
  selections: [
    [
      { playerId: "292824494445167112", "Rock" },
      { playerId: "292824508034712077", "Paper" }
    ],
    [
      { playerId: "292824494445167112", "Rock" },
      { playerId: "292824508034712077", "Scissors" }
    ],
  ]
}

Sample scoring output:

// result
{
  currentPlayer: 1,
  opponent: 1,
  selections: [
    {
      currentPlayer: "Rock",
      opponent: "Scissors",
      result: "Win"
    },
    {
      currentPlayer: "Rock",
      opponent: "Paper",
      result: "Loss"
    },
  ]
}

Building multiplayer games has never been easier

It takes just a few minutes to set up a Fauna database. From there, you don’t need to worry about scaling your infrastructure at all. Instead you can focus on the fun stuff: building the game experience you want for your players.

If you want to see a full implementation of online multiplayer rock paper scissors using the code and principles we covered here, check out Rock Paper Scissors.

Questions or comments? Find me on Twitter.

Get started with Next.js + Fauna GraphQL in 5 minutes

Sean Connolly — Thu, 03 Dec 2020 17:33:58 +0000

I love the classic game show Name That Tune where contestants start each round by bidding on how many notes they need to name a tune.

I can name that tune in three notes.

...

I can name that tune in two notes.

...and so on until the risk becomes too high for a contestant to bid any lower.

The same competitive spirits applies to software development. When starting a new project, how fast can you go from nothing to something?

Can you start that project in a day? An hour?

I can start that project in 5 minutes (and so can you).

In this tutorial, we will build a Next.js web application powered by a Fauna GraphQL API in 5 minutes. You can use this process over and over again, for any project you need.

What you will learn

In Part 1: Simple GraphQL with Fauna, we learned how to quickly construct a GraphQL API with Fauna, the data API for modern applications. It’s okay if you missed part 1, you can start right here in part 2 without missing a beat.

APIs are nice, but now we need a user interface to turn our project into an experience. We are going to leverage Next.js and a few other tools to add a user interface to the game of rock paper scissors we started in part 1.

By the end of this tutorial, you will understand:

How to setup a Fauna GraphQL API
How to integrate your Fauna GraphQL API with a Next.js application
How to use Apollo, TypeScript, and code generation to establish a statically typed interface for your GraphQL API

Up and running in 5 minutes

In just 5 minutes, we are going to set up a Fauna database and bootstrap a Next.js project that connects to the database.

Setup your Fauna database

If you do not have a Fauna account, you can register a Fauna account for free.
Create a new database.
Enter “rock-paper-scissors” as the name and click Save.
In the left nav, go to Security => New Key.
Make sure the “Admin” role is selected, enter “localhost” as the key and click Save.

You should see a secret key. Keep this window open while you switch to project setup.

Setup your Next.js project

Now that our Fauna database is set up, we can create our Next.js project.

Create a GitHub repository.
In a terminal, clone the repository to a local directory, i.e. git clone <repository url>.
In the created directory, run npx @seanconnolly/gen nextjs fauna.
Follow the prompts to enter the name (rock-paper-scissors) for your project.
When prompted for your Fauna Admin key, enter the key you kept open in step 6 of the Setup your database step.

Initialize your Fauna GraphQL API

Now that you have your Fauna database and your Next.js project setup, you are ready to initialize your database.

Run npm run fauna to bootstrap your Fauna database with the resources defined in the project generator you just ran (we will examine these more closely later).
Go back to the Fauna Dashboard and you should see that an example collection, index and function was created in your database. These were all created by the npm run fauna command you just ran.
Select Security and then New Key again.
In the Role dropdown, select the Public role (we will examine the importance of this role shortly). Enter "localhost" for the key name and then select Save.
Copy the secret key that was just generated and paste it in the .env.local file like so:

# Paste your secret key just after the = sign
NEXT_PUBLIC_FAUNA_CLIENT_KEY=

Test your Next.js project

Open a terminal and run npm run dev.

Now open http://localhost:3000 in your browser and you should see this message.

🎉 Success! We were able to successfully connect with your Fauna database.

You did it! 💥

In just 5* minutes, you created a Next.js web application and hooked it up with a Fauna database.

* It's okay if you took longer than 5 minutes. I've done this a few times so 5 minutes may be on the lower end, but after going through this process once or twice, 5 minutes is totally attainable!

Understand the setup process

While we were able to blaze through the setup process in just a few minutes, you are probably wondering what we just did exactly. Let’s walk through the key parts of the project so you understand how everything is working.

Next.js project setup

The npx @seanconnolly/dev nextjs fauna command you ran earlier is a Hygen.io generator I created to accelerate the process of setting up new projects that use Next.js and Fauna. Running the generator first adds the boilerplate files to our project directory and then installs all necessary packages from npm including Next.js, React and Apollo Client.

You are free to use this generator to kickstart any one of your projects or you can learn to create your own with Hygen’s Quick Start.

Initializing Fauna

If you joined us for Part 1: Simple GraphQL with Fauna, you hopefully already know about the fauna-gql-upload package. To summarize, fauna-gql-upload allows us to store Fauna schema and resource definition files alongside our project files and push them to Fauna as needed. When we ran the generator earlier, several of these files were generated to provide a baseline for our Fauna database.

For example, in our GraphQL schema definition file (fauna/schema.gql), we defined the Example type:

[Schema snippet]

type Example {
  foo: String!
}

When we ran npm run fauna earlier, that schema definition resulted in Fauna creating a Collection called Example.

The Public role

Earlier, we created a Fauna API key for the Public role, which is a custom role that was predefined with the project generator. Our Next.js application needs this API key to access our Fauna database from a web browser. We are calling it a “Public” role because our application does not require a user to authenticate with a password or via third-party authentication like Auth0 or Okta. Full user authentication is outside the scope of this tutorial, but the Public role is necessary in these unauthenticated cases to protect data and resources in our Fauna database.

By default, every Fauna database comes with two roles: Admin and Server. Fauna describes these roles in their Admin UI:

Admin: Used to create, destroy, or manage any database or key. Protect admin keys very carefully.
Server: Can be used to create, destroy, or manage the database to which they are assigned. Protect server keys carefully.

Both of these roles have too much privilege for us to expose their API keys to a web browser. If we did expose such keys, a savvy user could load your web application, inspect the key and use it to destroy or access valuable or sensitive resources in your Fauna account.

In your .env.local file, the FAUNA_ACCESS_KEY_ADMIN variable has Admin privilege, which means we do not want to expose that key to the browser. This key is required for you, the developer, to manage your Fauna database and it is not for your users. This Admin key should only be stored and accessible on your machine and should never be exposed to the browser.

We also added the NEXT_PUBLIC_FAUNA_CLIENT_KEY variable to .env.local, which has Public privilege. Opening fauna/roles/Public.ts, we see this definition of the Public role:

const Public = {
  name: 'Public',
  privileges: [
    {
      resource: Collection('Example'),
      actions: {
        read: true,
        create: true,
        delete: false,
      },
    },
  ],
};

Since this is a custom role, it only has privileges that are explicitly granted, in this case the ability to read and create documents in the Example collection.

By prefixing the environment variable with NEXT_PUBLIC_, Next.js automatically makes this environment variable accessible to the browser. If you open components/withApollo.tsx, you can see where this is read and then passed as an Authorization header to our Fauna GraphQL endpoint by Apollo Client.

const { NEXT_PUBLIC_FAUNA_CLIENT_KEY } = process.env;
/* ... */
return new ApolloClient({
  uri: 'https://graphql.fauna.com/graphql',
  cache: new InMemoryCache().restore(initialState || {}),
  headers: {
    Authorization: `Bearer ${NEXT_PUBLIC_FAUNA_CLIENT_KEY}`,
  },
});

GraphQL with Apollo

When we tested the project by hitting http://localhost:3000, we saw a “Success” message when the index page could successfully query the Fauna GraphQL API. If the API call were to fail, possibly due to some misconfiguration, we would have seen an error message instead. Let’s take a look at how all of this is working.

First, when running npm run dev, in addition to running the usual next dev script defined in package.json, we are also concurrently running a script called gen:gql:watch.

"scripts": {
  /* ... */
  "gen:gql": "dotenv -c -- graphql-codegen",
  "gen:gql:watch": "npm run gen:gql -- --watch",
  "dev": "concurrently \"next\" \"npm run gen:gql:watch\"",
  /* ... */
}

This is the graphql-codegen project at work and what it does for us is amazing. First, graphql-codegen is configured through the codegen.yml file that was created via the generator.

# codegen.yml
schema:
  - https://graphql.fauna.com/graphql:
      headers:
        Authorization: Bearer ${FAUNA_ACCESS_KEY_ADMIN}
documents: '{components,lib}/**/*.graphql'
generates:
  ./.gen/graphql.tsx:
    plugins:
      - typescript
      - typescript-operations
      - typescript-react-apollo
config:
  preResolveTypes: true

The schema points to Fauna’s GraphQL endpoint and is also configured to read the FAUNA_ACCESS_KEY_ADMIN environment variable that you entered when you first generated the project.

The documents configuration tells graphql-codegen to generate code from all files under the /components and /lib directories that end with .graphql.

The components/Example.graphql was created with the project setup generator and contains the content below. When Fauna received our schema.gql GraphQL definition file earlier, they automatically created CRUD queries and mutations for the Example type. findExampleByID is the “read” operation and allows us to get an Example by its ID.

# components/Example.graphql
query FindExample($id: ID!) {
  findExampleByID(id: $id) {
    _id
  }
}

The last part of the codegen.yml file is the generates section, which tells graphql-codegen to generate a TypeScript file at .gen/graphql.tsx that includes Apollo React hooks. If you are not familiar with Apollo’s hooks, you can read more about those in Apollo’s Hooks documentation.

If you open the generated .gen/graphql.tsx file you will see this useFindExampleQuery:

/* .gen/graphql.tsx */
export function useFindExampleQuery(baseOptions: Apollo.QueryHookOptions<FindExampleQuery, FindExampleQueryVariables>) {
  return Apollo.useQuery<FindExampleQuery, FindExampleQueryVariables>(FindExampleDocument, baseOptions);
}

This generated code and its associated TypeScript types are derived from the Example.graphql file we examined earlier.

The operation name dictates the name of the hook function:

# components/Example.graphql
query FindExample($id: ID!) {
  #   ^^^^^^^^^^^
  findExampleByID(id: $id) {
    _id
  }
}

/* .gen/graphql.tsx */
export function useFindExampleQuery(baseOptions: Apollo.QueryHookOptions<FindExampleQuery, FindExampleQueryVariables>) {
  return Apollo.useQuery<FindExampleQuery, FindExampleQueryVariables>(FindExampleDocument, baseOptions);
}

The query variables dictate the FindExampleQueryVariables type.

# components/Example.graphql
query FindExample($id: ID!) {
  #               ^^^^^^^^
  findExampleByID(id: $id) {
    _id
  }
}

/* .gen/graphql.tsx */
export type FindExampleQueryVariables = Exact<{
  id: Scalars['ID'];
}>;

The query body dictates the FindExampleQuery type.

# components/Example.graphql
query FindExample($id: ID!) {
  findExampleByID(id: $id) {
    _id
    # ^
  }
}

/* .gen/graphql.tsx */
export type FindExampleQuery = { __typename?: 'Query'; findExampleByID?: Maybe<{ __typename?: 'Example'; _id: string }> };

With our generated code, we can now consume it in a React component as demonstrated with the components/Example.tsx file.

/* components/Example.tsx */
import { FunctionComponent } from 'react';
import { useFindExampleQuery } from '@gen/graphql';

const Example: FunctionComponent = () => {
  const { data, error } = useFindExampleQuery({ variables: { id: '123' } });

  if (error) {
    console.error(error);
    return <div>‼️ Error! Inspect the console to see what happened.</div>;
  }

  if (data) {
    return <div>🎉 Success! We were able to successfully connect with your Fauna database.</div>;
  }

  return null;
};

export default Example;

Don’t worry about the hard-coded “123” id. At this stage we haven’t created any documents so no results will be returned. This is just enough to prove that we can successfully execute a query from our frontend Next.js application to our backend Fauna GraphQL API.

With code generation, we are able to reduce the amount of code we need to write and maintain in our React component to just one line:

/* components/Example.tsx */

/* Just one line! 💥 */
const { data, error } = useFindExampleQuery({ variables: { id: '123' } });

Without code generation, we would have needed to manually define the TypeScript types on our own and keep those types in sync with the data we are requesting via the GraphQL query. This is tedious work and error prone, so graphql-codegen helps us speed up development and reduce defects in our application.

Implementing the game UI

Now that we have everything wired up and we discussed how the generated code is all working together, we can now implement our Rock Paper Scissors game UI with Next.js and Fauna.

In Part 1: Simple GraphQL with Fauna, we played our game of Rock Paper Scissors in Fauna’s GraphQL Playground, which is fine for testing the API but not quite the experience we want for our users (unless they love GraphQL as much as you and I do!). In order to build UI for our own application, we are going to do 3 things:

Setup our backend game logic
Create a new GraphQL query in a .graphql file, which will generate a new React hook
Use one of the hooks in a React component

First, we are going to pull some of our Fauna backend from the part 1 solution, which implements the game logic in Fauna. If you want to better understand what these are doing, check out the explanations in part 1.

Copy this into your fauna/schema.gql file:

# fauna/schema.gql
type Query {
  play(selection: Selection!): Result! @resolver(name: "play")
}

enum Selection {
  Rock
  Paper
  Scissors
}

type Result @embedded {
  selection: Selection!
  opponentSelection: Selection!
  message: String!
}

Create fauna/functions/Play.ts and copy this into it:

/* fauna/functions/Play.ts */
import { query } from 'faunadb';
import { RandomString, Switch } from 'faunadb-fql-lib';
import DetermineResult from '../lib/DetermineResult';
const { Lambda, Let, Query, Var } = query;

const selectionMap = {
  R: 'Rock',
  P: 'Paper',
  S: 'Scissors',
};

const Play = {
  name: 'play',
  body: Query(
    Lambda(
      ['selection'],
      Let(
        {
          randomCharacter: RandomString(1, 'RPS'),
          opponentSelection: Switch(Var('randomCharacter'), selectionMap),
        },
        DetermineResult(Var('selection'), Var('opponentSelection')),
      ),
    ),
  ),
};

export default Play;

Create fauna/lib/DetermineResult.ts and copy this into it:

/* fauna/lib/DetermineResult.ts */
import { ExprArg, ExprVal, query } from 'faunadb';
const { And, Equals, If, Or } = query;

export default function DetermineResult(selection: ExprArg, opponentSelection: ExprArg): ExprVal {
  return {
    selection,
    opponentSelection,
    message: If(
      Equals(selection, opponentSelection),
      "It's a tie!",
      If(
        Or(
          And(Equals(selection, 'Rock'), Equals(opponentSelection, 'Scissors')),
          And(Equals(selection, 'Paper'), Equals(opponentSelection, 'Rock')),
          And(Equals(selection, 'Scissors'), Equals(opponentSelection, 'Paper')),
        ),
        'You win!',
        'You lose!',
      ),
    ),
  };
}

Since we are creating a new resource in Fauna (the play function), we need to grant the Public role access to that function, otherwise we will encounter authorization errors when we try to invoke that function from our application. The fauna/roles/Public.ts file should be updated to this:

/* fauna/roles/Public.ts */
import { query } from 'faunadb';
const { Collection, Function } = query;

const Public = {
  name: 'Public',
  privileges: [
    {
      resource: Collection('Example'),
      actions: {
        read: true,
        create: true,
        delete: false,
      },
    },
    // This is new
    {
      resource: Function('play'),
      actions: {
        call: true,
      },
    },
  ],
};

export default Public;

Now run npm run fauna in your terminal to push your API changes to Fauna. You should see success all the way down.

✔️  Successfully updated schema.

✔️  Successfully uploaded indexes

✔️  Successfully uploaded functions

✔️  Successfully uploaded roles

Next, we need to define the client-side GraphQL query that our UI requires to play the game.

Create RockPaperScissors.graphql and copy this into it:

query Play($selection: Selection!) {
  play(selection: $selection) {
    selection
    opponentSelection
    message
  }
}

Since we are running graphql-codegen in watch mode, the GraphQL code is automatically regenerated. If you open .gen/graphql.tsx, you should see two new hooks are available for us:

/* .gen/graphql.tsx */
export function usePlayQuery(baseOptions: Apollo.QueryHookOptions<PlayQuery, PlayQueryVariables>) {
  return Apollo.useQuery<PlayQuery, PlayQueryVariables>(PlayDocument, baseOptions);
}
export function usePlayLazyQuery(baseOptions?: Apollo.LazyQueryHookOptions<PlayQuery, PlayQueryVariables>) {
  return Apollo.useLazyQuery<PlayQuery, PlayQueryVariables>(PlayDocument, baseOptions);
}

Now we can use these hooks in a React component, so create components/RockPaperScissors.tsx and copy this:

/* components/RockPaperScissors.tsx */
import { Selection, usePlayLazyQuery } from '@gen/graphql';
import { FunctionComponent } from 'react';

const RockPaperScissors: FunctionComponent = () => {
  const [playSelection, { data, loading }] = usePlayLazyQuery({
    fetchPolicy: 'no-cache',
  });

  const handleSelection = (selection: Selection) => {
    playSelection({
      variables: {
        selection,
      },
    });
  };

  return (
    <div className="root">
      <h1>Rock Paper Scissors</h1>
      <h3>Choose wisely</h3>
      <div className="player-selections">
        <PlayerSelection selection={Selection.Rock} onSelect={handleSelection} />
        <PlayerSelection selection={Selection.Paper} onSelect={handleSelection} />
        <PlayerSelection selection={Selection.Scissors} onSelect={handleSelection} />
      </div>
      {loading && <p>Waiting on opponent...</p>}
      {data?.play && (
        <div>
          <p>{`Opponent chose ${data.play.opponentSelection} ${emojiFor(data.play.opponentSelection)}`}</p>
          <h3>{data.play.message}</h3>
        </div>
      )}
      <style jsx>{`
        font-family: Verdana, sans-serif;
        .root {
          text-align: center;
        }

        .player-selections {
          display: flex;
          justify-content: center;
        }
      `}</style>
    </div>
  );
};

interface PlayerSelectionProps {
  selection: Selection;
  onSelect: (selection: Selection) => void;
}
const PlayerSelection: FunctionComponent<PlayerSelectionProps> = (props) => {
  const { selection, onSelect } = props;

  return (
    <button type="button" className="root" onClick={() => onSelect(selection)}>
      <div className="emoji">{emojiFor(selection)}</div>
      <div className="selection">{selection}</div>
      <style jsx>{`
        font-family: Verdana, sans-serif;

        .root {
          padding: 16px 32px;
          margin: 16px;
          text-align: center;
          cursor: pointer;
        }

        .emoji {
          font-size: 4.8rem;
          line-height: 1;
          margin-bottom: 16px;
        }

        @media only screen and (max-width: 600px) {
          .root {
            padding: 8px 16px;
            margin: 8px;
          }
          .emoji {
            font-size: 1rem;
          }
        }
      `}</style>
    </button>
  );
};

function emojiFor(selection: Selection): string {
  switch (selection) {
    case Selection.Rock:
      return '✊🏼';
    case Selection.Paper:
      return '🖐🏼';
    case Selection.Scissors:
      return '✌🏼';
    default:
      throw new Error('Unrecognized selection');
  }
}

export default RockPaperScissors;

I tried to keep the styling code minimal here so it isn’t the most elegant game of Rock Paper Scissors you can find on the internet, but let’s look at a few key code snippets in this component.

First, we are using a hook called usePlayLazyQuery, which is a bit different from usePlayQuery.

/* components/RockPaperScissors.tsx */
const [playSelection, { data, loading }] = usePlayLazyQuery({
  fetchPolicy: 'no-cache',
});

The main difference in our use case is that we don’t want to initiate the GraphQL request until the user makes a selection. If we used usePlayQuery, the query would occur after the component mounts during initial page load. That wouldn’t make sense for the sequence of our game. Keep the following guidance in mind for your own applications:

use*Query: Fetch after the component mounts.
use*LazyQuery: Fetch in response to user action.

We also passed fetchPolicy: “no-cache” to tell Apollo that we always want this request to execute fully against our Fauna GraphQL endpoint without checking the local browser cache. This prevents our game from returning the same opponent selection over and over. In most use cases, you do not need to set an explicit fetchPolicy. Refer to Apollo’s Setting a fetch policy docs for more information on fetch policies and caching.

Next, we have the handleSelection callback function:

/* components/RockPaperScissors.tsx */
const handleSelection = (selection: Selection) => {
  playSelection({
    variables: {
      selection,
    },
  });
};

This function is called whenever the user makes a selection. It calls playSelection, another callback function defined by the result of the call to usePlayLazyQuery above and the function that triggers the network call to our GraphQL API.

Last, we define how we want to present responses from the GraphQL request.

/* components/RockPaperScissors.tsx */
<div className="root">
  {/* ... */}
  {loading && <p>Waiting on opponent...</p>}
  {data?.play && (
    <div>
      <p>{`Opponent chose ${data.play.opponentSelection} ${emojiFor(data.play.opponentSelection)}`}</p>
      <h3>{data.play.message}</h3>
    </div>
  )}
  {/* ... */}
</div>

The loading boolean value will be true while Apollo waits for the network response to complete, so the user sees the message “Waiting on opponent…”

When data.play is truthy, this means the network response is complete and we know the result of the game. The user sees the selection of the computer opponent and a message with the final game verdict.

The final step is to update the pages/index.tsx file to use your new component rather than the default Example component.

import RockPaperScissors from '@components/RockPaperScissors';
import { FunctionComponent } from 'react';

const Index: FunctionComponent = () => {
  return <RockPaperScissors />;
};

export default Index;

Now you should be able to refresh http://localhost:3000 in your browser and see this screen:

Open up your browser dev tools and go to the Network tab. As you make each selection, you can inspect the requests hitting your Fauna GraphQL endpoint that should look like this:

And now you have a fully functioning game complete with a Next.js frontend user interface and a backend Fauna GraphQL API. Nice work! 👏🏻

Close

Hopefully you now see the power of this awesome pairing of Next.js and Fauna. It is the most delightful full stack development experience I have ever encountered and with Fauna I never need to worry about database maintenance, scaling, or correctness.

In the next and final part of this series, we are going to learn about Fauna’s recently released streaming capability, which will allow us to turn our game of Rock Paper Scissors into a real-time multiplayer experience. Be the first to know when it’s published by subscribing to the newsletter over at seanconnolly.dev.

How to use React Hook Form with Material UI

Sean Connolly — Mon, 09 Nov 2020 16:38:16 +0000

React Hook Form recently won the Productity Booster Award at React Summit so if you are not familiar with React Hook Form, now is a good time to learn it. React Hook Form is performant, has great docs and it works everywhere (including React Native).

Material UI continues to be the most popular open source React component library out there.

So if you are a React developer, there is a good chance you will find yourself with the opportunity to use Material UI's form components with React Hook Form.

A basic TextField

If you are working with forms in Material UI, you are most likely working with the TextField component like this one:

import { TextField } from '@material-ui/core';

const BasicTextField = () => {
  return <TextField id="name" helperText="A basic TextField component" />;
};

export default BasicTextField;

Add React Hook Form

If you follow the React Hook Form docs, you will see code that looks like this:

<input name="example" ref={register} />

This doesn't quite work out of the box with Material UI's TextField component. Instead, we need to make use of the inputRef prop on TextField as demonstrated in this example.

import { useState } from 'react';
import { TextField } from '@material-ui/core';
import { useForm } from 'react-hook-form';

interface Inputs {
  name: string;
}

const HookedTextField = () => {
  const [name, setName] = useState<string>();
  const { register, handleSubmit } = useForm<Inputs>();

  const onSubmit = async (data: Inputs) => {
    setName(data.name);
  };

  return (
    <>
      <form onSubmit={handleSubmit(onSubmit)}>
        <TextField inputRef={register} id="name" name="name" helperText="Enter your name and press [Enter]" />
      </form>
      {name && <div>Submitted: {name}</div>}
    </>
  );
};

export default HookedTextField;

Reset the form

Sometimes you need to manually reset form state. React Hook Form makes this easy.

const { register, handleSubmit, reset } = useForm<Inputs>();

const onSubmit = async (data: Inputs) => {
  setName(data.name);
  reset();
};

Watch fields

React Hook Form also provides the watch function that allows you to immediately respond to changes in form state.

const { register, handleSubmit, watch } = useForm<Inputs>();

// This field will update as the user types
const currentName = watch('name');

Putting it all together

import { useState } from 'react';
import { TextField } from '@material-ui/core';
import { useForm } from 'react-hook-form';

interface Inputs {
  name: string;
}

const FinalTextField = () => {
  const [name, setName] = useState<string>();
  const { register, handleSubmit, reset, watch } = useForm<Inputs>();

  const currentName = watch('name');

  const onSubmit = async (data: Inputs) => {
    setName(data.name);
    reset();
  };

  return (
    <>
      <form onSubmit={handleSubmit(onSubmit)}>
        <TextField inputRef={register} id="name" name="name" helperText="Enter your name and press [Enter]" />
      </form>
      <div>
        {currentName && <div>Current: {currentName}</div>}
        {name && <div>Submitted: {name}</div>}
      </div>
    </>
  );
};

export default FinalTextField;

React Hook Form provides several other options for form management. When paired with Material UI, constructing forms doesn't get much easier.

Are you using React Hook Form with Material UI? Let me know on Twitter.

Simple GraphQL with Fauna

Sean Connolly — Thu, 29 Oct 2020 14:52:41 +0000

How I am using the fauna-gql-upload package, authored by Carl Hallén Jansson to simplify my Fauna GraphQL development workflow.

What I love about Fauna

At first glance, there is a lot to like about Fauna. First, it is a managed database. As a frontend engineer, I find the persnickety details and behaviors of databases cumbersome. I jump at any chance to avoid managing servers, dealing with state, and setting up my local development with a heavy database. Fauna is a backend as a service, so you don't need to worry about any of that. You setup your database in their UI, get your private key to access it and away you go. I love that experience.

I also love that Fauna has a GraphQL layer. I upload my schema and Fauna generates the basic queries, mutations and underlying implementation details like resolvers for me so I can start executing GraphQL queries immediately.

This is all great, but we can improve the Fauna GraphQL developer experience even further with some additional automation.

Why we need to automate

If you follow Fauna's Get started with GraphQL tutorial, you will need to use Fauna's admin UI to create and modify your GraphQL schema. That is fine to get started, but we need something more automated so we can continue to enhance our schema as our application evolves.

We don't want to upload a schema.gql file in Fauna's admin UI every time we need to modify our GraphQL server. What we need is:

The ability to quickly and easily push changes to our GraphQL server beyond just the schema.
The ability to know what other changes went along with our Fauna changes.
The knowledge of who made those changes and why.
The ability to revert to a prior state.

One way of doing this is to use fauna-gql-upload, a simple CLI to update your database's GraphQL schema, resolver functions, indexes, and database roles without going to the Fauna dashboard.

Yes, that's more like it! I can manage my GraphQL server as code just like any other code that powers my application. I can open PRs with the proposed changes and have my team review them before I commit them to my production database.

What we are building

In this tutorial, we are going to build a basic game of Rock Paper Scissors. By the end, you will be able to play a game with your Fauna backend using just GraphQL queries and mutations.

Setup your database

Before we can start using fauna-gql-upload, we need to set up a database. You can follow the Quick start with Fauna or use the admin UI to create your database. I will walk you through how to do this in the UI. After this you won’t need to manage anything else in Fauna’s UI, though it is still helpful to use it for document inspection, running one-off commands in the shell and executing GraphQL queries.

From the Fauna dashboard, select New Database.
For the Database Name, enter rock-paper-scissors.
In the left nav, select Security and then select New Key.
For the Role, make sure it is Admin and then enter fauna-gql as the Key Name, then select Save.
Keep the window open or store the secret key somewhere safe. We will use it in a moment.

Setup your project

Before we do anything with Fauna, we will set up our code project. To simplify setup for you, I created a simple generator CLI built on top of hygen.io. You can view the template files for that in this GitHub repository.

Create a GitHub repository.
Clone that repository to a local directory, i.e. git clone <repository url>.
In the created directory, run npx @goldenshun/shun fauna gql.
Follow the prompts to enter the name (rock-paper-scissors) and description for your project.
When prompted for your Fauna server key, enter the key you generated in step 5 of the Setup your database step.

You should now have several configuration files in your project as well as a fauna directory. This also installed several dependencies, which is all you need to leverage fauna-gql-upload to create your GraphQL server. Let's take a look at a few key files.

fauna/schema.gql

This declares a simple Example model with property foo, which is a string.

type Example {
  foo: String!
}

package.json

There are a few scripts defined here, but the main one we will be using is fauna, which will compile our TypeScript files and then upload our GraphQL schema plus supporting FQL files via fauna-gql-upload.

"scripts": {
  "build:fauna": "tsc --project tsconfig.fauna.json",
  "fauna": "npm run build:fauna && fauna-gql",
  "fauna:override": "npm run build:fauna && fauna-gql --override"
}

Is TypeScript required?

TypeScript is not required to use fauna-gql-upload. The default examples for that project are all in vanilla JavaScript. I prefer TypeScript for my projects because it makes it easier for me to find small mistakes like typos and misplaced arguments when I am writing complex FQL statements. Use whatever works for you though!

.fauna.json

This file provides configuration to fauna-gql-upload so it knows where to find your schema, supporting FQL files and the secret you entered in the Setup your project step.

{
  "envPath": ".env.local",
  "secretEnv": "FAUNA_ADMIN_SECRET_KEY",
  "schemaPath": "fauna/schema.gql",
  "fnsDir": ".gen/fauna/functions",
  "rolesDir": ".gen/fauna/roles",
  "indexesDir": ".gen/fauna/indexes"
}

Create your GraphQL server

Now that you have your Fauna database and your code project setup, you are ready to run it!

npm run fauna

You should see this output in your terminal:

✔️  Successfully updated schema.

✔️  Successfully uploaded indexes

✔️  Successfully uploaded functions

✔️  Successfully uploaded roles

As you can see, in one command we pushed our GraphQL type definitions as well as supporting indexes, functions, and roles.

Test your GraphQL server

Back in the Fauna Admin UI, select GraphQL in the left nav.
Open the Docs tab. You should see the findExampleByID query as well as several mutations, including createExample.

🎉 This is what Fauna does for you. Remember, all you uploaded in your schema.gql file was a model called Example. But after uploading your schema to Fauna, you now have the ability to create, read, update, and delete (CRUD) documents.

Enter the following GraphQL mutation in the GraphQL playground and execute it.

mutation {
  createExample(data: { foo: "Hello" }) {
    _id
  }
}

If all went well, you should see a result like this:

{
  "data": {
    "createExample": {
      "_id": "278019502149468680"
    }
  }
}

Customizing your GraphQL server

What we've done so far is pretty cool. In just a few CLI commands, we were able to bootstrap a fully functional GraphQL server. Now that we know everything is up and running, let's implement something more interesting.

In order to play a game of Rock Paper Scissors with our Fauna backend, we need some additional functionality.

The basic game flow should look like this:

You, the player, make a selection.
The opponent (programmed in Fauna) also makes a selection.
The winner is determined based on the rules of the game.
The results are sent back to you, the player.

Simple enough, let's implement it!

Initial schema

First, we can define an enum that declares all possible selections in the fauna/schema.gql file.

enum Selection {
  Rock
  Paper
  Scissors
}

Next, we define what the results should look like. We will use a message like You win! or You lose! to display the results.

type Result @embedded {
  selection: Selection!
  opponentSelection: Selection!
  message: String!
}

Last, we need a way for you, the player, to make your selection. In this case, the automatic CRUD queries and mutations generated by Fauna are not enough. In order to facilitate the additional logic of our game, we need a custom resolver.

What is that @embedded directive?

By labeling the Result type as embedded, it means Fauna will not create an associated collection nor additional queries and mutations associated with it. This is good for our purposes because we are merely defining the output shape of our game results, we are not planning to store those results anywhere.

For more information, refer to Fauna's docs on the embedded directive.

Implement a custom resolver

To implement a custom resolver, you need 2 things:

A user-defined function (UDF).
A query or mutation that references your UDF with the resolver directive.

This is where fauna-gql-upload really shines.

Create a new file fauna/lib/DetermineResult.ts and add the contents below.

This is a helper function that we'll use to compare our selection with a randomized opponent selection and determine a winner. Since it lives under /lib and not /functions, it will not be registered as a UDF in Fauna.

import { ExprArg, ExprVal, query } from "faunadb";
const { And, Equals, If, Or } = query;

export default function DetermineResult(selection: ExprArg, opponentSelection: ExprArg): ExprVal {
  return {
    selection,
    opponentSelection,
    message: If(
      Equals(selection, opponentSelection),
      "It's a tie!",
      If(
        Or(
          And(
            Equals(selection, "Rock"),
            Equals(opponentSelection, "Scissors")
          ),
          And(
            Equals(selection, "Paper"),
            Equals(opponentSelection, "Rock")
          ),
          And(
            Equals(selection, "Scissors"),
            Equals(opponentSelection, "Paper")
          ),
        ),
        "You win!",
        "You lose!"
      )
    )
  }
}

Now create the file fauna/functions/Play.ts and add the contents below.

This is our UDF. Note that it references the DetermineResult helper function we created above. Since FQL is somewhat verbose, I like to organize my functions like this to keep the logic readable and clean.

This UDF also makes use of some additional helper functions from fauna-fql-lib. Fauna does not provide its own random number generator (yet), but the RandomString function is good enough for our purposes.

The name property is especially important as it will serve as the identifier in the @resolver directive in schema.gql.

import { query } from "faunadb";
import { RandomString, Switch } from "faunadb-fql-lib";
import DetermineResult from '../lib/DetermineResult';
const { Lambda, Let, Query, Var } = query;

const selectionMap = {
  R: "Rock",
  P: "Paper",
  S: "Scissors"
};

const Play = {
  name: "play",
  body: Query(
    Lambda(
      ["selection"],
      Let({
        randomCharacter: RandomString(1, "RPS"),
        opponentSelection: Switch(Var("randomCharacter"), selectionMap),
      },
        DetermineResult(Var("selection"), Var("opponentSelection"))
      )
    )
  ),
};

export = Play;

With the UDF defined, we can now reference it in our GraphQL schema.

Open fauna/schema.gql again and add the following query.

type Query {
  play(selection: Selection!): Result! @resolver(name: "play")
}

This defines a query called play that takes one argument, selection, which will be one of the enum values defined earlier (Rock, Paper, or Scissors). The query returns a non-nullable Result and the @resolver directive tells Fauna to use the play UDF we defined in the fauna/functions/Play.ts file we implemented earlier.

Make it so

So far, we've accomplished the 2 aformentioned requirements for a custom resolver all in our code editor:

We updated our schema in schema.gql
We defined a UDF to implement our game logic.

Now, in one command we can push all of this to Fauna:

npm run fauna

Again, you should see the following output:

✔️  Successfully updated schema.

✔️  Successfully uploaded indexes

✔️  Successfully uploaded functions

✔️  Successfully uploaded roles

Let's play!

Head on over to the Fauna admin UI again. Go to the GraphQL section and execute the query below.

query {
  play(selection: Rock) {
    selection
    opponentSelection
    message
  }
}

You should see output like the following:

{
  "data": {
    "play": {
      "selection": "Rock",
      "opponentSelection": "Scissors",
      "message": "You win!"
    }
  }
}

Conclusion

In this tutorial, we laid a strong foundation for developing any application with Fauna. We can make changes in our code editor and push them to Fauna in a single command. The full source code for this project can be found at fauna-rock-paper-scissors.

If you want to experience a more complete example of what you can build with Fauna and GraphQL, head on over to Botwise Games. I was grateful to find fauna-gql-upload to make my Fauna developer experience for that project even better. Special thanks again to Carl Hallén Jansson for authoring this library and continuing to improve it.

If you have any questions or comments on this tutorial, find me on Twitter @seanconnollydev or seanconnolly.dev.

Up next

In the next post in this series, we will learn how to use Fauna's generated GraphQL schema to build UI for our game with Next.js, TypeScript and Apollo hooks. See you then!