GraphQL LSP VS Code Extension

A VS Code extension that provides comprehensive GraphQL language support including validation, navigation, hover information, and find references.

Features

Validation & Diagnostics

• Real-time validation: Instant feedback on GraphQL syntax and semantic errors
• Schema validation: Type checking against your GraphQL schema
• Configurable linting: Custom lint rules with tool-specific configuration
• Project-wide analysis: Validates fragment usage across files

Navigation

• Goto Definition: Navigate to definitions of:
  • Fragment spreads → Fragment definitions
  • Type references → Type definitions
  • Field selections → Schema field definitions
  • Variables → Variable definitions
  • Arguments → Argument definitions
  • Enum values → Enum value definitions
  • Directives → Directive definitions
• Find References: Find all usages of:
  • Fragment definitions
  • Type definitions
  • Fields (across schema and operations)

Code Intelligence

• Hover Information: Type details and descriptions for GraphQL elements
• Works with embedded GraphQL: Supports GraphQL in TypeScript/JavaScript, Vue, Svelte, and Astro files

Multi-Language Support

• Pure GraphQL files (.graphql, .gql)
• Embedded GraphQL in TypeScript/JavaScript (gql tagged templates)
• Vue Single File Components (.vue)
• Svelte components (.svelte)
• Astro pages (.astro)
• Automatic position adjustment for embedded queries

Installation

Install GraphQL Analyzer from the VS Code Marketplace, or search "GraphQL Analyzer" in the Extensions view (Ctrl/Cmd+Shift+X).

Bundled LSP Server

The extension includes a pre-compiled LSP server binary for your platform. No separate installation or downloads required - it works immediately after installation.

Supported platforms:

• macOS (Intel and Apple Silicon)
• Linux (x86_64 and ARM64)
• Windows (x86_64)

Configuration

The extension supports several configuration options in VS Code settings:

Basic Settings

{
  // Logging verbosity (off, messages, verbose)
  "graphql.trace.server": "off",

  // Custom path to LSP server binary (optional)
  "graphql.server.path": "/path/to/graphql-lsp",

  // Environment variables for LSP server
  "graphql.server.env": {
    "RUST_LOG": "debug",
    "OTEL_TRACES_ENABLED": "1"
  }
}

Linting Configuration

Linting is configured via .graphqlrc.yaml in your project root. Rule names use camelCase:

# Basic configuration
schema: "schema.graphql"
documents: "src/**/*.{graphql,ts,tsx,vue,svelte,astro}"

# Lint configuration under extensions.lint
extensions:
  lint:
    extends: recommended
    rules:
      noDeprecated: warn
      requireSelections: error
      redundantFields: error
      noUnusedFields: off

  # LSP-specific overrides
  lsp:
    lint:
      rules:
        noUnusedFields: off

See Configuration Documentation for more details.

Usage Examples

Goto Definition

Place your cursor on any GraphQL element and press F12 (or right-click → "Go to Definition"):

# Click on "UserFields" and jump to its definition
query GetUser {
  user {
    ...UserFields # F12 → jumps to fragment definition
  }
}

fragment UserFields on User {
  id
  name
}

Find References

Right-click on a fragment or type definition and select "Find All References":

# Right-click on "UserFields" to see all places it's used
fragment UserFields on User {
  id
  name
}

Hover Information

Hover over any type or field to see its documentation:

query {
  user {
    name # Hover to see: String! - The user's full name
  }
}

Development Setup

Prerequisites

• Rust toolchain (see rust-toolchain.toml in repo root)
• Node.js and pnpm (versions pinned via mise — run mise install)

Quick Install (Recommended)

Build the LSP server and install the extension in one step:

git clone https://github.com/trevor-scheer/graphql-analyzer.git
cd graphql-analyzer

# Debug build
cargo xtask install

# Release build (optimized)
cargo xtask install --release

This builds the LSP binary, bundles it into the extension, and installs the .vsix into VS Code. After installing, reload your VS Code window.

Manual Steps

If you need more control (e.g., for debugging the extension itself):

1. Build the LSP server:

   cargo build --package graphql-lsp
   

