GraphQL Unused

GraphQL Unused is a plugin that marks named GraphQL operations and fragments that appear unused in frontend codebases by tracking generated GraphQL Codegen artifacts, so you can identify dead GQL code right away.

If you use WebStorm (or another JetBrains IDE) or Visual Studio Code (or any of its forks), install the plugin from the appropriate plugin store:

• JetBrains Marketplace
• Visual Studio Code Marketplace

If you want editor-agnostic scans, CI checks, or a scriptable workflow, install the CLI.

Want a safe sandbox first? You can experiment with the plugin and/or the CLI in this sandbox repo. Just clone it and read its readme.md.

Why?

We've been working on a codebase where we used GraphQL Codegen, which is wonderful, because it gives you typesafe GQL operations, but using it introduced a new problem: we had no way of telling when is it safe to remove a GQL query, mutation or fragment on the frontend, because no IDE or plugin was able to detect whether such an entity (well, the code generated from it, e.g. a React hook) is used or not.

So I built this.

Features

• Highlights unused named GraphQL operations in .graphql and .gql files
• Highlights unused fragments
• Tracks generated GraphQL symbol references from JS/TS files
• Adds warnings to the Problems view in JetBrains IDEs
• Supports manual refresh from Tools > Refresh GraphQL Unused Analysis
• Runs as a standalone CLI with text or JSON output
• Lets you configure include roots, exclude globs, generated module patterns, artifact suffixes, and fragment reporting

Install the CLI

Homebrew

brew tap notAnElephant/tap
brew install graphql-unused

The Homebrew formula manages the Java 21 runtime dependency for you.

Direct Download with curl

Tagged GitHub releases publish stable latest-download asset names for the CLI:

• graphql-unused-darwin-arm64.zip
• graphql-unused-darwin-x64.zip
• graphql-unused-linux-x64.zip
• graphql-unused-windows-x64.zip

Direct downloads require Java 21 or newer available via JAVA_HOME or PATH.

macOS or Linux:

PLATFORM=linux-x64 # darwin-arm64 | darwin-x64 | linux-x64
curl -fL -o graphql-unused-$PLATFORM.zip \
  https://github.com/notAnElephant/graphql-unused-plugin/releases/latest/download/graphql-unused-$PLATFORM.zip
unzip graphql-unused-$PLATFORM.zip
./graphql-unused/bin/graphql-unused scan .

Windows PowerShell:

$Platform = "windows-x64"
curl.exe -fL "https://github.com/notAnElephant/graphql-unused-plugin/releases/latest/download/graphql-unused-$Platform.zip" `
  -o "graphql-unused-$Platform.zip"
Expand-Archive "graphql-unused-$Platform.zip" -DestinationPath .
.\graphql-unused\bin\graphql-unused.bat scan .

CLI Usage

Scan the current project:

graphql-unused scan .

Scan a single GraphQL file while still resolving usage against the full project:

graphql-unused scan --project-root . --file src/graphql/viewer.graphql

Emit JSON for CI or scripting:

graphql-unused scan . --format json

Supported config keys in .graphql-unused.properties:

• includeRoots
• excludeGlobs
• generatedModulePatterns
• operationArtifactSuffixes
• fragmentArtifactSuffixes
• includeFragments

Issues, feature requests

If you found a bug in the product or have any ideas to improve it further, feel free to open an issue in this repo or DM me directly, I'll be happy to help.

For Developers

Local builds, sandbox IDE runs, release packaging, and Marketplace publishing are documented in README.developer.md.

Support

If you find this project useful and want to support its development, you can buy me a coffee craft beer on Ko-fi.

License

MIT