diff --git a/docs/migration/graphiql-6.0.0.md b/docs/migration/graphiql-6.0.0.md index 166b83d802c..6997bb2acad 100644 --- a/docs/migration/graphiql-6.0.0.md +++ b/docs/migration/graphiql-6.0.0.md @@ -177,7 +177,7 @@ import { useDocExplorerActions, } from '@graphiql/plugin-doc-explorer'; -const explorerNavStack = useDocExplorer(state => state.navStack); +const explorerNavStack = useDocExplorer(); const { push, pop } = useDocExplorerActions(); ``` @@ -190,7 +190,7 @@ const { items, addToHistory } = useHistoryContext(); ```tsx import { useHistory, useHistoryActions } from '@graphiql/plugin-history'; -const items = useHistory(state => state.items); +const items = useHistory(); const { addToHistory } = useHistoryActions(); ``` @@ -616,6 +616,7 @@ Nothing below is happening in v6. These are informal signals about where the pro ## Other notes -- **Browserslist.** v6 drops the project's custom `.browserslistrc` in favor of the single `defaults` browserslist preset (`> 0.5%, last 2 versions, Firefox ESR, not dead`). That range covers the modern browsers that support the OKLCH color functions the new token system relies on. If your previous bespoke config deliberately targeted very old browsers, they may fall outside the new range — check `defaults` against your support matrix if that matters to you. +- **Browserslist.** v6 replaces the project's custom `.browserslistrc` contents with the single `defaults` browserslist preset (`> 0.5%, last 2 versions, Firefox ESR, not dead`). That range covers the modern browsers that support the OKLCH color functions the new token system relies on. If your previous bespoke config deliberately targeted very old browsers, they may fall outside the new range — check `defaults` against your support matrix if that matters to you. - **Monaco editor theme registration.** The built-in Monaco themes (`graphiql-DARK` and `graphiql-LIGHT`) were rewritten to use the v6 accent palette — every GraphQL token type (keywords, type names, field identifiers, variables, annotations, strings, numbers, comments) and the surrounding editor chrome (suggest widget, hover widget, quick input) now pull from the same tokens as the rest of the UI. The `editorTheme` prop on `` still takes the same `{ dark, light }` pair of Monaco theme names or definitions it always did, so a custom theme registered through that prop should continue to work unchanged. If you were depending on the specific color values baked into the previous built-in `graphiql-DARK` / `graphiql-LIGHT` themes (for a screenshot test, for example), expect those values to have shifted. - **`cn` removed from `@graphiql/react`.** The `cn` helper was just a re-export of `clsx`. It's gone now, so import `clsx` directly from the `clsx` package instead. +- **`ExecuteButton` removed from `@graphiql/react`.** The Run button and its execution logic moved into the top bar; there's no longer a standalone `ExecuteButton` export to compose into a custom toolbar. diff --git a/packages/graphiql-react/README.md b/packages/graphiql-react/README.md index 0b18a47a456..069e175efb2 100644 --- a/packages/graphiql-react/README.md +++ b/packages/graphiql-react/README.md @@ -22,9 +22,13 @@ All the state for your GraphQL IDE lives in multiple contexts. The easiest way to get started is by using the `GraphiQLProvider` component that renders all the individual providers. -There is one required prop called `transport`. This is a function that performs -GraphQL requests against a given endpoint. You can easily create a transport using -the method `createTransport` from the `@graphiql/toolkit` package. +`GraphiQLProvider` needs either a `transport` or a `fetcher` prop (the two are +mutually exclusive) to know how to run GraphQL requests against a given +endpoint. A `transport` is an object with a `send(request)` method; you can +easily create one using the `createTransport` function from the +`@graphiql/toolkit` package. `fetcher` is the older, deprecated-but-still-supported +alternative: a plain function that returns an execution result directly, with +no access to the underlying HTTP response. ```jsx import { GraphiQLProvider } from '@graphiql/react'; diff --git a/packages/graphiql-toolkit/README.md b/packages/graphiql-toolkit/README.md index 8446b1d8890..5faa474b93f 100644 --- a/packages/graphiql-toolkit/README.md +++ b/packages/graphiql-toolkit/README.md @@ -12,7 +12,11 @@ that are useful when working with these packages. ## Docs +- **[`createTransport`](./src/create-transport/README.md)** : a utility for + creating a `transport` prop implementation, GraphiQL's wire-level primitive + for running operations and reading back real HTTP status, headers, and + timing - **[`createFetcher`](./docs/create-fetcher.md)** : a utility for creating a `fetcher` prop implementation for HTTP GET, POST including multipart, - websockets fetcher + websockets fetcher (deprecated in favor of `createTransport`) - more to come! diff --git a/packages/graphiql-toolkit/docs/create-fetcher.md b/packages/graphiql-toolkit/docs/create-fetcher.md index 733698183e6..bc86d3db536 100644 --- a/packages/graphiql-toolkit/docs/create-fetcher.md +++ b/packages/graphiql-toolkit/docs/create-fetcher.md @@ -1,6 +1,6 @@ > [!WARNING] -> `createGraphiQLFetcher` is deprecated. Use [`createTransport`](./create-transport.md) instead. -> See the [GraphiQL 6 migration guide](../../docs/migration/graphiql-6.0.0.md) for upgrade instructions. +> `createGraphiQLFetcher` is deprecated. Use [`createTransport`](../src/create-transport/README.md) instead. +> See the [GraphiQL 6 migration guide](../../../docs/migration/graphiql-6.0.0.md) for upgrade instructions. # `createGraphiQLFetcher` diff --git a/packages/graphiql/README.md b/packages/graphiql/README.md index 82efa6b9889..4dc3a5c42a2 100644 --- a/packages/graphiql/README.md +++ b/packages/graphiql/README.md @@ -57,6 +57,7 @@ _/ˈɡrafək(ə)l/_ A graphical interactive in-browser GraphQL IDE. - [Migration guide to GraphiQL 2](../../docs/migration/graphiql-2.0.0.md) - [Migration guide to GraphiQL 4](../../docs/migration/graphiql-4.0.0.md) - [Migration guide to GraphiQL 5](../../docs/migration/graphiql-5.0.0.md) +- [Migration guide to GraphiQL 6](../../docs/migration/graphiql-6.0.0.md) ### CDN usage @@ -91,16 +92,23 @@ The package exports a bunch of React components: - The `GraphiQLInterface` component renders the UI that makes up GraphiQL - The `GraphiQL` component is a combination of both the above components -There is a single prop that is required for the `GraphiQL` component called -`transport`. A transport is a function that performs a request to a GraphQL API. -It may return a `Promise` for queries or mutations, but also an `Observable` or -an `AsyncIterable` in order to handle subscriptions or multipart responses. +The `GraphiQL` component needs to know how to run operations against a GraphQL +API, which it gets from either a `transport` or a `fetcher` prop (the two are +mutually exclusive). A `transport` is an object with a `send(request)` method +that performs the request. `send` may return a `Promise` for queries or +mutations, or an `AsyncIterable` for subscriptions and multipart responses. -An easy way to create such a function is the -[`createTransport`](../graphiql-toolkit/src/create-fetcher/createFetcher.ts) -method exported from the `@graphiql/toolkit` package. If you want to implement -your own transport function, you can use the `Transport` type from -`@graphiql/toolkit` to make sure the signature matches what GraphiQL expects. +An easy way to create one is the +[`createTransport`](../graphiql-toolkit/src/create-transport/createTransport.ts) +function exported from the `@graphiql/toolkit` package. If you want to +implement your own transport, you can use the `Transport` type from +`@graphiql/toolkit` to make sure the shape matches what GraphiQL expects. + +`fetcher` is still supported — it's deprecated but not removed, and predates +`transport`. Unlike a `transport`, a `fetcher` is a plain function that returns +an execution result directly, with no access to the underlying HTTP response. +See the [v6 migration guide](../../docs/migration/graphiql-6.0.0.md#new-transport-prop) +if you're moving from `fetcher` to `transport`. The following is everything you need to render GraphiQL in your React application: @@ -184,28 +192,34 @@ be considered stable and might change between minor or patch version updates. ### Editor Theme -The colors inside the editor can also be altered using -[CodeMirror editor themes](https://codemirror.net/demo/theme.html). You can use -the `editorTheme` prop to pass in the name of the theme. The CSS for the theme -has to be loaded for the theme prop to work. +The query, variables, headers, and response editors are built on +[Monaco](https://microsoft.github.io/monaco-editor/), so editor theming goes +through Monaco's theme system, not CSS. The `editorTheme` prop takes a +`{ dark, light }` pair of Monaco theme names, one for each GraphiQL theme: ```jsx -// In your document head: - + ``` +`graphiql-DARK` and `graphiql-LIGHT` are the built-in themes and also the +default value, so you only need to pass `editorTheme` if you want something +else. To use your own colors, register a theme with Monaco's `editor.defineTheme` +API before rendering `GraphiQL`, then reference it by name: + ```jsx +import * as monaco from 'monaco-editor'; + +monaco.editor.defineTheme('my-dark-theme', { + base: 'vs-dark', + inherit: true, + rules: [], + colors: {}, +}); + // When rendering GraphiQL: - +; ``` -You can also create your own theme in CSS. As a reference, the default -`graphiql` theme definition can be found -[here](../graphiql-react/src/style/codemirror.css). - ## Usage with a Custom Storage Namespace When multiple GraphiQL instances run on the same origin—such as in different apps or