diff --git a/docs/_config.yml b/docs/_config.yml index 4135ecd12aa..ad0858d02d2 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -21,7 +21,7 @@ sidebar_categories: - features/data-sources - features/subscriptions - features/metrics - - features/playground + - features/graphql-playground - features/scalars-enums - features/unions-interfaces - features/directives diff --git a/docs/source/features/graphql-playground.md b/docs/source/features/graphql-playground.md new file mode 100644 index 00000000000..2604416dcc8 --- /dev/null +++ b/docs/source/features/graphql-playground.md @@ -0,0 +1,48 @@ +--- +title: GraphQL Playground +description: Visually exploring an Apollo Server +--- + +[GraphQL Playground](https://github.com/prismagraphql/graphql-playground) is a graphical, interactive, in-browser GraphQL IDE, created by [Prisma](https://www.prisma.io/) and based on [GraphiQL](https://github.com/graphql/graphiql). + +In development, Apollo Server enables GraphQL Playground on the same URL as the GraphQL server itself (e.g. `http://localhost:4000/graphql`) and automatically serves the GUI to web browsers. When `NODE_ENV` is set to `production`, GraphQL Playground (as well as introspection) is disabled as a production best-practice. + +
+![GraphQL Playground](../images/graphql-playground.png) +
+ +## Enabling GraphQL Playground in production + +To enable GraphQL Playground in production, an integration package must be installed to provide more control over the middlewares used. The following example uses the express integration: + +```bash +npm install --save apollo-server-express@rc graphql +``` + +Introspection and the GUI can be enabled explicitly in the following manner. + +```js line=8,16 +const { ApolloServer } = require('apollo-server-express'); +const express = require('express'); +const { typeDefs, resolvers } = require('./schema'); + +const server = new ApolloServer({ + typeDefs, + resolvers, + introspection: true, +}); + +const app = express(); + +// `gui` accepts a GraphQL Playground configuration +server.applyMiddleware({ + app, + gui: true, +}); + +app.listen({ port: 4000 }, () => + console.log(`🚀 Server ready at http://localhost:4000${server.graphqlPath}`), +); +``` + +> Note: When using the `apollo-server-express` package, the `apollo-server` package can be uninstalled. diff --git a/docs/source/features/playground.md b/docs/source/features/playground.md deleted file mode 100644 index 230139ecbdb..00000000000 --- a/docs/source/features/playground.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: GraphQL Playground -description: Visually exploring a Apollo Server ---- - -[GraphQL Playground](https://github.com/prismagraphql/graphql-playground) is a graphical interactive in-browser GraphQL IDE, created by [Prisma](https://www.prisma.io/), based on [GraphiQL](https://github.com/graphql/graphiql). In development, Apollo Server collocates a GraphQL Playground instance with the GraphQL path. When a browser sends a request to Apollo Server, it receives the GraphQL Playground gui. When `NODE_ENV` is set to production, introspection and Playground are disabled as a production best practice. - -
-![GraphQL Playground](../images/playground.png) -
- -## Enabling Playground in Production - -To enable Playground in production, an integration package must be installed to provide more control over the middlewares used. The following example uses the express integration: - -```bash -npm install --save apollo-server-express@rc graphql -``` - -Introspection and the gui can be enabled explicitly in the following manner. - -```js line=8,16 -const { ApolloServer, gql } = require('apollo-server-express'); -const express = require('express'); -const { typeDefs, resolvers } = require('./schema'); - -const server = new ApolloServer({ - typeDefs, - resolvers, - introspection: true, -}); - -const app = express(); - -// gui accepts a Playground configuration -server.applyMiddleware({ - app, - gui: true, -}); - -app.listen({ port: 4000 }, () => - console.log(`🚀 Server ready at http://localhost:4000${server.graphqlPath}`), -); -``` - -> Note: when using apollo-server-express, you can remove apollo-server from your package.json diff --git a/docs/source/images/playground.png b/docs/source/images/graphql-playground.png similarity index 100% rename from docs/source/images/playground.png rename to docs/source/images/graphql-playground.png