SpectaQL and the case for generating GraphQL docs instead of writing them

Three ways to get a schema in, and why that choice matters

SpectaQL is a Node.js library that generates static documentation for a GraphQL schema, and it accepts that schema in three different forms. It can hit a live endpoint with an introspection query. It can read a file that already contains an introspection query result. Or it can take SDL, either as a single file, as an array of files to be merged, or as a glob that resolves to several files to be merged.

That last option, the glob, is the one that changes how a project is organised. If your schema lives in one big schema.graphql file, any of the three routes work. If it is split across a directory of type definitions, the merge and glob routes mean you can point the generator at the directory and let it assemble the schema, and you never maintain a second copy of it.

The audience is anyone with a GraphQL API and a documentation problem, and the stated goal is keeping documentation complete, current and attractive with as little effort as possible. The keyword is current. A generated page is derived from the schema, so it cannot drift out of sync with the types it describes. Hand written API reference pages can, and when they do, developers stop trusting them and start reading the schema by hand.

The counterpoint is equally real. The generator only sees what the schema contains. Behaviour, error semantics and the intent behind a field are not in a type definition, and no amount of configuration will put them there.

What gets generated by default, and what you can hide

By default the generator documents every part of the schema: all Types, Fields, Queries, Mutations, Arguments and Subscriptions. Nothing has to be switched on for the basic reference to appear, which is the opposite of how many documentation tools behave, where you select a list of types and forget one.

There is a blacklisting mechanism on top of that, and it comes in two forms. You can blacklist an entire area, for example telling it not to show Mutations, and you can blacklist individual items in a one-off way. For a public API reference, suppressing internal mutation types is a normal requirement, and having both a coarse and a fine control is what makes that practical without hand editing output.

Examples are handled separately from the schema itself. You can provide them as static metadata in the configuration, or generate them dynamically through a custom generator plugin that you control. The static route is straightforward, but a plugin lets the example for a given field follow the actual schema rather than a copy someone maintained by hand, which is the same drift problem in a smaller form.

There is also a third, less mature route. Dynamic grouping and arranging of the data is supported through a custom data arrangement plugin, and that capability is marked as beta. The word beta in the feature list is a signal about how much you should depend on the shape of that plugin interface.

Installing the CLI and producing your first page

The getting started path is three steps, and the first one is a global install.

npm install -g spectaql
# OR
yarn global add spectaql

A global install is convenient but not the only option. The project notes you can instead clone the repository, or add spectaql as a dependency to an existing project, and the dependency route is covered later with a code example.

Step two is configuration: write a config.yml that specifies how you want the documentation generated. The project keeps a full list of supported options and their descriptions in config-example.yml at the root of the repository, and a smaller working example in examples/config.yml.

Step three is the run, which takes the path to that config file.

npx spectaql config.yml

The result lands in the public directory by default. From there you can copy the generated HTML to a web server, point the tool elsewhere with the target directory option, or start the live preview and read the output in a browser. The three column layout, logo, favicon and the rest arrive with the default theme, which is why the configuration file is where real work happens.

config.yml carries the options, and the CLI overrides them

The configuration file is the main surface of the tool, and the split between YAML and command line matters for how you automate it.

The project states that several options are available on the command line, that some of them are exclusive to the CLI, and that others exist in both places. When an option appears in both, the command line value wins. That precedence rule is stated plainly, and it is the behaviour to design around: keep the site-wide choices in the YAML, and pass the per-run values such as the output directory on the command line.

The output options are where the flexibility shows. You can specify a logo and a favicon, set the target directory and the HTML file name, and choose whether the JavaScript and CSS are emitted in line in the HTML file instead of as separate files. There is also an embeddable mode in which only the body content is generated, so the output can be dropped into an existing site rather than deployed as a standalone page.

Two command line flags come up repeatedly. The target directory option writes the output somewhere other than public, and the `-D` flag serves the docs live, with the browser pointed at http://localhost:4400/.

