skevy / graphql-playground

🎮 GraphQL IDE for better development workflows (GraphQL Subscriptions, interactive docs & collaboration)

GraphQL IDE for better development workflows (GraphQL Subscriptions, interactive docs & collaboration).
You can download the desktop app or use the web version at graphqlbin.com: Demo

Installation

$ brew cask install graphql-playground

Features

• ✨ Context-aware autocompletion & error highlighting
• 📚 Interactive, multi-column docs (keyboard support)
• ⚡️ Supports real-time GraphQL Subscriptions
• ⚙ GraphQL Config support with multiple Projects & Endpoints
• 🚥 Apollo Tracing support

FAQ

How is this different from GraphiQL?

GraphQL Playground uses components of GraphiQL under the hood but is meant as a more powerful GraphQL IDE enabling better (local) development workflows. Compared to GraphiQL, the GraphQL Playground ships with the following additional features:

• Interactive, multi-column schema documentation
• Automatic schema reloading
• Support for GraphQL Subscriptions
• Query history
• Configuration of HTTP headers
• Tabs

See the following question for more additonal features.

What's the difference between the desktop app and the web version?

The desktop app is the same as the web version but includes these additional features:

• Support for graphql-config enabling features like multi-environment setups.
• Double click on *.graphql files.

How does GraphQL Bin work?

You can easily share your Playgrounds with others by clicking on the "Share" button and sharing the generated link. You can think about GraphQL Bin like Pastebin for your GraphQL queries including the context (endpoint, HTTP headers, open tabs etc).

You can also find the announcement blog post here.

Settings

In the top right corner of the Playground window you can click on the settings icon. These are the settings currently available:

{
  'general.betaUpdates': false,
  'editor.cursorShape': 'line', // possible values: 'line', 'block', 'underline'
  'editor.fontSize': 14,
  'editor.fontFamily': `'Source Code Pro', 'Consolas', 'Inconsolata', 'Droid Sans Mono', 'Monaco', monospace`,
  'editor.theme': 'dark', // possible values: 'dark', 'light'
  'editor.reuseHeaders': true,
  'request.credentials': 'omit', // possible values: 'omit', 'include', 'same-origin'
  'tracing.hideTracingResponse': true,
}

Usage

Properties

The React component <Playground /> and all middlewares expose the following options:

• props (Middlewares & React Component)
  • endpoint string - the GraphQL endpoint url.
  • subscriptionEndpoint string - the GraphQL subscriptions endpoint url.
  • workspaceName string - in case you provide a GraphQL Config, you can name your workspace here
  • config string - the JSON of a GraphQL Config. See an example here
  • settings ISettings - Editor settings in json format as described here

interface ISettings {
  'general.betaUpdates': boolean
  'editor.theme': Theme
  'editor.reuseHeaders': boolean
  'tracing.hideTracingResponse': boolean
  'editor.fontSize': number
  'editor.fontFamily': string
  'request.credentials': string
}

• schema IntrospectionResult - The result of an introspection query (an object of this form: {__schema: {...}}) The playground automatically fetches the schema from the endpoint. This is only needed when you want to override the schema.
• tabs Tab[] - An array of tabs to inject. Note: When using this feature, tabs will be resetted each time the page is reloaded

interface Tab {
  endpoint: string
  query: string
  variables?: string
  responses?: string[]
  headers?: { [key: string]: string }
}

In addition to this, the React app provides some more properties:

• props (React Component)
• createApolloLink [(session: Session) => ApolloLink] - this is the equivalent to the fetcher of GraphiQL. For each query that is being executed, this function will be called

createApolloLink is only available in the React Component and not the middlewares, because the content must be serializable as it is being printed into a HTML template.

As HTML Page

If you simply want to render the Playground HTML on your own, for example when implementing a GraphQL Server, there are 2 options for you:

1. The bare minimum HTML needed to render the Playground
2. The Playground HTML with full loading animation

As React Component

Install

yarn add graphql-playground-react

Use

