Skip to content

Commit d137a11

Browse files
timsuchanektimsuchanek
committed
update readme
1 parent ec441b7 commit d137a11

File tree

1 file changed

+81
-77
lines changed

1 file changed

+81
-77
lines changed

‎packages/graphql-playground/README.md‎

Lines changed: 81 additions & 77 deletions
Original file line numberDiff line numberDiff line change
@@ -44,112 +44,116 @@ You can easily share your Playgrounds with others by clicking on the "Share" but
4444

4545
## Usage
4646

47-
[examples/latest.html](https://github.com/graphcool/graphql-playground/blob/master/packages/graphql-playground/examples/latest.html) contains a simple example on how to use the latest playground in your application.
47+
### Properties
48+
All interfaces, the React component `<Playground />` and all middlewares expose the same set of options:
4849

49-
You also can use the latest playground based on the npm package.
50-
In order to do that, first you need to install `graphql-playground` via NPM. Then choose one of the following options to use the Playground in your own app/server.
50+
+ `properties`
51+
+ `endpoint` [`string`] - the GraphQL endpoint url.
52+
+ `subscriptionEndpoint` [`string`] - the GraphQL subscriptions endpoint url.
53+
+ `setTitle` [`boolean`] - reflect the current endpoint in the page title
5154

52-
```
55+
### As React Component
56+
57+
#### Install
58+
```sh
5359
yarn add graphql-playground
5460
```
5561

56-
### As React Component
62+
#### Use
63+
GraphQL Playground provides a React component responsible for rendering the UI and Session management.
64+
There are **3 dependencies** needed in order to run the `graphql-playground` React component.
65+
1. _Open Sans_ and _Source Code Pro_ fonts
66+
2. Including `graphql-playground/playground.css`
67+
3. Rendering the `<Playground />` component
5768

58-
GraphQL Playground provides a React component responsible for rendering the UI, which should be provided with a function for fetching from GraphQL, we recommend using the [fetch](https://fetch.spec.whatwg.org/) standard API.
69+
The GraphQL Playground requires **React 16**.
70+
71+
Including Fonts (`1.`)
72+
```html
73+
<link href="https://fonts.googleapis.com/css?family=Open+Sans:300,400,600,700|Source+Code+Pro:400,700" rel="stylesheet">
74+
```
5975

76+
Including stylesheet and the component (`2., 3.`)
6077
```js
6178
import React from 'react'
6279
import ReactDOM from 'react-dom'
6380
import Playground from 'graphql-playground'
64-
import fetch from 'isomorphic-fetch'
81+
import 'graphql-playground/playground.css'
6582

66-
function graphQLFetcher(graphQLParams) {
67-
return fetch(window.location.origin + '/graphql', {
68-
method: 'post',
69-
headers: { 'Content-Type': 'application/json' },
70-
body: JSON.stringify(graphQLParams),
71-
}).then(response => response.json())
72-
}
73-
74-
ReactDOM.render(<Playground fetcher={graphQLFetcher} />, document.body)
83+
ReactDOM.render(<Playground endpoint="https://api.graph.cool/simple/v1/swapi" />, document.body)
7584
```
7685

77-
### As Express Middleware
78-
79-
#### Properties
80-
Express middleware supports the following properties:
81-
82-
+ `options`
83-
+ `endpoint` [`string`] - the GraphQL endpoint url.
84-
85-
#### Usage
86-
```js
87-
import express from 'express'
88-
import { express as playground } from 'graphql-playground/middleware'
86+
### As Server Middleware
8987

90-
const app = express()
91-
92-
app.use('/playground', playground({ endpoint: '/graphql' }))
93-
94-
app.listen(3000)
88+
#### Install
89+
```sh
90+
# Pick the one that matches your server framework
91+
yarn add graphql-playground-middleware-express # for Express or Connect
92+
yarn add graphql-playground-middleware-hapi
93+
yarn add graphql-playground-middleware-koa
94+
yarn add graphql-playground-middleware-lambda
9595
```
9696

97-
### As Hapi Middleware
97+
#### Usage with example
9898

99-
#### Properties
100-
Hapi middleware supports the following properties:
99+
We have a full example for each of the frameworks below:
101100

102-
+ `options`
103-
+ `path` [`string`] - the Playground middleware url
104-
+ `playgroundOptions`
105-
+ `endpoint` [`string`] - the GraphQL endpoint url.
106-
+ `subscriptionEndpoint` [`string`] - the GraphQL subscription endpoint url.
101+
- **Express:** See [packages/graphql-playground-middleware-express/examples/basic](https://github.com/graphcool/graphql-playground/tree/master/packages/graphql-playground-middleware-express/examples/basic)
107102

108-
#### Usage
109-
```js
110-
import hapi from 'hapi'
111-
import { hapi as playground } from 'graphql-playground/middleware'
103+
- **Hapi:** See [packages/graphql-playground-middleware/examples/hapi](https://github.com/graphcool/graphql-playground/tree/master/packages/graphql-playground-middleware/examples/hapi)
112104

113-
const server = new Hapi.Server()
105+
- **Koa:** See [packages/graphql-playground-middleware/examples/koa](https://github.com/graphcool/graphql-playground/tree/master/packages/graphql-playground-middleware/examples/koa)
114106

115-
server.connection({
116-
port: 3001
117-
})
107+
- **Lambda (as serverless handler):** See [serverless-graphql-apollo](https://github.com/serverless/serverless-graphql-apollo) or a quick example below.
118108

119-
server.register({
120-
register: playground,
121-
options: {
122-
path: '/playground',
123-
endpoint: '/graphql'
124-
}
125-
},() => server.start())
109+
### As serverless handler
110+
#### Install
111+
```sh
112+
yarn add graphql-playground-middleware-lambda
126113
```
127114

128-
### As Koa Middleware
129-
130-
#### Properties
131-
Koa middleware supports the following properties:
132-
133-
+ `options`
134-
+ `endpoint` [`string`] - the GraphQL endpoint url.
135-
+ `subscriptionEndpoint` [`string`] - the GraphQL subscription endpoint url.
136-
137115
#### Usage
116+
`handler.js`
117+
138118
```js
139-
import Koa from 'koa'
140-
import KoaRouter from 'koa-router'
141-
import { koa as playground } from 'graphql-playground/middleware'
119+
import lambdaPlayground from 'graphql-playground-middleware-lambda'
120+
// or using require()
121+
// const lambdaPlayground = require('graphql-playground-middleware-lambda').default
122+
123+
exports.graphqlHandler = function graphqlHandler(event, context, callback) {
124+
function callbackFilter(error, output) {
125+
// eslint-disable-next-line no-param-reassign
126+
output.headers['Access-Control-Allow-Origin'] = '*';
127+
callback(error, output);
128+
}
142129

143-
const app = new Koa()
144-
const router = new KoaRouter()
130+
const handler = graphqlLambda({ schema: myGraphQLSchema });
131+
return handler(event, context, callbackFilter);
132+
};
145133

146-
router.all('/playground', playground({
147-
endpoint: '/graphql'
148-
}))
134+
exports.playgroundHandler = lambdaPlayground({
135+
endpoint: '/dev/graphql',
136+
});
137+
```
149138

150-
app.use(router.routes())
151-
app.use(router.allowedMethods())
152-
app.listen(3001)
139+
`serverless.yml`
140+
141+
```yaml
142+
functions:
143+
graphql:
144+
handler: handler.graphqlHandler
145+
events:
146+
- http:
147+
path: graphql
148+
method: post
149+
cors: true
150+
playground:
151+
handler: handler.playgroundHandler
152+
events:
153+
- http:
154+
path: playground
155+
method: get
156+
cors: true
153157
```
154158
155159
## Development [![npm version](https://badge.fury.io/js/graphql-playground.svg)](https://badge.fury.io/js/graphql-playground)
@@ -162,7 +166,7 @@ $ yarn
162166
$ yarn start
163167
```
164168
Open
165-
[localhost:3000](http://localhost:3000/?endpoint=https://api.graph.cool/simple/v1/cj56h35ol3y93018144iab4wo&subscription=wss://subscriptions.graph.cool/v1/cj56h35ol3y93018144iab4wo)
169+
[localhost:3000/middleware.html?endpoint=https://api.graph.cool/simple/v1/swapi](http://localhost:3000/middleware.html?endpoint=https://api.graph.cool/simple/v1/swapi) for local development!
166170

167171

168172
<a name="help-and-community" />

0 commit comments

Comments
 (0)