GraphQL Inspector

GraphQL Inspector outputs a list of changes between two GraphQL schemas. Every change is precisely explained and marked as breaking, non-breaking or dangerous. It helps you validate documents and fragments against a schema and even find similar or duplicated types.

Features

Major features:

• Compares schemas
• Finds breaking or dangerous changes
• Validates documents against a schema
• Finds similar / duplicated types
• Schema coverage based on documents
• Serves a GraphQL server with faked data and GraphQL Playground
• GitHub Bot
• GitHub Actions

GraphQL Inspector has a CLI and also a programmatic API, so you can use it however you want to and even build tools on top of it.

Installation

1# CLI
2pnpm add @graphql-inspector/cli
3
4# Core API for programmatic usage
5pnpm add @graphql-inspector/core

Compare schemas

Compares schemas and finds breaking or dangerous changes.

CLI:

$ graphql-inspector diff OLD_SCHEMA NEW_SCHEMA

API:

1import { Change, diff } from '@graphql-inspector/core'
2
3const changes: Change[] = diff(schemaA, schemaB)

Find similar types

Finds similar / duplicated types.

CLI:

$ graphql-inspector similar SCHEMA

API:

1import { similar, SimilarMap } from '@graphql-inspector/core'
2
3const similar: SimilarMap = similar(schema, typename, threshold)

Check coverage

Schema coverage based on documents. Find out how many times types and fields are used in your application.

CLI:

$ graphql-inspector coverage DOCUMENTS SCHEMA

API:

1import { coverage, SchemaCoverage } from '@graphql-inspector/core'
2
3const schemaCoverage: SchemaCoverage = coverage(schema, documents)

Validate documents

Validates documents against a schema and looks for deprecated usage.

CLI:

$ graphql-inspector validate DOCUMENTS SCHEMA

API:

1import { InvalidDocument, validate } from '@graphql-inspector/core'
2
3const invalid: InvalidDocument[] = validate(documentsGlob, schema)

Audit documents

Audit your documents for useful metrics such as query depth, directive count and alias count.

CLI:

$ graphql-inspector audit DOCUMENTS

API:

Not available

$ pnpm graphql-inspector audit "packages/**/*.graphql|packages/**/*.ts(x)"

Maximum depth is 16
Maximum alias amount is 3
Maximum directive amount is 6

$ pnpm graphql-inspector audit "packages/**/*.graphql|packages/**/*.ts(x)" --detail

┌────────────────┬───────┬─────────┬────────────┐
│ Operation Name │ Depth │ Aliases │ Directives │
├────────────────┼───────┼─────────┼────────────┤
│ getFoo         │ 1     │ 2       │ 6          │
├────────────────┼───────┼─────────┼────────────┤
│ getBar         │ 16    │ 3       │ 0          │
└────────────────┴───────┴─────────┴────────────┘

Maximum depth is 16
Maximum alias amount is 3
Maximum directive amount is 6

Serve faked GraphQL API

Serves a GraphQL server with faked data and GraphQL Playground

CLI:

$ graphql-inspector serve SCHEMA

1✅ Serving the GraphQL API on http://localhost:4000/

Introspect GraphQL server

Introspects a GraphQL Server and writes the result to a file

CLI:

$ graphql-inspector introspect SCHEMA --write schema.json

1✅ Introspection result saved to schema.json

GitHub Bot and GitHub Actions

Have a per-repository, self-hosted GraphQL Inspector service or deploy it with Docker.

1# install
2pnpm add --global @graphql-inspector/actions
3# use
4
5$ graphql-inspector-github

1{
2  "name": "app",
3  "scripts": {
4    "precommit": "graphql-inspector introspect schema.js --write schema.graphql && git add schema.graphql"
5  },
6  "graphql-inspector": {
7    "diff": true,
8    "schema": {
9      "ref": "master",
10      "path": "schema.graphql"
11    }
12  }
13}

Get GitHub annotations in your PRs.

CLI in more details

SCHEMA

Path to a CommonJS or ES Module that exports an object

Example:

graphql-inspector coverage ./src/schema.js

Example with TypeScript:

graphql-inspector coverage ./src/schema.ts --require ts-node/register

1// String
2export default `
3  type Query {
4    hello: String
5  }
6`
7
8// GraphQLSchema
9export default makeExecutableSchema({...});
10
11// GraphQL Document
12export default gql`
13  type Query {
14    hello: String
15  }
16`
17
18// IntrospectionQuery result
19export default {
20  data: {
21    __schema: {
22      ...
23    }
24  }
25}

Pointer to a Git repository

Example:

graphql-inspector diff git:origin/master:schema.graphql

Pattern:

git:ref:path/to/file

Pointer to a GitHub repository

Example:

graphql-inspector coverage github:kamilkisiela/graphql-inspector-example#master:schema.graphql

Pattern:

github:owner/name#ref:path/to/file

GraphQL File

Example:

graphql-inspector coverage schema.graphql
graphql-inspector coverage schema.gql

JSON File

Example:

graphql-inspector coverage introspected-schema.json

URL to a GraphQL endpoint

Example:

graphql-inspector coverage https://localhost:3000/graphql

DOCUMENTS

Glob pattern

Example:

graphql-inspector validate ./src/**/*.{js,jsx,tsx,graphql} https://localhost:3000/graphql

Supports TypeScript, JavaScript and GraphQL Files (Extensions: ts,tsx,js,jsx,graphql,gql,graphqls).

Help

Find out what the CLI is capable of:

graphql-inspector --help
graphql-inspector similar --help

License

MIT © Kamil Kisiela