Relay Compiler

Relay Compiler is a high-performance GraphQL compilation tool built in Rust that transforms GraphQL documents into optimized code for Relay applications. It provides fast compilation that scales to massive projects, improved developer experience with better error reporting and watch mode, built-in TypeScript support for extraction and type generation, and pre-built binaries for all platforms distributed via npm.

Package Information

• Package Name: relay-compiler
• Package Type: npm
• Language: Rust (with Node.js wrapper)
• Installation: npm install relay-compiler

Core Imports

Binary Path Resolution

const relayBinary = require('relay-compiler');
// Returns platform-specific binary path or null for unsupported platforms

CLI Usage

# Install globally
npm install -g relay-compiler

# Use binary directly
relay-compiler --src ./src --schema ./schema.graphql

# Or via npx
npx relay-compiler --watch --validate

Basic Usage

# Basic compilation
relay-compiler --src ./src --schema ./schema.graphql --artifact-directory ./src/__generated__

# Watch mode for development
relay-compiler --watch --src ./src --schema ./schema.graphql

# Validation mode for CI/CD
relay-compiler --validate --src ./src --schema ./schema.graphql

Architecture

The relay-compiler consists of several key components:

• CLI Interface: Command-line tool with compilation, validation, and watch modes
• Configuration System: Flexible JSON-based configuration supporting single and multi-project setups
• Language Server: Full LSP implementation for IDE integration and real-time feedback
• Codemod System: Automated code transformation tools for migrations and improvements
• Programmatic API: Rust crate API for custom tooling and integration

Capabilities

CLI Usage

Primary command-line interface for compiling GraphQL files, including compilation options, watch mode, validation, and platform-specific binary handling.

Key APIs:

relay-compiler [OPTIONS]
relay-compiler lsp [OPTIONS]
relay-compiler config-json-schema
relay-compiler codemod <CODEMOD> [OPTIONS]

Configuration

Comprehensive configuration system supporting both single-project and multi-project setups with extensive customization options.

Key APIs:

{ .api }
interface SingleProjectConfigFile {
  language: "javascript" | "typescript" | "flow";
  src?: string;
  schema?: string;
  artifactDirectory?: string;
  // 25+ additional configuration options
}

interface MultiProjectConfigFile {
  sources: Record<string, string>;
  projects: Record<string, ProjectConfig>;
  // Additional global options
}

Programmatic API

Full Rust crate API for building custom tooling, including build system integration, artifact generation, and custom file source handling.

Key APIs:

// Core build functions
pub fn build_programs(config: &Config) -> Result<Programs, BuildProjectFailure>;
pub fn generate_artifacts(programs: &Programs) -> Result<Vec<Artifact>, Error>;

// Configuration and project management
pub struct Config { /* ... */ }
pub struct ProjectConfig { /* ... */ }

Language Server

LSP implementation providing IDE integration with real-time GraphQL validation, auto-completion, and go-to-definition functionality.

Key APIs:

relay-compiler lsp [--config PATH] [--output KIND] [--locate-command SCRIPT]

Codemods

Automated code transformation tools for migrating and improving Relay codebases with built-in safety and rollout controls.

Key APIs:

relay-compiler codemod mark-dangerous-conditional-fragment-spreads [--rollout-percentage PERCENT]
relay-compiler codemod remove-unnecessary-required-directives

Platform Support

The relay-compiler provides pre-built binaries for:

• macOS: x64 and ARM64 architectures
• Linux: x64 and ARM64 architectures
• Windows: x64 architecture

Unsupported platforms will receive a clear error message with platform information.

Error Handling

The compiler provides comprehensive error types for different failure scenarios:

{ .api }
type CompilerError = 
  | "ProjectFilterError"    // Invalid project selection
  | "LSPError"             // Language server failures
  | "ConfigError"          // Configuration validation failures
  | "CompilerError"        // Compilation failures
  | "CodemodError";        // Codemod application failures