diff --git a/README.md b/README.md index f67c70e96ce..292be84ff42 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ # GraphQL IDE Monorepo -> **Security Notice:** All versions of `graphiql` < `1.4.7` are vulnerable to an XSS attack in cases where the GraphQL server to which the GraphiQL web app connects is not trusted. Learn more [in the graphiql `security` docs directory](https://github.com/graphql/graphiql/blob/main/docs/security) +> **Security Notice:** All versions of `graphiql` < `1.4.7` are vulnerable to an XSS attack in cases where the GraphQL server to which the GraphiQL web app connects is not trusted. Learn more [in the graphiql `security` docs directory](docs/security) > **Looking for the [GraphiQL Docs?](packages/graphiql/README.md)**: This is the root of the monorepo! The full GraphiQL docs are located at [`packages/graphiql`](packages/graphiql) @@ -31,22 +31,8 @@ The purpose of this monorepo is to give the GraphQL Community: - an example of how to use this ecosystem with GraphiQL. - examples of how to implement or extend GraphiQL. -### Latest Stable Ecosystem - -`graphiql@1.0.x` and ecosystem are organized as below. Any further changes to `graphiql@1.0.x` are made against `1.0.0` branch - -![Diagram of the current Monorepo and third party ecosystem](https://raw.githubusercontent.com/graphql/graphiql/main/resources/images/current-ecosystem.jpg) - -### Proposed Ecosystem - -As we re-write for `graphiql@2.x` ecosystem, this monorepo will contain a sdk and plugins. - -![Diagram of the proposed Monorepo and third party ecosystem](https://raw.githubusercontent.com/graphql/graphiql/main/resources/images/proposed-ecosystem.jpg) - ## [`graphiql`](packages/graphiql#readme) -> **Breaking Changes & Improvements:** several interfaces are being dropped for new ones are arriving for GraphiQL 1.0.0! Read more in [this issue](https://github.com/graphql/graphiql/issues/1165) - > [![NPM](https://img.shields.io/npm/v/graphiql.svg)](https://npmjs.com/graphiql) > ![jsDelivr hits (npm)](https://img.shields.io/jsdelivr/npm/hm/graphiql) @@ -55,7 +41,7 @@ As we re-write for `graphiql@2.x` ecosystem, this monorepo will contain a sdk an > ![npm bundle size (version)](https://img.shields.io/bundlephobia/min/graphiql/latest) > ![npm bundle size (version)](https://img.shields.io/bundlephobia/minzip/graphiql/latest) -![Screenshot of GraphiQL with Doc Explorer Open](https://raw.githubusercontent.com/graphql/graphiql/main/packages/graphiql/resources/graphiql.jpg) +![Screenshot of GraphiQL with Doc Explorer Open](packages/graphiql/resources/graphiql.jpg) _/ˈɡrafək(ə)l/_ A graphical interactive in-browser GraphQL IDE. [Try the live demo](http://graphql.org/swapi-graphql). We also have [a demo using our latest netlify build](http://graphiql-test.netlify.com) for the `main` branch. @@ -63,13 +49,6 @@ The GraphiQL IDE, implemented in React, currently using [GraphQL mode for CodeMi **Learn more about [GraphiQL in `packages/graphiql/README.md`](packages/graphiql#readme)** -### How To Setup/Implement GraphiQL - -[codesandbox.io graphiql example](https://codesandbox.io/s/graphiql-js-example-oc851) -[stackblitz.com graphiql example](https://stackblitz.com/edit/react-ts-jpnmod) - -**The [GraphiQL Readme](packages/graphiql#readme) explains** some of the ways to implement GraphiQL, and we also have the [examples](examples) directory as well! - ## [`monaco-graphql`](packages/monaco-graphql#readme) [![NPM](https://img.shields.io/npm/v/monaco-graphql.svg)](https://npmjs.com/monaco-graphql) diff --git a/docs/migration/graphiql-2.0.0.md b/docs/migration/graphiql-2.0.0.md new file mode 100644 index 00000000000..f70daaaeba6 --- /dev/null +++ b/docs/migration/graphiql-2.0.0.md @@ -0,0 +1,186 @@ +# Upgrading `graphiql` from `1.x` to `2.0.0` + +Hello GraphiQL user and thanks for upgrading! + +This migration guide walks you through all changes that come with `graphiql@2.0.0`, in particular the breaking ones, and will show you how to upgrade your `1.x` implementation. + +> If you encounter any issues while upgrading that are not covered in here, please open an issue or PR on this repo and we will extend this guide. + +## Design refresh including dark theme + +Arguably the biggest change in `graphiql@2` is the new design of the UI. It has been reworked from scratch to look more modern while keeping its simplistic look and feel. We also finally added a built-in dark theme. Theme selection is based on system defaults and can be changed in the new settings dialog (available by clicking on the gear icon at the bottom of the sidebar on the left of the screen). + +Starting with `graphiql@2`, the only officially supported way of customizing the CSS that make up the looks of GraphiQL is by overriding the design tokens defined using CSS variables. In particular, changes to class names are no longer considered breaking changes. If you use class-name based selectors to change styles your overrides might break with minor or patch version bumps. + +A list of all CSS variables that can be customized can be found in the [`root.css`](../../packages/graphiql-react/src/style/root.css) file of the `@graphiql/react` package. The variables for colors use a list of values that can be passed into the [`hsl`](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/hsl) function in CSS that defines colors by hue, saturation and lightness. + +## Changes to `GraphiQL` component props + +A couple of props of the `GraphiQL` have undergone breaking changes: + +- The props `defaultVariableEditorOpen` and `defaultSecondaryEditorOpen` have been merged into one prop `defaultEditorToolsVisibility`. The default behavior if this prop is not passed is that the editor tools are shown if at least one of the secondary editors has contents. You can pass the following values to the prop: + - Passing `false` hides the editor tools. + - Passing `true` shows the editor tools. + - Passing `"variables"` explicitly shows the variables editor. + - Passing `"headers"` explicitly shows the headers editor. +- The props `docExplorerOpen`, `onToggleDocs` and `onToggleHistory` have been removed. They are replaced by the more generic props `visiblePlugin` (for controlling which plugin is visible) and `onTogglePluginVisibility` (which is called each time the visibility of any plugin changes). +- The `headerEditorEnabled` prop has been renamed to `isHeadersEditorEnabled`. +- The `ResultsTooltip` prop has been renamed to `responseTooltip`. + +### Tabs enabled by default + +Tabs were supported opt-in starting with `@graphiql@1.8`. With `graphiql@2` tabs are now always enabled. The `tabs` prop (which previously toggled if tabs were enabled or not) has therefore been replaced with a prop `onTabChange`. If you used the `tabs` prop before to pass this function you can change your implementation like so: + +```diff + {/* do something */} }} ++ onTabChange={(tabState) => {/* do something */}} +/> +``` + +As long as only one session is open, the tab bar above the editors is hidden. A plus icon next to the logo on the top right allows the user to open more tabs. With at least two tabs opened, the tab bar appears above the editors. + +## Removed package exports + +All React components apart from the `GraphiQL` component have been moved to the `@graphiql/react` package. That's why we removed most of the exports with `graphiql@2`. Here is a list of all exported components and functions that have been removed and where you can find them now: + +- `QueryEditor`, `VariableEditor` and `DocExplorer`: Now exported from `@graphiql/react` under the same names + - Note that the `schema` prop of the `DocExplorer` no longer exists, the component now uses the schema provided by the `ExplorerContext`. +- `ToolbarMenu`: Now exported from `@graphiql/react` as `ToolbarMenu` +- `ToolbarMenuItem`: Now exported from `@graphiql/react` as `ToolbarMenu.Item` +- `ToolbarSelect`: Now exported from `@graphiql/react` as `ToolbarListbox` +- `ToolbarSelectOption`: Now exported from `@graphiql/react` as `ToolbarListbox.Option` +- `onHasCompletion`: This function is only meant to be used internally, it is no longer being exported +- `fillLeafs`, `getSelectedOperationName` and `mergeAst`: Now exported from `@graphiql/toolkit` under the same names +- types `Fetcher`, `FetcherOpts`, `FetcherParams`, `FetcherResult`, `FetcherReturnType`, `Observable`, `Storage` and `SyncFetcherResult`: Exported from `@graphiql/toolkit` under the same names (previously just re-exported by `graphiql`) + +## `GraphiQL` is now a function component + +The `GraphiQL` component in `graphiql@1.x` was a class component. That allowed easy access to its props, state and methods by attaching a ref to it like so: + +```jsx +import { createGraphiQLFetcher } from '@graphiql/toolkit'; +import { GraphiQL } from 'graphiql'; +import React from 'react'; + +const fetcher = createGraphiQLFetcher({ url: 'https://my.endpoint' }); + +class MyComponent extends React.Component { + _graphiql: GraphiQL; + + componentDidMount() { + const query = this._graphiql.getQueryEditor().getValue(); + } + + render() { + return (this._graphiql = r)} fetcher={fetcher} />; + } +} +``` + +With `graphiql@2` we refactored the codebase to more "modern" React. This also meant replacing all class components with function components. The code above no longer works in `graphiql@2` as attaching refs to function components is not possible in React. + +All logic and state management now lives in multiple React contexts, provided by the `@graphiql/react` package. The `GraphiQL` component is now basically combining two other components, both of which are also exported by the package. + +- `GraphiQLProvider` (originally coming from `@graphiql/react`) will render all context providers and takes care of state management +- `GraphiQLInterface` is defined in the `graphiql` package and renders the UI + +If you want to read or modify GraphiQL state from your custom implementation you need to render both the above components separately as the hooks for consuming the context values only work in components that are rendered inside the provider component. + +With all that, the example above can be refactored a such: + +```jsx +import { useEditorContext } from '@graphiql/react'; +import { createGraphiQLFetcher } from '@graphiql/toolkit'; +import { GraphiQLInterface, GraphiQLProvider } from 'graphiql'; +import { useEffect } from 'react'; + +const fetcher = createGraphiQLFetcher({ url: 'https://my.endpoint' }); + +function MyComponent() { + return ( + + + + ); +} + +function InsideContext() { + // Calling this hook would not work in `MyComponent` (it would return `null`) + const { queryEditor } = useEditorContext(); + + useEffect(() => { + const query = queryEditor.getValue(); + }, []); + + return ; +} +``` + +Here is a list of all public class methods that existed in `graphiql@1` and its replacement in `graphiql@2`. All the contexts mentioned below can be accessed using a hook exported by `@graphiql/react`. + +- `getQueryEditor`: Use the `queryEditor` property from the `EditorContext`. +- `getVariableEditor`: Use the `variableEditor` property from the `EditorContext`. +- `getHeaderEditor`: Use the `headerEditor` property from the `EditorContext`. +- `refresh`: Calling this method should no longer be necessary, all editors will refresh automatically after resizing. If you really need to refresh manually you have to call the `refresh` method on all editor instances individually. +- `autoCompleteLeafs`: Use the `useAutoCompleteLeafs` hook provided by `@graphiql/react` that returns this function. + +There are a couple more class methods that were intended to be private and were already removed starting in `graphiql@1.9.0`. Since they were not actually marked with `private`, here's an extension to the above list for these methods: + +- `handleClickReference`: This was a callback method triggered when clicking on a type or field. It would open the doc explorer for the clicked reference. If you want to manually mimic this behavior you can use the `push` method from the `ExplorerContext` to add an item to the navigation stack of the doc explorer, and you can use the `setVisiblePlugin` method of the `PluginContext` to show the doc explorer plugin (by passing the `DOC_EXPLORER_PLUGIN` object provided by `@graphiql/react`). +- `handleRunQuery`: To execute a query, use the `run` method of the `ExecutionContext`. If you want to explicitly set an operation name, call the `setOperationName` method of the `EditorContext` provider before that (passing in the operation name string as argument). +- `handleEditorRunQuery`: Use the `run` method of the `ExecutionContext`. +- `handleStopQuery`: Use the `stop` method from the `ExecutionContext`. +- `handlePrettifyQuery`: Use the `usePrettifyQuery` hook provided by `@graphiql/react` that returns this function. +- `handleMergeQuery`: Use the `useMergeQuery` hook provided by `@graphiql/react` that returns this function. +- `handleCopyQuery`: Use the `useCopyQuery` hook provided by `@graphiql/react` that returns this function. +- `handleToggleDocs` and `handleToggleHistory`: Use the `setVisiblePlugin` method of the `PluginContext`. + +Some class methods were callbacks to modify state which are not intended to be called manually. All these methods don't have a successor: `handleEditQuery`, `handleEditVariables`, `handleEditHeaders`, `handleEditOperationName`, `handleSelectHistoryQuery`, `handleResetResize` and `handleHintInformationRender` + +### Static properties have been removed + +In `graphiql@1.x` the `GraphiQL` component included a bunch of static properties that exposed utility functions and other components. Most of these have been removed in `graphiql@2` since the components and functions have been moved to the `@graphiql/react` and `@graphiql/toolkit` packages. + +The properties that remain on the `GraphiQL` function component are `GraphiQL.Logo`, `GraphiQL.Toolbar` and `GraphiQL.Footer`. All three are React components that can be passed as children to the `GraphiQL` components and override certain parts of the UI: + +- `GraphiQL.Logo`: Overrides the "logo" at the top right of the screen. By default it contains the text "Graph*i*QL". +- `GraphiQL.Toolbar`: Overrides the toolbar next to the query editor. By default if contains buttons for prettifying the current editor contents, merging fragment definitions into the operation definition and copying the contents of the query editor to the clipboard. Note that the default buttons will not be shown when passing this component as child to `GraphiQL`, instead it will show the children you pass to `GraphiQL.Toolbar`. The execute button will always be shown. If you want to keep the default buttons and add additional buttons you can use the `toolbar` prop. +- `GraphiQL.Footer`: Adds a section below the response editor. By default this won't show up in the UI. + +Here is a list of all the static properties that have been removed and their replacements: + +- `GraphiQL.formatResult` and `GraphiQL.formatError`: Replaced by equally named functions from `@graphiql/toolkit` +- `GraphiQL.QueryEditor`, `GraphiQL.VariableEditor` and `GraphiQL.HeaderEditor`: Replaced by equally named components from `@graphiql/react` +- `GraphiQL.ResultViewer`: Replaced by the `ResponseEditor` component from `@graphiql/react` +- `GraphiQL.Button`: Replaced by the `ToolbarButton` component from `@graphiql/react` +- `GraphiQL.ToolbarButton`: This exposed the same component as `GraphiQL.Button`. +- `GraphiQL.Menu`: Replaced by the `ToolbarMenu` component from `@graphiql/react` +- `GraphiQL.MenuItem`: Replaced by the `ToolbarMenu.Item` component from `@graphiql/react` +- `GraphiQL.Group`: Grouping multiple buttons side-by-side is not provided out-of-the box anymore in the new GraphiQL UI. If you want to implement a similar feature in the new vertical toolbar you can do so by adding your own styles for your custom toolbar elements. Example: + + ```jsx + import { createGraphiQLFetcher } from '@graphiql/toolkit'; + import { GraphiQL } from 'graphiql'; + + const fetcher = createGraphiQLFetcher({ url: 'https://my.endpoint' }); + + function MyComponent() { + return ( + + + {/* Add custom styles for your buttons using the given class */} +
+ + + +
+ + + ); + } + ``` + +### `window.g` has been removed + +In `graphiql@1.x` the `GraphiQL` class component stored a reference to itself on a global property named `g`. This property has been removed as refs don't exist for function components. (Also, the property was only intended for internal use like testing in the first place.) diff --git a/packages/graphiql/README.md b/packages/graphiql/README.md index e6797130e72..0ff6494aec4 100644 --- a/packages/graphiql/README.md +++ b/packages/graphiql/README.md @@ -2,10 +2,6 @@ > **Security Notice:** All versions of `graphiql` < `1.4.3` are vulnerable to an XSS attack in cases where the GraphQL server to which the GraphiQL web app connects is not trusted. Learn more in [our security advisory](https://github.com/graphql/graphiql/tree/main/docs/security/2021-introspection-schema-xss.md). -> **Breaking Changes & Improvements:** several interfaces are being dropped for new ones for GraphiQL 2.0.0! Read more in [this issue](https://github.com/graphql/graphiql/issues/1165) - -> **[`graphiql@2.0.0-beta`](https://github.com/graphql/graphiql/issues/983)** is a much larger ongoing effort that introduces plugins, i18n, and so many more features after a substantial rewrite using modern react. - [![NPM](https://img.shields.io/npm/v/graphiql.svg)](https://npmjs.com/graphiql) ![jsDelivr hits (npm)](https://img.shields.io/jsdelivr/npm/hm/graphiql) ![npm downloads](https://img.shields.io/npm/dm/graphiql?label=npm%20downloads) @@ -13,57 +9,42 @@ ![npm bundle size (version)](https://img.shields.io/bundlephobia/min/graphiql/latest) ![npm bundle size (version)](https://img.shields.io/bundlephobia/minzip/graphiql/latest) [![License](https://img.shields.io/npm/l/graphiql.svg?style=flat-square)](LICENSE) -[Discord Channel](https://discord.gg/NP5vbPeUFp) +[![](https://dcbadge.vercel.app/api/server/NP5vbPeUFp?style=flat)](https://discord.gg/NP5vbPeUFp) + _/ˈɡrafək(ə)l/_ A graphical interactive in-browser GraphQL IDE. [Try the live demo](http://graphql.org/swapi-graphql). -[![](https://raw.githubusercontent.com/graphql/graphiql/master/packages/graphiql/resources/graphiql.jpg)](http://graphql.org/swapi-graphql) +[![](resources/graphiql.png)](http://graphql.org/swapi-graphql) ## Features -- Syntax highlighting. -- Intelligent type ahead of fields, arguments, types, and more. -- Real-time error highlighting and reporting for queries and variables. -- Automatic query and variables completion. -- Automatically adds required fields to queries. -- Documentation explorer, search, with markdown support. -- Query History using local storage -- Run and inspect query results using _any_ promise that resolves JSON results. HTTPS or WSS not required. -- Supports full [GraphQL Language Specification](https://github.com/graphql/graphql-wg): - - Queries, Mutations, Subscriptions, Fragments, Unions, directives, multiple operations per query, etc +- Full language support of the latest [GraphQL Specification](https://spec.graphql.org/draft/#sec-Language): +- Syntax highlighting +- Intelligent type ahead of fields, arguments, types, and more +- Real-time error highlighting and reporting for queries and variables +- Automatic query and variables completion +- Automatic leaf node insertion for non-scalar fields +- Documentation explorer with search and markdown support +- Persisted state using `localStorage` +- Simple API for adding custom plugins ## Live Demos -We have a few demos of `master` branch via the default netlify build (the same URL paths apply to deploy previews on PRs): - -1. [`graphiql.min.js` demo](https://graphiql-test.netlify.com/) - the min.js bundle for the current ref -2. [`graphiql.js` demo](https://graphiql-test.netlify.com/dev) - development build is nice for react inspector, debugging, etc -3. [bundle analyzer for graphiql.min.js](https://graphiql-test.netlify.com/analyzer) +- The [latest stable version](http://graphql.org/swapi-graphql) +- The current state of the `master` branch: + - Using the [minified bundles](https://graphiql-test.netlify.com/) + - Using the [development bundles](https://graphiql-test.netlify.com/dev) (good for inspecting, debugging, etc) +- Each pull request will also get its own preview deployment on Netlify, you'll find a link in the GitHub checks ## Examples -- [`Unpkg (CDN)`](https://github.com/graphql/graphiql/blob/main/examples/graphiql-cdn/) - a single html file using cdn assets and a script tag -- [`Webpack`](https://github.com/graphql/graphiql/blob/main/examples/graphiql-webpack/) - a starter for webpack -- [`Create React App`](https://github.com/graphql/graphiql/blob/main/examples/graphiql-create-react-app) - an example using [Create React App](https://create-react-app.dev/) -- [`Parcel`](https://github.com/graphql/graphiql/blob/main/examples/graphiql-parcel) - an example using [Parcel](https://parceljs.org/) -- `Rollup` - TODO +- [`Unpkg (CDN)`](../../examples/graphiql-cdn) - A single HTML file using CDN assets and a script tag +- [`Webpack`](../../examples/graphiql-webpack) - A starter for Webpack +- [`Create React App`](../../examples/graphiql-create-react-app) - An example using [Create React App](https://create-react-app.dev/) +- [`Parcel`](../../examples/graphiql-parcel) - An example using [Parcel](https://parceljs.org/) ## Getting started -### Modules - -You can use the `graphiql` module, however bear in mind that `react` `react-dom` and `graphql` will all need to be present already for it to work, as they are `peerDependencies` - -With `npm`: - -```sh -npm install --save graphiql react react-dom graphql -``` - -Alternatively, if you are using [`yarn`](https://yarnpkg.com/): - -``` -yarn add graphiql react react-dom graphql -``` +> If you're looking to upgrade from `graphiql@1.x` to `graphiql@2`, check out the [migration guide](../../docs/migration/graphiql-2.0.0.md)! ### UMD @@ -78,155 +59,95 @@ With `unpkg`/`jsdelivr`, etc.: ## Usage -Build for the web with [webpack](https://webpack.js.org/) or [browserify](http://browserify.org/), or use the pre-bundled `graphiql.js` file. See the [cdn example](https://github.com/graphql/graphiql/blob/main/examples/graphiql-cdn/) in the git repository to see how to use the pre-bundled file, or see the [webpack example](https://github.com/graphql/graphiql/blob/main/examples/graphiql-webpack) to see how to bundle an application using the `GraphiQL` component. +### Using as package + +The `graphiql` package can be installed using your favorite package manager. You also need to have `react`,`react-dom` and `graphql` installed which are peer dependencies of `graphiql`. -### Usage: NPM module +```sh +npm install --save graphiql react react-dom graphql +``` -**Note**: If you are having webpack issues or questions about webpack, make sure you've cross-referenced your webpack configuration with our own [webpack example](https://github.com/graphql/graphiql/blob/main/examples/graphiql-webpack) first. We now have tests in CI that ensure this always builds, and we ensure it works end-to-end with every publish. +The package exports a bunch of React components: -Using another GraphQL service? Here's how to get GraphiQL set up: +- The `GraphiQLProvider` components renders multiple context providers that encapsulate all state management +- The `GraphiQLInterface` component renders the UI that makes up GraphiQL +- The `GraphiQL` component is a combination of both the above components -GraphiQL provides a React component responsible for rendering the UI, which should be provided with a required `fetcher function for executing GraphQL operations against your schema. +There is a single prop that is required for the `GraphiQL` component called fetcher. A fetcher 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. -For HTTP transport implementations, we recommend using the [fetch](https://fetch.spec.whatwg.org/) standard API, but you can use anything that matches [the type signature](https://graphiql-test.netlify.app/typedoc/modules/graphiql-toolkit.html#fetcher), including async iterables and observables. +An easy way to get create such a function is the [`createGraphiQLFetcher`](../graphiql-toolkit/src/create-fetcher/createFetcher.ts) method exported from the `@graphiql/toolkit` package. If you want to implement your own fetcher function you can use the `Fetcher` type from `@graphiql/toolkit` to make sure the signature matches what GraphiQL expects. -You can also install `@graphiql/create-fetcher` to make it easier to create a simple fetcher for conventional http and websockets transports. It uses `graphql-ws@4.x` protocol by default. +The following is everything you need to render GraphiQL in your React application: -```js +```jsx +import { createGraphiQLFetcher } from '@graphiql/toolkit'; +import { GraphiQL } from 'graphiql'; import React from 'react'; import ReactDOM from 'react-dom'; -import GraphiQL from 'graphiql'; -import { createGraphiQLFetcher } from '@graphiql/toolkit'; +import 'graphiql/graphiql.css'; const fetcher = createGraphiQLFetcher({ - url: window.location.origin + '/graphql', + url: 'https://my.backend/graphql', }); -ReactDOM.render( - , - document.body, -); +ReactDOM.render(, document.body); ``` -[Read more about using `createGraphiQLFetcher` in the readme](https://github.com/graphql/graphiql/tree/main/packages/graphiql-toolkit/docs/create-fetcher.md) to learn how to add headers, support the legacy `subscriptions-transport-ws` protocol, and more. +### Using as UMD bundle over CDN (Unpkg, JSDelivr, etc) -### Usage: UMD Bundle over CDN (Unpkg, JSDelivr, etc) - -Don't forget to include the CSS file on the page! If you're using `npm` or `yarn`, you can find it in `node_modules/graphiql/graphiql.css`, or you can download it from the [releases page](https://github.com/graphql/graphiql/releases). - -For an example of setting up a GraphiQL, check out the [example](https://github.com/graphql/graphiql/blob/main/examples/graphiql-cdn/) in this repository which also includes a few useful features highlighting GraphiQL's API. - -The most minimal way to set up GraphiQL is a single index.html file: - -```html - - - Simple GraphiQL Example - - - -
- - - - - - - - -``` - -**Notes**: - -- the inlined styles are important for ensuring GraphiQL is visible and fills the canvas. -- using `React.createElement` directly is laborious, so follow the webpack instructions above for more highly customized implementation -- we can use [`GraphiQL.createFetcher`](https://github.com/graphql/graphiql/tree/main/packages/graphiql-toolkit/docs/create-fetcher.md) in the UMD bundle only, so that it can be tree shaken out for modules - -### GraphiQL for my GraphQL Service/HTTP Server/Etc - -You may be using a runtime that already provides graphiql, or that provides it via a middleware. For example, we support [`express-graphql`](https://github.com/graphql/express-graphql)! - -I would suggest a search for "graphiql " such as "graphiql express", "graphiql absinthe", etc to learn a potentially simpler route to setup for your environment. There are many npm packages, ruby gems, java utilities for deploying graphiql. - -Here are some example searches: - -- https://www.npmjs.com/search?q=graphiql - ~117 hits -- https://pypi.org/search/?q=graphiql - ~33 hits -- https://search.maven.org/search?q=graphiql - ~15 hits -- https://rubygems.org/search?utf8=%E2%9C%93&query=graphiql - ~6 hits -- https://godoc.org/?q=graphiql - ~12 hits -- https://packagist.org/?query=%22graphiql%22 - ~5 hits -- https://crates.io/search?q=graphiql - ~2 hits - -This doesn't include runtimes or libraries where GraphiQL is used but isn't referenced in the package registry search entry. +There exist pre-bundled static assets that allow you to easily render GraphiQL just by putting together a single HTML file. Check out the `index.html` file in the [example project](../../examples/graphiql-cdn/) in this repository. ## Customize GraphiQL supports customization in UI and behavior by accepting React props and children. - - ### Props -`fetcher` is the only required prop for ``. - For props documentation, see the [API Docs](https://graphiql-test.netlify.app/typedoc/modules/graphiql.html#graphiqlprops-1) -### Children (this pattern will be dropped in 2.0.0) +### Children + +Parts of the UI can be customized by passing children to the `GraphiQL` or the `GraphiQLInterface` component. - ``: Replace the GraphiQL logo with your own. -- ``: Add a custom toolbar above GraphiQL. If not provided, a - default toolbar may contain common operations. Pass the empty - `` if an empty toolbar is desired. +- ``: Add a custom toolbar below the execution button. Pass the empty `` if an empty toolbar is desired. Use the components provided by `@graphiql/react` to create toolbar buttons with proper styles. + +- ``: Add a custom footer shown below the response editor. -- ``: Add a button to the toolbar above GraphiQL. +### Plugins -- ``: Add a dropdown menu to the toolbar above GraphiQL. +Starting with `graphiql@2` there exists a simple plugin API that allow you to build your own custom tools right into GraphiQL. - - ``: Items for a menu. +There are two built-in plugins that come with GraphiQL: The documentation explorer and the query history. Both can be toggled using icons in the sidebar on the left side of the screen. When opened, they appear next to the sidebar in a resizable portion of the screen. -- ``: Add a select list to the toolbar above GraphiQL. +To define your own plugin, all you need is a JavaScript object with three properties: - - ``: Options for a select list. +- `title`: A unique title for the plugin (this will show up in a tooltip when hovering over the sidebar icon) +- `icon`: A React component that renders an icon which will be included in the sidebar +- `content`: A React component that renders the plugin contents which will be shown next to the sidebar when opening the plugin -- ``: Add a group of associated controls to the - toolbar above GraphiQL. Expects children to be ``, - ``, or ``. +You can pass a list of plugin objects to the `GraphiQL` component using the `plugins` prop. You can also control the visibility state of plugins using the `visiblePlugin` prop and react to changes of the plugin visibility state using the `onTogglePluginVisibility` prop. -- ``: Add a custom footer below GraphiQL Results. +Inside the component you pass to `content` you can interact with the GraphiQL state using the hooks provided by `@graphiql/react`. As an example, check out how you can integrate the OneGraph Explorer in GraphiQL using the plugin API in the [example folder](../../examples/graphiql-explorer) in this repo. -## Full Usage Example +### Theming -TODO: kitchen sink example project or codesandbox +The GraphiQL interface uses CSS variables for theming, in particular for colors. Check out the [`root.css`](../graphiql-react/src/style/root.css) file for the available variables. -### Applying an Editor Theme +Overriding these variables is the only officially supported way of customizing the appearance of GraphiQL. Starting from version 2, class names are no longer be considered stable and might change between minor or patch version updates. -In order to theme the editor portions of the interface, you can supply a `editorTheme` prop. You'll also need to load the appropriate CSS for the theme (similar to loading the CSS for this project). [See the themes available here](https://codemirror.net/demo/theme.html). +### Editor Theme -```js -// In your html +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. + +```jsx +// In your document head: -// In your GraphiQL JSX - +// 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/editor/style/codemirror.css). diff --git a/packages/graphiql/resources/graphiql.jpg b/packages/graphiql/resources/graphiql.jpg deleted file mode 100644 index 65a57c758cd..00000000000 Binary files a/packages/graphiql/resources/graphiql.jpg and /dev/null differ diff --git a/packages/graphiql/resources/graphiql.png b/packages/graphiql/resources/graphiql.png new file mode 100644 index 00000000000..de073bc9931 Binary files /dev/null and b/packages/graphiql/resources/graphiql.png differ diff --git a/resources/images/current-ecosystem.jpg b/resources/images/current-ecosystem.jpg deleted file mode 100644 index 60c5bc18194..00000000000 Binary files a/resources/images/current-ecosystem.jpg and /dev/null differ diff --git a/resources/images/proposed-ecosystem.jpg b/resources/images/proposed-ecosystem.jpg deleted file mode 100644 index 8d5584db1b2..00000000000 Binary files a/resources/images/proposed-ecosystem.jpg and /dev/null differ