[graphiql] Allow for full customization of GraphiQL (#3314)

Author: EmrysMyrddin

.changeset/kind-fireants-rush.md

@@ -0,0 +1,11 @@
+---
+'graphql-yoga': minor
+'@graphql-yoga/graphiql': minor
+---
+
+Allow for full customization of the GraphiQL page.
+
+Props from the `YogaGraphiQL` are now forwarded to the underlying GraphiQL components.
+
+The `graphiql` option field type of the Yoga server as also been updated to document which options
+are configurable from the server side. Only serializable options are available.

packages/graphiql/src/YogaGraphiQL.tsx

@@ -32,17 +32,7 @@ const getOperationWithFragments = (
   };
 };
 
-export type YogaGraphiQLProps = Omit<
-  GraphiQLProps,
-  | 'fetcher'
-  | 'isHeadersEditorEnabled'
-  | 'defaultEditorToolsVisibility'
-  | 'onToggleDocs'
-  | 'toolbar'
-  | 'onSchemaChange'
-  | 'query'
-  | 'onEditQuery'
-> &
+export type YogaGraphiQLProps = Partial<GraphiQLProps> &
   Partial<Omit<LoadFromUrlOptions, 'headers'>> & {
     title?: string;
     /**
@@ -98,6 +88,15 @@ export function YogaGraphiQL(props: YogaGraphiQLProps): React.ReactElement {
   const urlLoader = useMemo(() => new UrlLoader(), []);
 
   const fetcher = useMemo(() => {
+    if (props.fetcher) {
+      if (props.endpoint) {
+        // eslint-disable-next-line no-console
+        console.warn(
+          'You are using a custom fetcher and an endpoint. The endpoint will be ignored.',
+        );
+      }
+      return props.fetcher;
+    }
     const executor = urlLoader.getExecutorAsync(endpoint, {
       subscriptionsProtocol: SubscriptionProtocol.GRAPHQL_SSE,
       subscriptionsEndpoint: endpoint, // necessary because graphql-sse in graphql-tools url-loader defaults to endpoint+'/stream'
@@ -123,7 +122,7 @@ export function YogaGraphiQL(props: YogaGraphiQLProps): React.ReactElement {
         },
       });
     };
-  }, [urlLoader, endpoint]) as Fetcher;
+  }, [urlLoader, endpoint, props.fetcher]) as Fetcher;
 
   const [params, setParams] = useUrlSearchParams(
     {
@@ -138,25 +137,34 @@ export function YogaGraphiQL(props: YogaGraphiQLProps): React.ReactElement {
     showAttribution: true,
   });
 
+  if (props.query && !props.onEditQuery) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      'If you provide `query` prop, you should also provide `onEditQuery` prop to handle query changes.',
+    );
+  }
+
   return (
     <div className="graphiql-container">
       <GraphiQLProvider
-        defaultHeaders={props.defaultHeaders}
-        fetcher={fetcher}
-        headers={props.headers}
+        // default values that can be override by props
+        shouldPersistHeaders
         plugins={[explorer]}
-        query={query}
         schemaDescription={true}
-        shouldPersistHeaders={props.shouldPersistHeaders ?? true}
+        query={query}
+        {...props}
+        fetcher={fetcher}
       >
         <GraphiQLInterface
           isHeadersEditorEnabled
           defaultEditorToolsVisibility
-          onEditQuery={query => {
+          {...props}
+          onEditQuery={(query, ast) => {
             setParams({
               query,
             });
             setQuery(query);
+            props.onEditQuery?.(query, ast);
           }}
         >
           <GraphiQL.Logo>

packages/graphql-yoga/src/plugins/use-graphiql.ts

@@ -62,6 +62,62 @@ export type GraphiQLOptions = {
    * Whether to use the GET HTTP method for queries when querying the original schema
    */
   useGETForQueries?: boolean;
+  /**
+   * "external" fragments that will be included in the query document (depending on usage)
+   */
+  externalFragments?: string;
+  /**
+   * The maximum number of executed operations to store.
+   * @default 20
+   */
+  maxHistoryLength?: number;
+  /**
+   * Whether target GraphQL server support deprecation of input values.
+   * @default false
+   */
+  inputValueDeprecation?: boolean;
+  /**
+   * Custom operation name for the introspection query.
+   */
+  introspectionQueryName?: string;
+  /**
+   * Whether to include schema description in introspection query.
+   * @default false
+   */
+  schemaDescription?: boolean;
+  /**
+   * Editor theme
+   * @default "graphiql"
+   */
+  editorTheme?: string;
+  /**
+   *  Sets the key map to use when using the editor.
+   * @default 'sublime'
+   */
+  keyMap?: 'sublime' | 'emacs' | 'vim';
+  defaultEditorToolsVisibility?: boolean | 'variables' | 'headers';
+  isHeadersEditorEnabled?: boolean;
+  disableTabs?: boolean;
+  /**
+   * Whether to include `isRepeatable` flag on directives.
+   * @default false
+   */
+  directiveIsRepeatable?: boolean;
+  experimentalFragmentVariables?: boolean;
+  /**
+   * Set to `true` in order to convert all GraphQL comments (marked with # sign) to descriptions (""")
+   * GraphQL has built-in support for transforming descriptions to comments (with `print`), but not while
+   * parsing. Turning the flag on will support the other way as well (`parse`)
+   */
+  commentDescriptions?: boolean;
+  /**
+   * Timeout in milliseconds
+   */
+  timeout?: number;
+  /**
+   * Retry attempts
+   */
+  retry?: number;
 };
 
 export type GraphiQLRendererOptions = {