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

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.

...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.

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:

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

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

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

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

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.

* 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!

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.

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.

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]

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

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:

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:

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.

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.

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.

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.

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:

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:

The query variables dictate the FindExampleQueryVariables type.

The query body dictates the FindExampleQuery type.

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

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:

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.

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:

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:

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

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

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:

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

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:

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:

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

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.

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:

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:

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.

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.

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! 👏🏻

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 below 👇🏻.