Registry / devops / graphql-schema-utilities

graphql-schema-utilities

library1.1.8jsnpmunverified

A CLI tool for merging GraphQL schema files and validating operations against the merged schema, developed by AWS Labs. Version 1.1.8 is the latest stable release. It supports custom validation rules, glob patterns for schema and operation files, and TypeScript types. Unlike graphql-tools which is more comprehensive, this tool focuses specifically on schema merging and operation validation with a simple CLI interface. The package includes directives merging as an option and provides exit codes for CI integration.

devops

npm install graphql-schema-utilities

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GRAPHQL-SCHEMA-UTI

graphql-schema-utilities

devopsjavascriptv1.1.8

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.

graphql-schema-utilities

✓ npx graphql-schema-utilities -s 'schema/**/*.graphql'

✗ npm install graphql-schema-utilities && graphql-schema-utilities -s 'schema/**/*.graphql'

This is a CLI tool primarily used via npx or global install. Programmatic API not exposed; import not available.

Custom Rule (TypeScript Type)

✓ import { ValidationRule } from 'graphql'; then export your function matching RuleVisitor interface

✗ import { GraphQLError } from 'graphql-schema-utilities';

Custom rules are standard graphql-js validation rules; types come from 'graphql' package.

GraphQLError

✓ import { GraphQLError } from 'graphql';

✗ import { GraphQLError } from 'graphql-schema-utilities';

GraphQLError is a class from the 'graphql' package, not from graphql-schema-utilities.

Merge all .graphql files in current directory, validate operations against merged schema, apply custom rules, output merged schema to file.

npx graphql-schema-utilities -s '*.graphql' -p 'operations/**/*.graphql' -r 'custom-rules/*.js' -o merged.graphql

Debug

Known issues

gotchaGlob patterns require quotes to prevent shell expansion; otherwise only the first path is used.

fix

Enclose glob patterns in single quotes: -s '{src/**/*.graphql,lib/**/*.graphql}'

affects: >=0.0.0

deprecatedThe `-d, --includeDirectives` flag is necessary to include custom directives; otherwise they are stripped silently.

fix

Add `-d` flag when merging schemas with custom directives: graphql-schema-utilities -s 'schema.graphql' -d

affects: >=1.0.0

gotchaCustom rules written in TypeScript must be compiled to JavaScript before use; the CLI does not run ts-node.

fix

Compile TypeScript rules to .js files and reference the compiled output.

affects: >=0.0.0

breakingVersion 1.0.0 dropped support for programmatic API (importing module in Node.js).

fix

Use the CLI exclusively via npx or global install; programmatic usage is no longer supported.

affects: >=1.0.0

gotchaValidation rules must export a function matching graphql-js Rule interface; documentation example uses 'context: any' which bypasses type checks.

fix

Define rules with proper TypeScript types using 'ValidationContext' from 'graphql/type/validation'.

affects: >=0.0.0

breakingThe merged output file is always named 'Merged_schema.graphQL' regardless of `-o` flag; the `-o` flag controls only custom rule output path.

fix

Workaround: rename the output file manually; fixed in v2.0.0 (not yet released).

affects: >=1.0.0, <2.0.0

Errors

Common errors & fixes

Error: Cannot find module 'graphql-schema-utilities'

CLI run without npx or global installation.

fix

Use npx: npx graphql-schema-utilities -s 'schema.graphql'

Error: ENOTDIR: not a directory, scandir 'First_Directory/**/*.graphql'

Shell expanded the glob pattern before passing to the CLI, causing it to be treated as literal paths.

fix

Wrap the glob in quotes: -s '{First_Directory/**/*.graphql,Second_Directory/**/*.graphql}'

Error: Unknown argument: --include-directives

Typo in directive flag: correct flag is `-d` not `--include-directives`.

fix

Use `-d` or `--includeDirectives` (camelCase) as per documentation: graphql-schema-utilities -s 'schema.graphql' -d

TypeError: context.reportError is not a function

Custom validation rule expects `context.reportError` but actual API uses `context.reportError()` in graphql-js 16+.

fix

Use `context.reportError(new GraphQLError(...))` (method call) instead of `context.reportError = ...`.

Upgrade

Version history

1.1.8latest on npm

Audit

Dependencies

graphqloptionalPeer dependency for GraphQL type system and validation rules; required both at runtime and for custom rule development.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/awslabs/graphql-schema-utilities ↗

packagegraphql-schema-utilities ↗

homepagehttps://github.com/awslabs/graphql-schema-utilities#readme ↗