Keystone on Azure: Part 1 - Local Dev

As I’ve been exploring GraphQL on Azure through my series of the same name I wanted to take a look at how we can run applications that provide GraphQL as an endpoint easily, specifically those which we’d class as headless CMSs (Content Management Systems).

So let’s start a new series in which we look at one such headless CMS, Keystone 6. Keystone is an open source project created by the folks over at Thinkmill and gives you a code-first approach to creating content types (models for the data you store), a web UI to edit the content and a GraphQL API in which you can consume the data via.

Note: At the time of writing, Keystone 6 is still in pre-release, so some content might change when GA hits.

In this series we’re going to create an app using Keystone, look at the services on Azure that we’d need to host it and how to deploy it using GitHub Actions. But first up, let’s look at the local development experience and how we can optimise it for the way that (I think) gives you the best bang for buck.

Setting up Keystone

The easiest way to setup Keystone is to use the create-keystone-app generator, which you can read about in their docs. I’m going to use npm as the package manager, but you’re welcome to use yarn if that’s your preference.

npm init keystone-app@latest azure-keystone-demo

This will create the app in the azure-keystone-demo folder, but feel free to change the folder name to whatever you want.

Configuring VS Code

I use VS Code for all my development, so I’m going to show you how to set it up for optimal use in VS Code.

Once we’ve opened VS Code the first thing we’ll do is add support for Remote Container development. I’ve previously blogged about why you need remote containers in projects and I do all of my development in them these days as I love having a fully isolated dev environment that only has the tooling I need at that point in time.

You’ll need to have the Remote - Containers extension extension installed.

Open the VS Code Command Pallette (F1/CTRL+SHIFT+P) and type Remote-Containers: Add Development Container Configuration Files and select the TypeScript and Node.js definition.

Before we reopen VS Code with the remote container we’re going to do some tweaks to it. Open the .devcontainer/devcontainer.json file and let’s add a few more extensions:

  "extensions": [
    "dbaeumer.vscode-eslint",
    "esbenp.prettier-vscode",
    "apollographql.vscode-apollo",
    "prisma.prisma",
    "github.vscode-pull-request-github",
    "eg2.vscode-npm-script",
    "alexcvzz.vscode-sqlite"
  ],

This will configure VS Code with eslint, prettier, Apollo’s GraphQL plugin (for GraphQL language support), Prisma’s plugin (for Prisma language support), GitHub integration, npm and a sqlite explorer.

Since we’re using SQLite for local dev I find it useful to install the SQLite plugin for VS Code but that does mean that we need the sqlite3 package installed into our container, so let’s add that by opening the Dockerfile and adding the following line:

RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
    && apt-get -y install --no-install-recommends sqlite3

Lastly, I like to add a postCreateCommand to my devcontainer.json file that does npm install, so all my dependencies are installed when the container starts up (if you’re using yarn, then make the command yarn install instead).

Another useful thing you can do is setup some VS Code Tasks so that you can run the different commands (like dev, start, build) rather than using the terminal, but that’s somewhat personal preference so I’ll leave it as an exercise for the reader.

And with that done, you’re dev environment is ready to go, use the command pallette to reopen VS Code in a container and you’re all set.

Conclusion

I know that this series is called “Keystone on Azure” and we didn’t do anything with Azure, but I thought it was important to get ourselves setup and ready to go so that when we are ready to work with Azure, it’s as easy as can be.