@sgrove/graphiql-code-exporter

    3.0.8 • Public • Published

    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.

    Install

    npm i @sgrove/graphiql-code-exporter

    DownloadsWeekly Downloads

    25

    Version

    3.0.8

    License

    MIT

    Unpacked Size

    296 kB

    Total Files

    61

    Last publish

    Collaborators

    • sgrove