graphql.github.io: the Next.js source behind the GraphQL website

A site repository, not a GraphQL implementation

The scope is narrow and worth stating at the start. The repository contains the source code for the GraphQL website, and the primary language is TypeScript, with the default branch named source rather than main, which tells you the published site is built from a branch that is not the one you would normally expect. The site itself carries the GraphQL overview: GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data, and it provides a complete and understandable description of the data in your API, support for powerful developer tooling, and precise querying. The precision is what yields the listed benefits: clients request only the data they need, new fields and features can be added without impacting existing clients, and field level usage can be tracked and monitored. The specification itself is open source and governed by the GraphQL Foundation, which is a separate thing from this repository and from the Foundation membership discussed later.

Four commands to get the site running locally

The deployment section doubles as the local development instructions, since the site deploys through Vercel on merges to the source branch. To preview changes locally the steps are to clone the repository and change into it, install the dependencies, run the site locally and then open the port in a browser:

git clone https://github.com/graphql/graphql.github.io.git
cd graphql.github.io

pnpm i

pnpm dev

The final step is to open http://localhost:3000 to view it in the browser. The package manager is pinned in the package manifest at pnpm 10.26.2 with an integrity hash, and there is a pnpm-workspace.yaml and a pnpm-lock.yaml in the repository, so the dependency graph is resolved by pnpm and locked. The dev script is next, the build script is next build, and the start script is next start, so the same three commands cover development and production.

A prebuild step that syncs data before every build

The most interesting part of the package manifest is the prebuild script, because it shows the site pulling in outside data at build time rather than hand-maintaining it. Before the build runs, a script fetches GitHub information, another synchronises the landing schema, another synchronises the working groups, and then the schedule is synced for a given year, with the script written so that a schedule sync failure prints a message and continues rather than failing the build:

"prebuild": "tsx scripts/get-github-info && node scripts/sync-landing-schema && node scripts/sync-working-groups && ( pnpm run sync-sched || echo 'Sched sync failed; continuing...' )"

The schedule sync is its own script, run with a year argument of 2026, which tells you the conference schedule is pulled per edition rather than being a static file. The landing schema and working groups are synchronised with node rather than tsx, so those two are plain JavaScript, while the schedule script is TypeScript run through tsx. The design decision worth noticing is the tolerated failure: the conference schedule is considered optional content, so a failure there does not stop the site from building, while a failure in the other three steps does. The repository also has a generate-videos-mappings.py script at the root, so not everything in the pipeline is JavaScript or TypeScript.

Playwright, a link checker and a snippet validator

The test story is threefold, and each piece catches a different class of mistake. The test script runs the Playwright end to end suite and then the unit tests, with a separate test:ui mode for the Playwright UI runner and a test:show-report script to open the last report. The unit tests are not Playwright at all: they run with node using the test runner and the tsx loader over the source files, so the unit layer is plain Node. The second piece is a link checker, run with lychee over the MDX pages with the site as the base URL, which catches the broken outbound links that a documentation site accumulates. The third is a validate:snippets script, which checks the code examples in the documentation, and that matters more than it sounds for a site whose whole subject is a query language, because a wrong snippet in a reference document is a documentation bug that no other check would see.

The specification membership agreement gates every pull request

Contributing has one hard gate that is unlike a normal open source project. Before contributing, all participants must sign the free GraphQL Specification Membership Agreement, and it only has to be done once. It can be signed either as an individual contributor or by an employer, and the signature process starts by opening a pull request against this repository, because the EasyCLA bot will block the merge if the agreement has not been signed. The detailed instructions live in the GraphQL working group repository, and issues go to an operations address. The reason for this arrangement is that the site documents the GraphQL specification, so contributing to it is treated as contributing to the specification itself, and the specification is a foundation-governed artefact with its own participation terms. There is also a financial route: if your company benefits from GraphQL and wants to support the systems and the people behind the community, you can join the GraphQL Foundation as a member.

The content side has its own style and design documents

The repository is as much about how the site is written as about the code. There is a DESIGN.md, a BLOG_STYLE_GUIDE.md, a CONTRIBUTING.md, a notes directory and a scripts directory, and the top level also holds theme.config.tsx, next.config.js, next-sitemap.config.js, tailwind.config.ts, a playwright.config.ts, a postcss config, a prettier config and an eslint config. The scripts themselves cover things a content site needs beyond the framework: a social banner generator, a conference kit banner renderer, and the three sync scripts already mentioned. The style guide for blog posts and the design document together are what a contributor needs before writing prose, and the presence of a BLOG_STYLE_GUIDE.md and a DESIGN.md as separate documents in the root suggests the maintainers treat content quality as a first-class concern rather than something the code review covers.

Dependency upkeep is automated, and the docs are split by audience

The public facing content is organised by what a reader wants, and the site navigation mirrors it: the website itself, reference documentation, a page listing language support, tools and services, a frequently asked questions page and a community resources page. On the maintenance side, renovate.json is present, so dependency updates are opened as automated pull requests rather than done by hand, and a patches directory holds the patch files that some dependencies need, which is a sign that at least one dependency is not usable unmodified. The repository also carries a node version file, an npmrc and an AGENTS.md alongside a CLAUDE.md, which is the current convention for shipping coding agent instructions inside a project. The last push was on 2026-10-22, and the site is deployed automatically on every merge, so the gap between a merged change and a live page is short.

Editorial conclusion

graphql.github.io suits a documentation site maintainer who wants a Next.js setup with schema-aware code samples, generated landing data and a scheduled conference list, and who wants to see how a project of this kind wires its content pipeline into the build. It does not suit someone looking for a GraphQL server or library, because the GraphQL implementation is elsewhere and this repository is only the website. Before you contribute, sign the GraphQL Specification Membership Agreement, since the EasyCLA bot blocks the merge without it, and read the DESIGN.md and BLOG_STYLE_GUIDE.md files, which are the two documents that tell you what a change to the site is supposed to look like.

Frequently asked questions

Official sources

1. graphql/graphql.github.io on GitHub
2. Issues
3. License: MIT
4. Project website
5. README