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.

!Example

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

``bash


CLI

pnpm add @graphql-inspector/cli

Core API for programmatic usage

pnpm add @graphql-inspector/core
`

$3

Compares schemas and finds breaking or dangerous changes.

CLI:

$ graphql-inspector diff OLD_SCHEMA NEW_SCHEMA

API:

`typescript
import { Change, diff } from '@graphql-inspector/core'

const changes: Change[] = diff(schemaA, schemaB)
`

!Diff

$3

Finds similar / duplicated types.

CLI:

$ graphql-inspector similar SCHEMA

API:

`typescript
import { similar, SimilarMap } from '@graphql-inspector/core'

const similar: SimilarMap = similar(schema, typename, threshold)
`

!Similar

$3

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:

`typescript
import { coverage, SchemaCoverage } from '@graphql-inspector/core'

const schemaCoverage: SchemaCoverage = coverage(schema, documents)
`

!Coverage

$3

Validates documents against a schema and looks for deprecated usage.

CLI:

$ graphql-inspector validate DOCUMENTS SCHEMA

API:

`typescript
import { InvalidDocument, validate } from '@graphql-inspector/core'

const invalid: InvalidDocument[] = validate(documentsGlob, schema)
`

!Validate

$3

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
`

$3

Serves a GraphQL server with faked data and GraphQL Playground

CLI:

$ graphql-inspector serve SCHEMA

`bash
✅ Serving the GraphQL API on http://localhost:4000/
`

$3

Introspects a GraphQL Server and writes the result to a file

CLI:

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

`bash
✅ Introspection result saved to schema.json
`

$3

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

`bash


install

pnpm add --global @graphql-inspector/actions

use

$ graphql-inspector-github
`

`json
{
"name": "app",
"scripts": {
"precommit": "graphql-inspector introspect schema.js --write schema.graphql && git add schema.graphql"
},
"graphql-inspector": {
"diff": true,
"schema": {
"ref": "master",
"path": "schema.graphql"
}
}
}
`

Get GitHub annotations in your PRs.

!GitHub

$3

$3

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

`typescript
// String
export default
type Query {
hello: String
}

// GraphQLSchema
export default makeExecutableSchema({...});

// GraphQL Document
export default gql
type Query {
hello: String
}

// IntrospectionQuery result
export default {
data: {
__schema: {
...
}
}
}
``

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

$3

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_).

$3

Find out what the CLI is capable of:

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

License

MIT © Kamil Kisiela