GraphQL

SetupCopy Anchor Link

Install the required packages.

npm i @fumadocs/graphql graphql

Generate StylesCopy Anchor Link

Add the following line:

@import 'tailwindcss';
@import 'fumadocs-ui/css/neutral.css';
@import 'fumadocs-ui/css/preset.css';
@import '@fumadocs/graphql/css/preset.css';

Configure PluginCopy Anchor Link

Create the GraphQL server instance and the <GraphQLPage /> component.

import { createGraphQL } from '@fumadocs/graphql/server';

// note: this is a server-side API
export const graphql = createGraphQL({
  // the GraphQL schema, it accepts:
  // SDL files/URLs (including `extend type`), SDL text,
  // introspection results, and `GraphQLSchema` instances.
  input: ['./schema.graphql'],
});

See createGraphQL() and createGraphQLPage() for their options.

Generate PagesCopy Anchor Link

Pass staticSource() to your loader(). It generates pages without writing files.

staticSource() reads files, so source.ts becomes server-only. Move docs into collections.ts for client code to import.

import { loader } from 'fumadocs-core/source';
import { defineDocs } from 'fumadocs-mdx/macro'; 
import { docs } from '@/lib/collections';
import { graphql } from '@/lib/graphql';

export const docs = defineDocs({
  dir: 'content/docs',
  docs: {
    async: true,
  },
});

// server-only now, as `staticSource()` reads files
export const source = loader(
  {
    docs: docs.toFumadocsSource(),
    graphql: await graphql.staticSource({
      baseDir: 'graphql',
    }),
  },
  {
    baseUrl: '/docs',
    // optional: adds a query/mutation/subscription badge to each page item in page tree
    plugins: [graphql.loaderPlugin()],
  },
);

staticSource() generates a page per operation, grouped into folders by kind (e.g. queries/). Pages of named types are opt-in.

Pages of source now have two types, docs and graphql. Update every place that uses source.

Render GraphQL pages with <GraphQLPage /> in your docs page:

import { docs, source } from '@/lib/source'; 
import { docs } from '@/lib/collections';
import { source } from '@/lib/source';
import { GraphQLPage } from '@/components/api-page';

export async function loader({ params }: Route.LoaderArgs) {
  const slugs = params['*'].split('/').filter((v) => v.length > 0);
  const page = source.getPage(slugs);
  if (!page) throw new Response('Not found', { status: 404 });

  const pageTree = await source.serializePageTree(source.getPageTree());
  if (page.type === 'graphql') {
    return {
      type: 'graphql' as const,
      title: page.data.title,
      props: page.data.getGraphQLPageProps(),
      pageTree,
    };
  }

  return { type: 'docs' as const, path: page.path, pageTree }; 
}

export default function Page({ loaderData }: Route.ComponentProps) {
  const data = useFumadocsLoader(loaderData);

  return (
    <DocsLayout {...baseOptions()} tree={data.pageTree}>
      {data.type === 'graphql' && (
        <DocsPage full>
          <DocsTitle>{data.title}</DocsTitle>
          <DocsBody>
            <GraphQLPage {...data.props} />
          </DocsBody>
        </DocsPage>
      )}
      {data.type === 'docs' && <Content path={data.path} />}
    </DocsLayout>
  );
}

npm run types:check

FeaturesCopy Anchor Link

The official GraphQL integration supports:

• A page per operation (query/mutation/subscription), with the types it uses explored in place
• Arguments, fields, deprecations, default values and @oneOf input objects
• Directives applied in the schema, with their definitions
• Example requests and responses, generated or from your own operations
• Code samples in cURL, JavaScript, Go, Python, Java, C# and Rust
• A playground with a variables form, it runs subscriptions over WebSocket or SSE too
• Markdown of pages for LLMs
• Optional pages for named types, with their usages across the schema

DemoCopy Anchor Link

See the GraphQL example.