diff --git a/.prettierignore b/.prettierignore index ebb39d2d73..b7bff94af8 100644 --- a/.prettierignore +++ b/.prettierignore @@ -4,5 +4,6 @@ pnpm-lock.yaml !src/pages/blog/2024-04-11-announcing-new-graphql-website/index.mdx !src/pages/blog/2024-08-15-graphql-local-initiative.mdx !src/pages/community/foundation/community-grant.mdx -!src/pages/blog/2025-06-01-graphiql-4/index.mdx +!src/pages/blog/2025-05-31-graphiql-4/index.mdx +!src/pages/blog/2025-06-10-graphiql-5/index.mdx *.jpg diff --git a/src/pages/blog/2025-06-10-graphiql-5/custom-rules-example.png b/src/pages/blog/2025-06-10-graphiql-5/custom-rules-example.png new file mode 100644 index 0000000000..509773222e Binary files /dev/null and b/src/pages/blog/2025-06-10-graphiql-5/custom-rules-example.png differ diff --git a/src/pages/blog/2025-06-10-graphiql-5/graphiql-5.png b/src/pages/blog/2025-06-10-graphiql-5/graphiql-5.png new file mode 100644 index 0000000000..67568e053d Binary files /dev/null and b/src/pages/blog/2025-06-10-graphiql-5/graphiql-5.png differ diff --git a/src/pages/blog/2025-06-10-graphiql-5/index.mdx b/src/pages/blog/2025-06-10-graphiql-5/index.mdx new file mode 100644 index 0000000000..1953ba3261 --- /dev/null +++ b/src/pages/blog/2025-06-10-graphiql-5/index.mdx @@ -0,0 +1,233 @@ +--- +title: The New GraphiQL 5 is Released; Press F1! +tags: [announcements, grants] +date: 2025-06-10 +byline: Dimitri Postolov +--- + +import { Callout } from "nextra/components" + +
+ <>![GraphiQL 5 with Monaco Editor Preview](./graphiql-5.png) + {/* prettier-ignore */} +
GraphiQL 5 with Monaco Editor Preview
+
+ +This post marks the completion of **8 weeks** of work on my GraphiQL grant, +sponsored by the **GraphQL Foundation**. + +I'm thrilled to announce the release of the all-new **GraphiQL 5**, powered by +the latest version of the [Monaco editor][monaco-editor]! 🎉 + +I also added support for comments in the **Variables** and **Headers** editors. +This release is a major step forward. + +> [The original issue for integrating the Monaco editor](https://github.com/graphql/graphiql/issues/2326) +> was opened over **3 years ago**.
And the +> [issue requesting comments support in the Variables editor](https://github.com/graphql/graphiql/issues/780) +> was opened over **6 years ago**! + +As a primary maintainer of the GraphiQL IDE, I previously led the releases of +GraphiQL 3 and [GraphiQL 4](/blog/2025-05-31-graphiql-4). This new version marks +another exciting milestone in the evolution of the project. + +## What's New + +### Monaco Editor Migration + +GraphiQL 5 now uses [Monaco editor][monaco-editor] as default editor, the same +editor used in [VSCode](https://code.visualstudio.com). + +Monaco editor runs heavy language features (like syntax analysis, linting, and +IntelliSense) in +[Web Workers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers), +keeping the UI smooth and responsive. + +You can now delight your users with identical behavior to Visual Studio Code, +meaning intelligent autocompletion, hover tooltips, go to definition, find +references. I've also added +[`monaco-graphql`](https://github.com/graphql/graphiql/tree/main/packages/monaco-graphql) +integration in **Query** and **Variables** editor. + + + Clicking on a reference in the Query editor now works by holding `Cmd` on + macOS or `Ctrl` on Windows/Linux. + + +### Support for Comments in Variables and Headers Editors + +Thanks to the migration to Monaco Editor, another long-awaited feature has been +implemented. The **Variables** and **Headers** editors now support comments and +use the **JSONC** language internally. + +In the **Variables** and **Headers** payloads, all comments are automatically +stripped before the request is executed — the content in the editors **remains +unchanged**. + +### UMD Builds Are Removed + +Previously in GraphiQL 4 UMD builds were marked as deprecated, in GraphiQL 5 +they were removed completely. + +We suggest using ESM-based CDNs like [esm.sh][esm.sh] to import GraphiQL in your +projects. + +I updated [GraphiQL CDN example][graphiql-cdn] to show how to use GraphiQL with +[esm.sh][esm.sh] including how to import and setup workers. + +### Examples Update + +**GraphiQL with Parcel** and **GraphiQL with Create React App** examples were +removed. + +In addition to updated [GraphiQL CDN example][graphiql-cdn], I've added 2 new +examples +[GraphiQL with Vite](https://github.com/graphql/graphiql/tree/main/examples/graphiql-vite) +and +[GraphiQL with Next.js and App Router](https://github.com/graphql/graphiql/tree/main/examples/graphiql-nextjs). + +### Customizable Default Plugins + +GraphiQL 5 lets you take full control over the UI by allowing complete +customization of its 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: + +```jsx +import { GraphiQL } from "graphiql" + +const myPlugins = [] + +function App() { + return ( + + ) +} +``` + + + 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: + +```jsx +import { GraphiQL, HISTORY_PLUGIN } from "graphiql" +import { explorerPlugin } from "@graphiql/plugin-explorer" + +const myPlugins = [HISTORY_PLUGIN, explorerPlugin()] + +function App() { + return +} +``` + +### Removed Props + +- `readOnly` +- `keyMap` - to use Vim or Emacs keybindings in Monaco, you can use community + plugins such as [Monaco Vim](https://github.com/brijeshb42/monaco-vim) or + [Monaco Emacs](https://github.com/aioutecism/monaco-emacs) +- `validationRules` - use custom GraphQL worker, see + [Monaco GraphQL docs](https://github.com/graphql/graphiql/tree/main/packages/monaco-graphql#custom-webworker-for-passing-non-static-config-to-worker) + +
+ {/* prettier-ignore */} + <>![Example of custom GraphQL validation rules](./custom-rules-example.png) + {/* prettier-ignore */} +
Example of custom GraphQL validation rules
+
+ +### Additional Changes + +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. + +## How to Update + +Update `graphiql` using your favorite package manager: + +```sh npm2yarn +npm i graphiql@latest +``` + +### Setup Monaco Workers + +You need to set up Monaco workers in your project: + +- For **Vite** projects you must import: + + ```js + import "graphiql/setup-workers/vite" + ``` + + + See [Vite + example](https://github.com/graphql/graphiql/blob/main/examples/graphiql-vite/src/App.jsx). + + +- For Webpack projects such as **Next.js** you must import: + + ```js + import "graphiql/setup-workers/webpack" + ``` + + + See [Next.js + example](https://github.com/graphql/graphiql/blob/main/examples/graphiql-nextjs/src/app/page.tsx). + + +- For ESM-based CDN usages, you must use + [`?worker` query](https://esm.sh/#web-worker) to load the module as a web + worker: + + ```js /?worker/ + 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() + } + } + ``` + + + See [CDN + example](https://github.com/graphql/graphiql/blob/main/examples/graphiql-cdn/index.html). + + +## Stay Connected + +Follow me, **Dima Machina**, on [𝕏](https://x.com/dimaMachina_) and +[GitHub](https://github.com/dimaMachina) to stay up to date with the latest +updates! + + + I am available for consulting and open to new and exciting challenges. Please + feel free to get in touch. + + +[monaco-editor]: https://github.com/microsoft/monaco-editor +[graphiql-cdn]: + https://github.com/graphql/graphiql/blob/main/examples/graphiql-cdn/index.html +[esm.sh]: https://esm.sh