GraphQL Playground provides a React component responsible for rendering the UI and Session management. There are 3 dependencies needed in order to run the graphql-playground-react React component.

1. Open Sans and Source Code Pro fonts
2. Rendering the <Playground /> component

The GraphQL Playground requires React 16.

Including Fonts (1.)

<link href="https://fonts.googleapis.com/css?family=Open+Sans:300,400,600,700|Source+Code+Pro:400,700" rel="stylesheet">

Including stylesheet and the component (2., 3.)

import React from 'react'
import ReactDOM from 'react-dom'
import { Provider } from 'react-redux'
import { Playground, store } from 'graphql-playground-react'

ReactDOM.render(
  <Provider store={store}>
    <Playground endpoint="https://api.graph.cool/simple/v1/swapi" />
  </Provider>,
  document.body,
)

As Server Middleware

Install

# Pick the one that matches your server framework
yarn add graphql-playground-middleware-express  # for Express or Connect
yarn add graphql-playground-middleware-hapi
yarn add graphql-playground-middleware-koa
yarn add graphql-playground-middleware-lambda

Usage with example

We have a full example for each of the frameworks below:

• Express: See packages/graphql-playground-middleware-express/examples/basic

• Hapi: See packages/graphql-playground-middleware-hapi

• Koa: See packages/graphql-playground-middleware-koa

• Lambda (as serverless handler): See serverless-graphql-apollo or a quick example below.

As serverless handler

Install

yarn add graphql-playground-middleware-lambda

Usage

handler.js

import lambdaPlayground from 'graphql-playground-middleware-lambda'
// or using require()
// const lambdaPlayground = require('graphql-playground-middleware-lambda').default

exports.graphqlHandler = function graphqlHandler(event, context, callback) {
  function callbackFilter(error, output) {
    // eslint-disable-next-line no-param-reassign
    output.headers['Access-Control-Allow-Origin'] = '*'
    callback(error, output)
  }

  const handler = graphqlLambda({ schema: myGraphQLSchema })
  return handler(event, context, callbackFilter)
}

exports.playgroundHandler = lambdaPlayground({
  endpoint: '/dev/graphql',
})

serverless.yml

functions:
  graphql:
    handler: handler.graphqlHandler
    events:
    - http:
        path: graphql
        method: post
        cors: true
  playground:
    handler: handler.playgroundHandler
    events:
    - http:
        path: playground
        method: get
        cors: true

Development

$ cd packages/graphql-playground-react
$ yarn
$ yarn start

Open localhost:3000/localDev.html?endpoint=https://api.graph.cool/simple/v1/swapi for local development!

Custom Theme

From graphql-playground-react@1.7.0 on you can provide a codeTheme property to the React Component to customize your color theme. These are the available options:

export interface EditorColours {
  property: string
  comment: string
  punctuation: string
  keyword: string
  def: string
  qualifier: string
  attribute: string
  number: string
  string: string
  builtin: string
  string2: string
  variable: string
  meta: string
  atom: string
  ws: string
  selection: string
  cursorColor: string
  editorBackground: string
  resultBackground: string
  leftDrawerBackground: string
  rightDrawerBackground: string
}

Versions

This is repository is a "mono repo" and contains multiple packages using Yarn workspaces. Please be aware that versions are not synchronised between packages. The versions of the release page refer to the electron app.

Packages

In the folder packages you'll find the following packages:

• graphql-playground-electron: Cross-platform electron app which uses graphql-playground-react
• graphql-playground-html: Simple HTML page rendering a version of graphql-playground-react hosted on JSDeliver
• graphql-playground-middleware-express: Express middleware using graphql-playground-html
• graphql-playground-middleware-hapi: Hapi middleware using graphql-playground-html
• graphql-playground-middleware-koa: Koa middleware using graphql-playground-html
• graphql-playground-middleware-lambda: AWS Lambda middleware using graphql-playground-html
• graphql-playground-react: Core of GraphQL Playground built with ReactJS

Help & Community

Join our Slack community if you run into issues or have questions. We love talking to you!