Putting GraphQL Playground in front of AppSync
Tags: graphql, playground, appsync
Published: 2020-02-23 09:12:18

Prerequisite knowledge: Node, NPM and AWS AppSync

[AWS AppSync](https://aws.amazon.com/appsync/) is a service for hosting a [GraphQL](https://graphql.org/) API with cool features like being able to generate backend resources based on a schema. We can inspect and debug that API from the queries tab in the AppSync console. But there's another tool called [GraphQL Playground](https://github.com/prisma-labs/graphql-playground) that has a lot more features like tabs, history, prettification, complete schema inspection and custom settings. It's also nice not having to login to AWS in order to debug or play around with our GraphQL API. So let's take a look at how we can hook up GraphQL Playground to AppSync.

### Step 1: Install the necessary packages

After setting up your project with npm, we are going to install the following dependencies:

`npm i -S express @workpop/graphql-proxy graphql-playground-middleware-express babel-runtime`

We are going to run a node server using [express](https://expressjs.com/). Then we need a way to proxy our GraphQL API so that our queries and mutations get forwarded to AppSync. That's where [@workpop/graphql-proxy](https://www.npmjs.com/package/@workpop/graphql-proxy) comes in. This package is built for schema stitching, which is useful if you need to combine multiple GraphQL endpoints (you can read more about that in [this blogpost](https://blog.cloudboost.io/building-a-graphql-proxy-part-1-88548667dde2)). But for our purpose we are happy with just the proxying. Finally, [graphql-playground-middleware-express](https://www.npmjs.com/package/graphql-playground-middleware-express) will give us an endpoint for the GraphQL Playground IDE.

### Step 2: Get your API details

Within the Appsync console, navigate to the **Schema** tab, click **Export schema** and choose `schema.graphql`. Save it to your project directory, rename the file to `schema.js`. Surround schema with backticks and export the string, so it will look like this:

```js
// schema.js
module.exports = `
  <YOUR SCHEMA HERE>
`;
```

Now we just need the URL and Api key. Back in the Appsync console, navigate to the **Settings** tab and copy your **API URL** and a valid **API key**. Alternatively, if you've used [Amplify](https://aws.amazon.com/amplify/) to setup your API you can also get theses details by running `amplify status` from your terminal. You can put these values in a `.env` file which you can read with [dotenv](https://github.com/motdotla/dotenv), but for this example we'll just put them in a javascript file:

```js
// settings.js
module.exports = {
  API_KEY: "<your api key here>",
  API_URL: "<your endpoint here>"
};
```

Don't forget to add this file to your `.gitignore` if you're using git!

### Step 3: The code

Now all that's left to do is write a little express server:

```js
// server.js
const express = require("express");
const registerServices = require("@workpop/graphql-proxy").default;
const expressPlayground = require("graphql-playground-middleware-express").default;
const types = require("./schema.js");
const { API_KEY, API_URL } = require("./settings.js");

const SERVICE_CONFIG = {
  APPSYNC: {
    address: API_URL,
    typeDefs: types
  }
};

const PORT = 4000;
const app = express();
app.get("/playground", expressPlayground({ endpoint: "/graphql" }));

registerServices({
  SERVICE_CONFIG,
  server: app,
  masterTypeDefs: types,
  customHeaders: {
    "x-api-key": API_KEY
  },
  enableGrqphiQL: true
}).then(() => {
  app.listen(PORT, () =>
    console.log(
      `Running playground proxy on http://localhost:${PORT}/playground`
    )
  );
});
```

Now start your server with `node server.js` et voila. Happy querying!

Edit:
Note that AppSync might have some AWS directives in your exported schema which graphql-proxy cannot recognize, so you will have to remove those manually.