npm install
npm run develop ./examples/config.yml

That pair of commands is the fastest way to see the tool's range: it installs the project and runs the example build with the configuration that exercises its most interesting parts.

Themes take over CSS, JS and HTML when the default is not enough

The default output is described as a three column page with a modern look and feel, and the project is clear that most things can be customized with ease while just about everything can be customized if you are willing to dig in. The mechanism for that is themes, which cover light tweaking or complete replacement of the CSS, JavaScript and HTML output.

The distinction between tweaking and replacing is worth understanding before you start, because it decides how much work a rebrand costs. A theme that edits the existing markup can change colours, spacing and typography. A theme that replaces the HTML can change the page structure entirely, which is the only route to a layout that the three column default cannot express.

The repository ships examples for this, in a customizations directory and a themes directory alongside the example data and the example output, so there is working material to copy rather than an empty starting point.

The point of view here is that SpectaQL separates presentation from content more thoroughly than most generators do. If your documentation has to look like the rest of your product, that is a supported outcome rather than a fight with the tool. If your documentation has to look like every other generated API reference, the default theme already does that and you can skip the work entirely.

Embedding the generator in your own Node application

SpectaQL is not limited to being a binary you shell out to. It can be imported into a Node application as a dependency, and the project shows a short example of that path.

import { run } from 'spectaql'
...
const spectaqlOptions = {
   specFile: 'path/to/your/config.yml',
   resolveWithOutput: true,
}
const { html } = await run(spectaqlOptions)
...

The shape is simple: pass a run function a specFile pointing at the configuration and a resolveWithOutput flag, and the promise resolves to an object containing the generated html. The project is candid that more documentation on this route is coming soon, so treat the snippet as the starting point rather than a complete reference.

This matters most for teams that already generate their site from a build pipeline. If a Node build step produces your documentation pages, embedding the generator avoids a second toolchain and a second place where the configuration lives. It also means the documentation build can fail the same way any other build step fails, which is a feature in a pipeline that publishes on merge.

The package layout supports the same conclusion. Alongside index.js and the bin directory there is a src directory that is compiled to dist by babel, a separate vendor build step, and static assets shipped with the published package.

Version 3.0.9, an MIT licence, and a single commercial sponsor

The published package version is 3.0.9, and the licence is MIT, which means the code can be used, modified and redistributed inside a closed source product without any obligation to publish your own work. There is no copyleft condition to plan around.

The project has no GitHub releases, so the version in package.json is the reference point and the npm registry is where you pull from. A migration note sits in the repository for anyone coming from a pre 1.0 version, with the breaking changes listed in BREAKING_CHANGES_1.md and a changelog for the newer features. That file has existed for a long time, which is a hint that the 1.0 boundary is old news and the interesting changes are the ones since.

The repository is sponsored by Anvil, and the source of the sponsorship is stated plainly: Anvil uses SpectaQL for its own API documentation and links a blog post describing that use case. The sponsoring company sells PDF filling, PDF generation, e-signature and workflow APIs and it says so on the page.

What that means for an adopter is a governance question worth stating plainly. The library is MIT licensed, so there is no vendor lock in the legal sense. The maintenance reality is that one company funds the work and the maintainers respond to it, and the last push was on 2026-08-09, with the repository not archived.

Editorial conclusion

Adopt SpectaQL if your team ships a GraphQL API whose schema changes faster than anyone can maintain hand written reference pages, and if you can accept a generated site as the source of truth for reference material. Do not adopt it for a small stable schema, and do not expect it to document behavior: it reflects the schema, and everything beyond types, fields, queries, mutations, arguments and subscriptions is your own text. Before you commit, run the example build in examples/config.yml, check that the default three column layout fits your brand, and confirm your Node version satisfies the declared engines field of node >=16 with npm >=7.

Frequently asked questions

Official sources

1. anvilco/spectaql on GitHub
2. Issues
3. License: MIT
4. Project website
5. README