spectaql

library3.0.9jsnpmunverified

SpectaQL is a Node.js library (v3.0.9, latest) for auto-generating static GraphQL API documentation. It supports multiple input sources: live endpoints via introspection queries, introspection result files, SDL files, and glob patterns for merging schemas. Key differentiators include customization via themes, markdown support, live preview, and generative examples. Released under the Apache-2.0 license, it is actively maintained by Anvil. Alternatives like GraphQL Playground or GraphiQL focus on interactive exploration, while SpectaQL produces standalone static docs suitable for versioning and hosting.

devops

npm install spectaql

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SPECTAQL

spectaql

devopsjavascriptv3.0.9

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

spectaql

✓ import spectaql from 'spectaql'

✗ const spectaql = require('spectaql')

Default export; ESM-only since v3. CommonJS require may not work without bundler.

SpectaQL

✓ import { SpectaQL } from 'spectaql'

Named export for the class; also available as default.

run

✓ import { run } from 'spectaql'

Convenience function to run generation with a config object.

Generate static GraphQL docs from a live endpoint using an introspection query with auth headers.

import { run } from 'spectaql'; const config = { spec: { introspection: { url: process.env.GRAPHQL_URL ?? 'https://example.com/graphql', headers: { Authorization: `Bearer ${process.env.GRAPHQL_TOKEN ?? ''}` } }, }, output: { file: './docs/index.html', }, }; try { await run(config); console.log('Documentation generated!'); } catch (error) { console.error('Generation failed:', error); }

Debug

Known issues

breakingv3.0.0 dropped Node 14 support; minimum Node 16.

fix

Upgrade Node.js to version >=16.

affects: >=3.0.0

deprecatedCJS require() is deprecated; use ESM imports.

fix

Switch to `import` syntax in ESM context.

affects: >=3.0.0

gotchaIntrospection may be disabled on production GraphQL endpoints; ensure introspection is enabled or use SDL file.

fix

Check that introspection is allowed, or provide an introspection result file or SDL.

affects: *

gotchaCustom theme paths must be absolute; relative paths may fail silently.

fix

Use path.resolve() to create absolute paths for theme config.

affects: *

Errors

Common errors & fixes

Error: Cannot find module 'spectaql'

Using require('spectaql') in a CommonJS environment.

fix

Use import syntax with an ESM-compatible Node project, or use dynamic import: const spectaql = await import('spectaql');

Error: Failed to load schema from introspection URL

Introspection query failed due to network error or disabled introspection.

fix

Verify the URL is correct, introspection is enabled, and proper auth headers are set.

TypeError: run is not a function

Importing wrong export (e.g., default instead of named).

fix

Use `import { run } from 'spectaql'` instead of `import spectaql from 'spectaql'; spectaql.run(...)`.

Upgrade

Version history

3.0.9latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

7 hits · last 30 days

node

Resources

githubhttps://github.com/anvilco/spectaql ↗

packagespectaql ↗

homepagehttps://github.com/anvilco/spectaql ↗