2. Install extension dependencies:

   cd editors/vscode
   pnpm install
   pnpm run compile
   

3. Launch extension in debug mode:

   Open the editors/vscode directory in VS Code and press F5 to launch the Extension Development Host.

4. Set custom binary path (optional):

   The extension automatically uses target/debug/graphql when running from the repository. To override:

   export GRAPHQL_PATH=/custom/path/to/graphql
   

   Or set graphql.server.path in VS Code settings.

Testing

1. In the Extension Development Host window, open a folder with a .graphqlrc.yaml config
2. Create or open a .graphql file
3. Test features:
   • Validation: Write invalid GraphQL and see error diagnostics
   • Goto Definition: F12 on fragment spreads, types, fields
   • Find References: Right-click → Find All References
   • Hover: Hover over types and fields

Example test query:

query GetUser($id: ID!) {
  user(id: $id) {
    id
    name
    email
  }
}

Troubleshooting

Extension Not Working

Check LSP server status:

1. Open VS Code Output panel (View → Output)
2. Select "GraphQL Language Server" from dropdown
3. Look for errors or connection issues

Common solutions:

• Ensure .graphqlrc.yaml exists in your project root
• Verify schema file path is correct in config
• Check that document patterns match your GraphQL files
• Reload VS Code window (Ctrl/Cmd+Shift+P → "Developer: Reload Window")

LSP Server Not Starting

Check binary exists:

# If using auto-download
ls ~/.vscode/extensions/*/graphql-lsp-*

# If using local build
ls target/debug/graphql-lsp

Enable debug logging:

{
  "graphql.trace.server": "verbose",
  "graphql.server.env": {
    "RUST_LOG": "debug"
  }
}

No Diagnostics Showing

Verify configuration:

• Check that .graphqlrc.yaml is valid YAML
• Ensure schema file exists and is readable
• Verify document glob patterns match your files

Check file associations:

• Ensure .graphql files are recognized
• For TypeScript/JavaScript, GraphQL must be in gql tagged templates

Performance Issues

Disable expensive lints:

extensions:
  lsp:
    lint:
      rules:
        unused_fields: off
        unused_fragments: off

Profile with OpenTelemetry:

{
  "graphql.server.env": {
    "OTEL_TRACES_ENABLED": "1",
    "RUST_LOG": "debug"
  }
}

Then view traces at http://localhost:16686 (requires Jaeger running).

Extension Development

Building

pnpm run compile    # Compile TypeScript
pnpm run watch      # Watch mode for development

Formatting & Linting

pnpm run format     # Format with Prettier
pnpm run format:check  # Check formatting
pnpm run lint       # Lint with oxlint

Packaging

pnpm run package    # Creates .vsix file

Publishing

The extension is automatically published to GitHub Releases via CI. For manual publishing:

# Increment version in package.json
pnpm version patch  # or minor, major

# Create and push tag
git tag -a vscode-v0.1.0 -m "Release vscode v0.1.0"
git push origin vscode-v0.1.0

Architecture

Platform-Specific Bundling

This extension uses platform-specific bundling: the compiled LSP server binary is included directly in the extension package for each supported platform. This approach was chosen over download-on-demand for several reasons:

1. Zero-friction experience - Works immediately after installation, no network requests or permission dialogs
2. Reliability - No dependency on GitHub availability or network connectivity
3. Offline support - Works in air-gapped environments
4. Simplicity - Fewer failure modes and simpler extension code

The VS Code Marketplace automatically serves the correct platform-specific extension to users.

Version Coupling

The extension bundles the graphql-lsp binary (the standalone LSP server). This means:

• Extension releases include LSP changes: Any LSP changes that affect IDE features will trigger an extension version bump
• Consistent behavior: The bundled binary version is always known and tested with the extension
• Independent CLI: The CLI (graphql) and LSP (graphql-lsp) are separate binaries; installing one doesn't affect the other

For development, the extension automatically detects and uses target/debug/graphql-lsp when running from the repository, allowing you to test local changes without rebuilding the extension.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

License

MIT OR Apache-2.0