GraphiQL

GraphiQL is an in-browser IDE for writing, validating, and testing GraphQL queries.

You can configure or completely disable GraphiQL with the graphiql option. By default, GraphiQL is only enabled.

Example

import { createYoga } from 'graphql-yoga'
 
// Provide your schema
const yoga = createYoga({
  graphiql: {
    defaultQuery: /* GraphQL */ `
      query {
        hello
      }
    `
  }
})
// Start the server and explore http://localhost:4000/graphql
const server = createServer(yoga)
server.listen(4000, () => {
  console.info('Server is running on http://localhost:4000/graphql')
})

Disabling GraphiQL

You can disable GraphiQL simply by setting graphiql: false.

import { createYoga } from 'graphql-yoga'
 
// Provide your schema
const yoga = createYoga({ graphiql: false })
 
// Start the server and explore http://localhost:4000/graphql
const server = createServer(yoga)
server.listen(4000, () => {
  console.info('Server is running on http://localhost:4000/graphql')
})

💡

Be aware that this does not really make your GraphQL server more secure. As long as the introspection and/or the "did you mean x" suggestion feature of GraphQL are enabled.

import { createYoga } from 'graphql-yoga'
import { useDisableIntrospection } from '@envelop/disable-introspection'
 
// Provide your schema
const yoga = createYoga({
  graphiql: false,
  plugins: [useDisableIntrospection()]
})
// Start the server and explore http://localhost:4000/graphql
const server = createServer(yoga)
server.listen(4000, () => {
  console.info('Server is running on http://localhost:4000/graphql')
})

Disabling the "did you mean x" suggestion feature is not possible at the moment (see the corresponding graphql-js GitHub issue).

As a workaround you can use the maskedError option for masking validation and parse errors.

import { createYoga } from 'graphql-yoga'
import { useDisableIntrospection } from '@envelop/disable-introspection'
 
// Provide your schema
const yoga = createYoga({
  graphiql: false,
  plugins: [useDisableIntrospection()],
  maskedErrors: {
    handleParseErrors: true,
    handleValidationErrors: true
  }
})
// Start the server and explore http://localhost:4000/graphql
const server = createServer(yoga)
server.listen(4000, () => {
  console.info('Server is running on http://localhost:4000/graphql')
})

So if your goal is to avoid unknown actors from reverse-engineering your GraphQL schema and executing arbitrary operations, it is highly recommended to use persisted operations. Envelop has the plugin @envelop/persisted-operations that can be used with GraphQL Yoga.

A more detailed guide and example for adding persisted operations to GraphQL Yoga will follow.

Dynamic Options

You can also dynamically set GraphiQL options based on the incoming request. This allows rendering GraphiQL conditionally e.g. based on a header presence or value.

import { createYoga } from 'graphql-yoga'
 
// Provide your schema
const yoga = createYoga({
  graphiql(request) {
    if (request.headers.get('graphiql-enabled')) {
      return true
    }
    return false
  }
})
// Start the server and explore http://localhost:4000/graphql
const server = createServer(yoga)
server.listen(4000, () => {
  console.info('Server is running on http://localhost:4000/graphql')
})

Within the function passed to graphiql you also have access to the serverContext. E.g. on Node.js it contains the http.Request and http.Response objects.

import { createYoga } from 'graphql-yoga'
 
// Provide your schema
const yoga = createYoga({
  graphiql(request, { req, res }) {
    // access something attached to the request object
    // e.g. an user object added by an auth middleware.
    if (req.user.role === 'admin') {
      return true
    }
    return false
  }
})
// Start the server and explore http://localhost:4000/graphql
const server = createServer(yoga)
server.listen(4000, () => {
  console.info('Server is running on http://localhost:4000/graphql')
})

Offline Usage

By default, GraphiQL code is served from a CDN because if we added GraphiQL code inside Yoga, it would end up with huge bundle size and exceed the payload limit for some environments for example (CF Workers, AWS etc). If you want to use GraphiQL from a local version, you need to install it manually.

yarn add @graphql-yoga/render-graphiql

And you need to pass imported renderGraphiQL to createServer like below:

import { createYoga } from 'graphql-yoga'
import { renderGraphiQL } from '@graphql-yoga/render-graphiql'
 
const yoga = createYoga({ renderGraphiQL })

Last updated on October 2, 2022

Apollo Federation CORS