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
$ brew cask install graphql-playground
- ✨ 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
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.
The desktop app is the same as the web version but includes these additional features:
- Partial support for graphql-config enabling features like multi-environment setups (no support for sending HTTP headers).
- Double click on
*.graphql
files.
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.
In the top right corner of the Playground window you can click on the settings icon. These are the settings currently available:
{
'editor.cursorShape': 'line', // possible values: 'line', 'block', 'underline'
'editor.fontFamily': `'Source Code Pro', 'Consolas', 'Inconsolata', 'Droid Sans Mono', 'Monaco', monospace`,
'editor.fontSize': 14,
'editor.reuseHeaders': true, // new tab reuses headers from last tab
'editor.theme': 'dracula', // possible values: 'dark', 'light', 'dracula'
'general.betaUpdates': false,
'prettier.printWidth': 80,
'prettier.tabWidth': 2,
'prettier.useTabs': false,
'request.credentials': 'omit', // possible values: 'omit', 'include', 'same-origin'
'schema.polling.enable': true, // enables automatic schema polling
'schema.polling.endpointFilter': '*localhost*', // endpoint filter for schema polling
'schema.polling.interval': 2000, // schema polling interval in ms
'schema.disableComments': boolean,
'tracing.hideTracingResponse': true,
}
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 hereconfig
string
- the JSON of a GraphQL Config. See an example heresettings
ISettings
- Editor settings in json format as described here
interface ISettings {
'editor.cursorShape': 'line' | 'block' | 'underline'
'editor.fontFamily': string
'editor.fontSize': number
'editor.reuseHeaders': boolean
'editor.theme': 'dark' | 'light' | 'dracula'
'general.betaUpdates': boolean
'prettier.printWidth': number
'prettier.tabWidth': number
'prettier.useTabs': boolean
'request.credentials': 'omit' | 'include' | 'same-origin'
'schema.polling.enable': boolean
'schema.polling.endpointFilter': string
'schema.polling.interval': number
'schema.disableComments': boolean
'tracing.hideTracingResponse': boolean
}
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
name?: 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, subscriptionEndpoint?: string) => ApolloLink
] - this is the equivalent to thefetcher
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.
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:
- The bare minimum HTML needed to render the Playground
- The Playground HTML with full loading animation
Note: In case you do not want to serve assets from a CDN (like jsDelivr) and instead use a local copy, you will need to install graphql-playground-react
from npm, and then replace all instances of //cdn.jsdelivr.net/npm
with ./node_modules
. An example can be found here
yarn add graphql-playground-react
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.
- Open Sans and Source Code Pro fonts
- 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,
)
# 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
We have a full example for each of the frameworks below:
-
Express: See packages/graphql-playground-middleware-express/examples/basic
-
Lambda (as serverless handler): See serverless-graphql-apollo or a quick example below.
yarn add graphql-playground-middleware-lambda
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
$ cd packages/graphql-playground-react
$ yarn
$ yarn start
Open localhost:3000/localDev.html?endpoint=https://api.graph.cool/simple/v1/swapi for local development!
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
}
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.
In the folder packages
you'll find the following packages:
graphql-playground-electron
: Cross-platform electron app which usesgraphql-playground-react
graphql-playground-html
: Simple HTML page rendering a version ofgraphql-playground-react
hosted on JSDelivergraphql-playground-middleware-express
: Express middleware usinggraphql-playground-html
graphql-playground-middleware-hapi
: Hapi middleware usinggraphql-playground-html
graphql-playground-middleware-koa
: Koa middleware usinggraphql-playground-html
graphql-playground-middleware-lambda
: AWS Lambda middleware usinggraphql-playground-html
graphql-playground-react
: Core of GraphQL Playground built with ReactJS
Join our Slack community if you run into issues or have questions. We love talking to you!