Skip to content

Commit 1ebd26e

Browse files
dimaMachinadimaMachina
authored
graphiql 5: improve migration guide (#4029)
* improve migration guide * upd * upd * upd * upd * upd * prettier * upd * upd * upd * upd * upd * upd * prettier
1 parent b630949 commit 1ebd26e

File tree

2 files changed

+167
-10
lines changed

2 files changed

+167
-10
lines changed

‎docs/migration/graphiql-5.0.0.md‎

Lines changed: 166 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,152 @@
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+
```
296

397
---
498

599
## `graphiql`
6100

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)
11107
- Clicking on a reference in the query editor now works by holding `Cmd` on macOS or `Ctrl` on Windows/Linux
12108
- 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)
15110
- Removed examples: **GraphiQL x Parcel** and **GraphiQL x Create React App**
16-
- UMD build is removed. Use the ESM-based CDN instead.
17111
- Removed props
18-
- `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
112+
- `query`
113+
- `variables`
114+
- `headers`
115+
- `response`
19116
- `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
20118
- `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.'
21119

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+
22134
## `@graphiql/react`
23135

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+
24150
The `ToolbarMenu` component has changed.
25151

26152
- The `label` and `className` props were removed
@@ -40,3 +166,34 @@ The `ToolbarMenu` component has changed.
40166
</ToolbarMenu.Item>
41167
</ToolbarMenu>
42168
```
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.

‎packages/graphiql/src/ui/short-keys.tsx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,8 @@ import { FC, Fragment } from 'react';
22
import { formatShortcutForOS, KEY_MAP } from '@graphiql/react';
33

44
const SHORT_KEYS = Object.entries({
5-
'Open the Command Palette (you must have focus in the editor)': 'F1',
65
'Execute query': formatShortcutForOS(KEY_MAP.runQuery.key),
6+
'Open the Command Palette (you must have focus in the editor)': 'F1',
77
'Prettify editors': KEY_MAP.prettify.key,
88
'Copy query': KEY_MAP.copyQuery.key,
99
'Re-fetch schema using introspection': KEY_MAP.refetchSchema.key,

0 commit comments

Comments
 (0)