Graphox

A high-performance GraphQL toolset for TypeScript monorepos, providing LSP, type generation, and validation.

Table of Contents

• Features
• Quick Start
• Installation
• Editor Setup
• Commands
• Configuration
• Fragment Directives
• Build Tool Plugins
• Validation Rules
• Architecture
• Common Configurations
• Comparison with GraphQL Code Generator
• Contributing
• Plugin Development
• License

Features

Language Server (LSP)

• Real-time GraphQL validation with granular diagnostics
• Autocomplete, go-to-definition, hover documentation, and find references
• Fragment dependency tracking and validation
• Semantic syntax highlighting and call hierarchy
• File watching with incremental updates
• Automatic codegen on file changes

Type Generation (Codegen)

• TypeScript type generation from GraphQL operations
• Apollo AST generation for apollo-client
• Shared fragment support between packages

Supported Formats

• Standalone .graphql files
• Embedded GraphQL in TypeScript/TSX template literals (gql, graphql tags)

Quick Start

1. Install the CLI

   pnpm add @graphox/cli

2. Create configuration

   # graphox.yaml
   projects:
     - schema: "schema.graphql"
       include: "src/**/*.{ts,tsx}"
       output_dir: "__generated__"

3. Set up your editor - See Editor Setup

4. Run commands

   pnpm graphox check     # Validate GraphQL files
   pnpm graphox codegen   # Generate TypeScript types
   pnpm graphox lsp       # Start LSP (for editors)

Installation

NPM Package (Recommended)

Install via pnpm to automatically download the correct binary for your platform:

pnpm add @graphox/cli
npm install @graphox/cli
yarn add @graphox/cli

Then use with pnpm:

pnpm graphox lsp
pnpm graphox check
pnpm graphox codegen

Or install globally:

pnpm add -g @graphox/cli
graphox lsp
graphox check
graphox codegen

Manual Binary Installation

Download pre-built binaries from the releases page for:

• macOS (x86_64, ARM64)
• Linux (x86_64, ARM64)
• Windows (x86_64, ARM64)

Build Tool Plugins

Optimize bundle size by ensuring GraphQL AST files are properly codesplit.

| Build Tool | Plugin | Documentation | |------------|--------|---------------| | rsbuild | SWC Plugin | plugins/swc/README.md | | Turbopack/Next.js | SWC Plugin | plugins/swc/README.md | | React Native (Metro) | Babel Plugin | plugins/babel/README.md | | Webpack | Babel Plugin | plugins/babel/README.md |

Editor Setup

Set up Graphox as a language server in your editor:

| Editor | Setup Guide | |--------|-------------| | VSCode | editors/vscode/README.md | | Neovim | editors/neovim.md | | IntelliJ | editors/intellij.md |

Quick Editor Configuration

VSCode: Install the Graphox extension or use the npm package.

Neovim: Configure LSP with nvim-lspconfig:

require('lspconfig').graphox.setup({
  cmd = { 'pnpm', 'exec', 'graphox', 'lsp' },
  filetypes = { 'graphql', 'typescript', 'typescriptreact' },
})

IntelliJ/JetBrains: Install LSP4IJ plugin and configure to run pnpm exec graphox lsp.

Commands

# Start the Language Server
graphox lsp

# Validate GraphQL files
graphox check

# Generate TypeScript types
graphox codegen
graphox codegen --clean  # Remove generated files and caches
graphox codegen --watch   # Watches and runs codegen of file changes

# Run performance benchmarks
graphox benchmark

Command Options

• check - Validates all GraphQL files against the schema
• codegen - Generates TypeScript types for operations
• lsp - Starts the Language Server Protocol server

Configuration

Create a graphox.yaml file in your project root.

Basic Example

projects:
  - schema: "schema.graphql"
    include: "src/**/*.{ts,tsx}"
    exclude: "**/*.test.ts"
    output_dir: "__generated__"

Full Configuration

See Common Configurations for detailed examples including:

• Single and multi-project setups
• Custom scalars and schema types
• Performance tuning and LSP tracing
• Monorepo patterns with shared fragments

Configuration Notes

• Configuration is discovered by searching current directory and parent directories for graphox.yaml or graphox.yml
• All file paths in the config are resolved relative to the config file location
• Schema files can be specified as single strings or arrays for multi-file schemas
• Include/exclude patterns support standard glob syntax (**/*.ts, src/**/*.{ts,tsx})
• Projects are matched in order; the first matching project is used for each file

See Validation Rules for configuring validation rules.

Fragment Directives

@public - Shareable Fragments Across Projects

Use @public to make fragments available for import in other projects within your monorepo:

# In package-a/fragments.graphql
fragment UserFields on User @public {
  id
  name
  email
}

# In package-b/query.graphql
query GetUser($id: ID!) {
  user(id: $id) {
    ...UserFields  # Imports from package-a
  }
}

Generated TypeScript types will automatically import the fragment type:

// package-b/query.codegen.ts
import type { UserFields } from "@workspace/package-a";

export interface GetUserQuery {
  user: ({ __typename: "User" } & UserFields) | null;
}

Configuration requirement: Set the import field in your project config to specify how other projects should import from it:

projects:
  - schema: "schema.graphql"
    include: "packages/package-a/**/*.graphql"
    import: "@workspace/package-a"  # Other projects import from here

  - schema: "schema.graphql"
    include: "packages/package-b/**/*.graphql"
    import: "@workspace/package-b"

@type_only - Type-Only Fragments

Use @type_only for fragments that are only used for TypeScript types and never used in actual GraphQL queries:

# Define reusable type-only fragment
fragment UserBaseFields on User @type_only {
  id
  name
}

# Spread it in another fragment to compose types
fragment UserWithEmail on User {
  ...UserBaseFields
  email
}

Generated types will include the fragment but no AST will be generated:

// Only type definition, no DocumentNode/AST
export interface UserBaseFields {
  __typename: "User";
  id: string;
  name: string;
}

// Full fragment with AST
export interface UserWithEmail {
  __typename: "User";
  id: string;
  name: string;
  email: string;
}

export const UserWithEmailFragmentDocument = { /* AST */ };

This prevents warnings about unused fragments for these as the tool is not following use of the typescript types. The LSP will warn if you accidentally use a @type_only fragment in a query and provide a code action to remove it.

Contributing

See CONTRIBUTING.md for detailed information on:

• Development setup and prerequisites
• Testing your changes (CLI and editor)
• Code quality commands
• Release process

Advanced Topics

See docs/architecture.md for in-depth documentation on:

• System architecture and components
• Data flow and processing pipeline
• Performance characteristics
• Caching strategy

See docs/configurations.md for:

• Multi-project workspace setup
• Custom scalar mappings
• Performance tuning
• LSP tracing configuration

Repository

https://github.com/soundtrackyourbrand/graphox