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.

import { getCollection } from 'astro:content';
import { loader } from 'fumadocs-core/source';
import { toFumadocsSource } from '@fumadocs/astro/source';
import { graphql } from '@/lib/graphql'; 

export const source = loader(
  {
    docs: toFumadocsSource(await getCollection('docs'), await getCollection('meta')),
    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 in an island of their own, which wraps <GraphQLPage /> with the docs layout:

---
import type { GetStaticPaths, InferGetStaticPropsType } from 'astro';
import Layout from '@/layouts/Layout.astro';
import { Docs } from '@/components/docs';
import { GraphQLDocs } from '@/components/graphql-docs'; 
import { source } from '@/lib/source';

export const prerender = true;

export const getStaticPaths = (() => {
  return source.getPages().map((page) => ({
    params: { slug: decodeURI(page.slugs.join('/')) || undefined },
    props: { page },
  }));
}) satisfies GetStaticPaths;

type Props = InferGetStaticPropsType<typeof getStaticPaths>;

const { page } = Astro.props;
const pageTree = await source.serializePageTree(source.getPageTree());
---

{/* [!code ++:13] */}
{page.type === 'graphql' && (
  <Layout title={page.data.title ?? 'My App'}>
    <GraphQLDocs
      client:load
      pathname={Astro.url.pathname}
      params={Astro.params}
      tree={pageTree}
      title={page.data.title}
      props={page.data.getGraphQLPageProps()}
    />
  </Layout>
)}

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.