Upgrading graphiql from 4.x to 5.0.0

Starting from GraphiQL 5, you need to set up Monaco workers in your project:

• For Vite projects you must:

  1. Install vite-plugin-monaco-editor package:
  shCopy

  npm install vite-plugin-monaco-editor --save-dev
  

  2. Import and configure the plugin in your vite.config.mjs file:
  diffCopy

  // vite.config.mjs
  import { defineConfig } from 'vite'
  import react from '@vitejs/plugin-react'
  +import $monacoEditorPlugin from 'vite-plugin-monaco-editor'
  
  +const monacoEditorPlugin = $monacoEditorPlugin.default ?? $monacoEditorPlugin
  
  export default defineConfig({
    plugins: [
      react(),
  +   monacoEditorPlugin({
  +     languageWorkers: ['editorWorkerService', 'json'],
  +     customWorkers: [
  +       {
  +         label: 'graphql',
  +         entry: 'monaco-graphql/esm/graphql.worker.js'
  +       }
  +     ]
  +   })
    ]
  })
  

[!NOTE]

See Vite example.

• For Webpack projects such as Next.js you must import:

  jsCopy

  import 'graphiql/setup-workers/webpack';
  

[!NOTE]

See Next.js example.

• For ESM-based CDN usages, you must use ?worker query to load the module as a web worker:

  jsCopy

  import createJSONWorker from 'https://esm.sh/monaco-editor/esm/vs/language/json/json.worker.js?worker';
  import createGraphQLWorker from 'https://esm.sh/monaco-graphql/esm/graphql.worker.js?worker';
  import createEditorWorker from 'https://esm.sh/monaco-editor/esm/vs/editor/editor.worker.js?worker';
  
  globalThis.MonacoEnvironment = {
    getWorker(_workerId, label) {
      switch (label) {
        case 'json':
          return createJSONWorker();
        case 'graphql':
          return createGraphQLWorker();
      }
      return createEditorWorker();
    },
  };
  

[!NOTE]

See CDN example.

Allow to Override All Default GraphiQL Plugins

Starting from GraphiQL 5, you can override all default plugins.

Removing All Default Plugins

To remove all default plugins (currently Doc Explorer and History), set referencePlugin={null} and pass an empty array to the plugins prop:

import { GraphiQL } from 'graphiql';

const myPlugins = [];

function App() {
  return (
    <GraphiQL
      referencePlugin={null} // Removes Doc Explorer plugin
      plugins={myPlugins} // Removes History plugin
    />
  );
}

[!NOTE]

If you're using a custom Doc Explorer, pass it to the referencePlugin prop — not the plugins array. It will be automatically included and always rendered first.

Adding Plugins While Keeping Defaults

If you're adding custom plugins (e.g., the Explorer plugin) and want to keep the History plugin, you must explicitly include it in the plugins array:

import { GraphiQL, HISTORY_PLUGIN } from 'graphiql';
import { explorerPlugin } from '@graphiql/plugin-explorer';

const myPlugins = [HISTORY_PLUGIN, explorerPlugin()];

function App() {
  return <GraphiQL plugins={myPlugins} />;
}

graphiql

[!WARNING]

⚠️ UMD build is removed. Switch to the ESM CDN example.

• Migration from Codemirror to Monaco Editor
  • Replacing codemirror-graphql with monaco-graphql
  • Clicking on a reference in the operation editor now works by holding Cmd on macOS or Ctrl on Windows/Linux
• Support for comments in Variables and Headers editors
• Added new examples: GraphiQL x Vite and GraphiQL x Next.js
• Removed examples: GraphiQL x Parcel and GraphiQL x Create React App
• Removed props
  • query
  • variables
  • headers
  • response
  • readOnly
  • keyMap. To use Vim or Emacs keybindings in Monaco, you can use community plugins. Monaco Vim: https://github.com/brijeshb42/monaco-vim. Monaco Emacs: https://github.com/aioutecism/monaco-emacs
  • validationRules. Use custom GraphQL worker, see https://github.com/graphql/graphiql/tree/main/packages/monaco-graphql#custom-webworker-for-passing-non-static-config-to-worker.'

[!NOTE]

If you used query, variables and headers in integration tests, you can use the new initialQuery, initialVariables and initialHeaders props instead. These props will only be used for the first tab. When opening more tabs, the operation editor will start out empty.

• Added new props
  • initialQuery
  • initialVariables
  • initialHeaders
• feat: allow children: ReactNode for <GraphiQL.Toolbar /> component

@graphiql/react

[!IMPORTANT]

Clicking on a reference in the operation editor now works by holding Cmd on macOS or Ctrl on Windows/Linux.

• usePrettifyEditors, useCopyQuery, useMergeQuery, useExecutionContext, usePluginContext, useSchemaContext, useStorageContext hooks are deprecated.
• Add new useGraphiQL and useGraphiQLActions hooks instead. See updated README for more details about them.
• remove useSynchronizeValue hook
• fix defaultQuery with empty string does not result in an empty default query
• fix defaultQuery, when is set will only be used for the first tab. When opening more tabs, the operation editor will start out empty
• fix execute query shortcut in operation editor, run it even there are no operations in the operation editor
• fix plugin store, save last opened plugin in storage
• remove onClickReference from variable editor
• fix shortcut text per OS for default query and in run query in execute query button's tooltip

The ToolbarMenu component has changed.

• The label and className props were removed

• The button prop should now be a button element

  jsxCopy

  <ToolbarMenu
    label="Options"
    button={
      <ToolbarButton label="Options">
        <SettingsIcon className="graphiql-toolbar-icon" aria-hidden="true" />
      </ToolbarButton>
    }
  >
    <ToolbarMenu.Item onSelect={() => console.log('Clicked!')}>
      Test
    </ToolbarMenu.Item>
  </ToolbarMenu>
  

@graphiql/plugin-code-exporter

[!WARNING]

⚠️ UMD build is removed. Switch to the ESM CDN example.

@graphiql/plugin-explorer

[!WARNING]

⚠️ UMD build is removed. Switch to the ESM CDN example.

@graphiql/plugin-doc-explorer

• useExplorerContext hook is deprecated. Use new useDocExplorer and useDocExplorerActions hooks instead.
• The shortcut to focus on the Doc Explorer search input is now Cmd/Ctrl+Alt+K instead of the previous Cmd/Ctrl+K. This was changed because monaco-editor has a built-in Cmd/Ctrl+K command.
• push a field type on stack too before field
• fix: show spinner in doc explorer based on isIntrospecting value, and not based on isFetching

@graphiql/plugin-history

• useHistoryContext hook is deprecated. Use new useHistory and useHistoryActions hooks instead.