|
1 | | -# Upgrading `graphiql` from `4.x` to `5.0.0-rc` |
| 1 | +# Upgrading `graphiql` from `4.x` to `5.0.0` |
| 2 | + |
| 3 | +Starting from GraphiQL 5, you need to set up Monaco workers in your project: |
| 4 | + |
| 5 | +- For **Vite** projects you must import: |
| 6 | + |
| 7 | + ```js |
| 8 | + import 'graphiql/setup-workers/vite'; |
| 9 | + ``` |
| 10 | + |
| 11 | +> [!NOTE] |
| 12 | +> |
| 13 | +> See [Vite example](../../examples/graphiql-vite/src/App.jsx). |
| 14 | +
|
| 15 | +- For Webpack projects such as **Next.js** you must import: |
| 16 | + |
| 17 | + ```js |
| 18 | + import 'graphiql/setup-workers/webpack'; |
| 19 | + ``` |
| 20 | + |
| 21 | +> [!NOTE] |
| 22 | +> |
| 23 | +> See [Next.js example](../../examples/graphiql-nextjs/src/app/page.tsx). |
| 24 | +
|
| 25 | +- For ESM-based CDN usages, you must use |
| 26 | + [`?worker` query](https://esm.sh/#web-worker) to load the module as a web |
| 27 | + worker: |
| 28 | + |
| 29 | + ```js |
| 30 | + import createJSONWorker from 'https://esm.sh/monaco-editor/esm/vs/language/json/json.worker.js?worker'; |
| 31 | + import createGraphQLWorker from 'https://esm.sh/monaco-graphql/esm/graphql.worker.js?worker'; |
| 32 | + import createEditorWorker from 'https://esm.sh/monaco-editor/esm/vs/editor/editor.worker.js?worker'; |
| 33 | + |
| 34 | + globalThis.MonacoEnvironment = { |
| 35 | + getWorker(_workerId, label) { |
| 36 | + switch (label) { |
| 37 | + case 'json': |
| 38 | + return createJSONWorker(); |
| 39 | + case 'graphql': |
| 40 | + return createGraphQLWorker(); |
| 41 | + } |
| 42 | + return createEditorWorker(); |
| 43 | + }, |
| 44 | + }; |
| 45 | + ``` |
| 46 | + |
| 47 | +> [!NOTE] |
| 48 | +> |
| 49 | +> See [CDN example](../../examples/graphiql-cdn/index.html). |
| 50 | +
|
| 51 | +## Allow to Override All Default GraphiQL Plugins |
| 52 | + |
| 53 | +Starting from GraphiQL 5, you can override all default plugins. |
| 54 | + |
| 55 | +### Removing All Default Plugins |
| 56 | + |
| 57 | +To remove all default plugins (currently **Doc Explorer** and **History**), set |
| 58 | +`referencePlugin={null}` and pass an empty array to the `plugins` prop: |
| 59 | + |
| 60 | +```jsx |
| 61 | +import { GraphiQL } from 'graphiql'; |
| 62 | + |
| 63 | +const myPlugins = []; |
| 64 | + |
| 65 | +function App() { |
| 66 | + return ( |
| 67 | + <GraphiQL |
| 68 | + referencePlugin={null} // Removes Doc Explorer plugin |
| 69 | + plugins={myPlugins} // Removes History plugin |
| 70 | + /> |
| 71 | + ); |
| 72 | +} |
| 73 | +``` |
| 74 | + |
| 75 | +> [!NOTE] |
| 76 | +> |
| 77 | +> If you're using a custom Doc Explorer, pass it to the `referencePlugin` prop — |
| 78 | +> **not** the `plugins` array. It will be automatically included and always |
| 79 | +> rendered first. |
| 80 | +
|
| 81 | +### Adding Plugins While Keeping Defaults |
| 82 | + |
| 83 | +If you're adding custom plugins (e.g., the **Explorer** plugin) and want to keep |
| 84 | +the **History** plugin, you must explicitly include it in the `plugins` array: |
| 85 | + |
| 86 | +```jsx |
| 87 | +import { GraphiQL, HISTORY_PLUGIN } from 'graphiql'; |
| 88 | +import { explorerPlugin } from '@graphiql/plugin-explorer'; |
| 89 | + |
| 90 | +const myPlugins = [HISTORY_PLUGIN, explorerPlugin()]; |
| 91 | + |
| 92 | +function App() { |
| 93 | + return <GraphiQL plugins={myPlugins} />; |
| 94 | +} |
| 95 | +``` |
2 | 96 |
|
3 | 97 | --- |
4 | 98 |
|
5 | 99 | ## `graphiql` |
6 | 100 |
|
7 | | -- Migration from Codemirror to |
8 | | - [Monaco Editor](https://github.com/microsoft/monaco-editor) |
9 | | - - Replacing `codemirror-graphql` with |
10 | | - [`monaco-graphql`](https://github.com/graphql/graphiql/tree/main/packages/monaco-graphql) |
| 101 | +> [!WARNING] |
| 102 | +> |
| 103 | +> ⚠️ UMD build is removed. Switch to the [ESM CDN example](../../examples/graphiql-cdn/index.html). |
| 104 | +
|
| 105 | +- Migration from Codemirror to [Monaco Editor](https://github.com/microsoft/monaco-editor) |
| 106 | + - Replacing `codemirror-graphql` with [`monaco-graphql`](../../packages/monaco-graphql) |
11 | 107 | - Clicking on a reference in the query editor now works by holding `Cmd` on macOS or `Ctrl` on Windows/Linux |
12 | 108 | - Support for comments in **Variables** and **Headers** editors |
13 | | -- Added new examples: [**GraphiQL x Vite**](https://github.com/graphql/graphiql/tree/graphiql-5/examples/graphiql-vite) and [**GraphiQL x |
14 | | - Next.js**](https://github.com/graphql/graphiql/tree/graphiql-5/examples/graphiql-nextjs) |
| 109 | +- Added new examples: [**GraphiQL x Vite**](../../examples/graphiql-vite) and [**GraphiQL x Next.js**](../../examples/graphiql-nextjs) |
15 | 110 | - Removed examples: **GraphiQL x Parcel** and **GraphiQL x Create React App** |
| 111 | +- Removed props |
| 112 | + - `query` |
| 113 | + - `variables` |
| 114 | + - `headers` |
| 115 | + - `response` |
| 116 | + - `readOnly` |
| 117 | + - `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 |
| 118 | + - `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.' |
| 119 | + |
| 120 | +> [!NOTE] |
| 121 | +> |
| 122 | +> If you used `query`, `variables` and `headers` in integration tests, you can use the new `initialQuery`, |
| 123 | +> `initialVariables` and `initialHeaders` props instead. These props will only be used for the first tab. |
| 124 | +> When opening more tabs, the query editor will start out empty. |
| 125 | +
|
| 126 | +- Added new props |
| 127 | + - `initialQuery` |
| 128 | + - `initialVariables` |
| 129 | + - `initialHeaders` |
| 130 | +- feat: allow `children: ReactNode` for `<GraphiQL.Toolbar />` component |
| 131 | + |
| 132 | +--- |
| 133 | + |
| 134 | +## `@graphiql/react` |
| 135 | + |
| 136 | +> [!IMPORTANT] |
| 137 | +> |
| 138 | +> Clicking on a reference in the Query editor now works by holding `Cmd` on macOS or `Ctrl` on Windows/Linux. |
| 139 | +
|
| 140 | +- `usePrettifyEditors`, `useCopyQuery`, `useMergeQuery`, `useExecutionContext`, `usePluginContext`, `useSchemaContext`, `useStorageContext` hooks are deprecated. |
| 141 | +- Add new `useGraphiQL` and `useGraphiQLActions` hooks instead. See updated [README](../../packages/graphiql-react/README.md#available-stores) for more details about them. |
| 142 | +- remove `useSynchronizeValue` hook |
| 143 | +- fix `defaultQuery` with empty string does not result in an empty default query |
| 144 | +- fix `defaultQuery`, when is set will only be used for the first tab. When opening more tabs, the query editor will start out empty |
| 145 | +- fix execute query shortcut in query editor, run it even there are no operations in query editor |
| 146 | +- fix plugin store, save last opened plugin in storage |
| 147 | +- remove `onClickReference` from variable editor |
| 148 | +- fix shortcut text per OS for default query and in run query in execute query button's tooltip |
| 149 | + |
| 150 | +The `ToolbarMenu` component has changed. |
| 151 | + |
| 152 | +- The `label` and `className` props were removed |
| 153 | +- The `button` prop should now be a button element |
| 154 | + |
| 155 | + ```jsx |
| 156 | + <ToolbarMenu |
| 157 | + label="Options" |
| 158 | + button={ |
| 159 | + <ToolbarButton label="Options"> |
| 160 | + <SettingsIcon className="graphiql-toolbar-icon" aria-hidden="true" /> |
| 161 | + </ToolbarButton> |
| 162 | + } |
| 163 | + > |
| 164 | + <ToolbarMenu.Item onSelect={() => console.log('Clicked!')}> |
| 165 | + Test |
| 166 | + </ToolbarMenu.Item> |
| 167 | + </ToolbarMenu> |
| 168 | + ``` |
| 169 | + |
| 170 | +## `@graphiql/plugin-code-exporter` |
| 171 | + |
| 172 | +> [!WARNING] |
| 173 | +> |
| 174 | +> ⚠️ UMD build is removed. Switch to the [ESM CDN example](../../packages/graphiql-plugin-code-exporter/example/index.html). |
| 175 | +
|
| 176 | +--- |
| 177 | + |
| 178 | +## `@graphiql/plugin-explorer` |
| 179 | + |
| 180 | +> [!WARNING] |
| 181 | +> |
| 182 | +> ⚠️ UMD build is removed. Switch to the [ESM CDN example](../../examples/graphiql-cdn/index.html). |
| 183 | +
|
| 184 | +--- |
| 185 | + |
| 186 | +## @graphiql/plugin-doc-explorer |
| 187 | + |
| 188 | +- `useExplorerContext` hook is deprecated. Use new `useDocExplorer` and `useDocExplorerActions` hooks instead. |
| 189 | +- The shortcut to focus on the Doc Explorer search input is now `Cmd/Ctrl+Alt+K` |
| 190 | + instead of the previous `Cmd/Ctrl+K`. This was changed because monaco-editor has |
| 191 | + a built-in `Cmd/Ctrl+K` command. |
| 192 | +- push a field type on stack too before field |
| 193 | +- fix: show spinner in doc explorer based on `isIntrospecting` value, and not based on `isFetching` |
| 194 | + |
| 195 | +--- |
| 196 | + |
| 197 | +## @graphiql/plugin-history |
| 198 | + |
| 199 | +- `useHistoryContext` hook is deprecated. Use new `useHistory` and `useHistoryActions` hooks instead. |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4&size=40){kind=avatar}
0 commit comments