Skip to content

OneGraph/graphiql-code-exporter

Repository files navigation

Code Exporter for GraphiQL

A GraphiQL addon that generates ready-to-run code for your queries and mutations.
It provides a wide range of default snippets, but is also extendable with custom snippets.

Bundlesize

Demo

Read the introduction blog post to learn why and how we built it!

Installation

# yarn
yarn add graphiql-code-exporter

# npm
npm i --save graphiql-code-exporter

Built-in Snippets

  • JavaScript
    • fetch
    • react-apollo

< your favorite language/framework/library >

Usage

import React, { Component, Fragment } from 'react'
import GraphiQL from 'graphiql'
import CodeExporter from 'graphiql-code-exporter'
import 'graphiql-code-exporter/CodeExporter.css';

// Optional if you want to use a custom theme
import 'codemirror/theme/neo.css';

const serverUrl = /* your server url here */

export default class GraphiQLWithCodeExporter extends Component {
  state = {
    codeExporterIsVisible: false,
    query: ''
  }

  toggleCodeExporter = () => this.setState({
    codeExporterIsVisible: !this.state.codeExporterIsVisible
  })

  updateQuery = query => this.setState({
    query
  })

  render() {
    const { query, codeExporterIsVisible } = this.state

    const codeExporter = codeExporterIsVisible ? (
      <CodeExporter
        hideCodeExporter={this.toggleCodeExporter}
        snippets={snippets}
        serverUrl={serverUrl}
        context={{
          appId: /* APP_ID */
        }}
        headers={{
          Authorization: 'Bearer ' + /* AUTH_TOKEN */
        }}
        query={query}
        // Optional if you want to use a custom theme
        codeMirrorTheme="neo"
      />
    ) : null

    return (
      <Fragment>
        <GraphiQL
          onEditQuery={this.updateQuery}
          query={query}>
          <GraphiQL.Button
            onClick={this.toggleCodeExporter}
            label="Code Exporter"
            title="Toggle Code Exporter"
          />
        </GraphiQL>
        {codeExporter}
      </Fragment>
    )
  }
}

Props

Property Type Description
hideCodeExporter Function A callback function that is called when clicking the close (x) button in the upper right corner of the panel.
serverUrl URI The server url for your GraphQL endpoint.
query string A string containing the GraphQL query that is synced with the GraphiQL query editor.
snippets Snippet[] A list of snippet objects that one can choose from to generate code snippets.
headers Object?  An optional object containing app specific HTTP headers
context Object?  An optional object containing any additional keys required to render app specific snippets
codeMirrorTheme string? The name of the CodeMirror theme you'd like to use e.g. neo. Make sure to also import the theme's css in your code (e.g. import 'codemirror/theme/neo.css')

Snippets

What we call snippet here, is actually an object with 4 required keys.

Key Type Description
name string A name that is used to identify the snippet.
language string A language string that is used to group the snippets by language.
codeMirrorMode string A valid CodeMirror mode used for syntax highlighting. Make sure to also require the mode (e.g. import 'codemirror/mode/jsx/jsx'
options Option[] Options are rendered as checkboxes and can be used to customize snippets. They must have an unique id, a label and an initial value of either true or false.
generate Function A function that returns the generated code as a single string. It receives below listed data as an object.
generateCodesandboxFiles Function A function that returns a set of codesandbox files, e.g. {'index.js': {content: 'console.log("hello world")'}}. It receives below listed data as an object.

Snippet Data

Key Type  Description
serverUrl string The passed GraphQL server url
operations Operation[] A list of GraphQL operations where each operation has the operation keys.
options Object  A map of option-boolean pairs providing whether an option is selected or not
headers Object? The headers object that is passed to the CodeExporter component
context Object? The context object that is passed to the CodeExporter component
Operation
Key  Type Description
name string The selected GraphQL operation name
type "query" | "mutation" The selected operation's type
query  string  A formatted string containing the GraphQL operation
variableName string The operation name but in UPPER_CASE as that's the common way to declare GraphQL operations in JavaScript
operation Object The plain GraphQL parser result for this operation
variables Object  A map of all used variables for this specific operation

Example

The following example implements a subset of the built-in Fetch API snippet.
The output will look similar to the demo above.

const fetchSnippet = {
  language: 'JavaScript',
  prismLanguage: 'javascript',
  name: 'Fetch API',
  options: [
    {
      id: 'server',
      label: 'server-side usage',
      initial: false,
    },
  ],
  generate: ({serverUrl, operations, options}) => {
    // we only render the first operation here
    const {query} = operations[0];

    const serverImport = options.server
      ? 'import { fetch } from "node-fetch"'
      : '';

    return `
${serverImport}

const res = await fetch("${serverUrl}", {
  method: 'POST',
  body: JSON.stringify({ query: \`${query}\` }),
})
const { errors, data } = await res.json()

// Do something with the response
console.log(data, errors)
`;
  },
};

Extending the built-in snippets

If we want to use both custom and all the built-in snippets, we can import them from npm.

import snippets from 'graphiql-code-exporter/lib/snippets'

const customSnippet = /* custom snippet */

const extendedSnippets = [
  ...snippets,
  customSnippet
]

This is also useful if you want to filter or modify single snippets.

License

graphiql-code-exporter is licensed under the MIT License.
Documentation is licensed under Creative Common License.
Created with ♥ by @rofrischmann and all the great contributors.