0
# Relay Compiler
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: relay-compiler
7
- **Package Type**: npm
8
- **Language**: Rust (with Node.js wrapper)
9
- **Installation**: `npm install relay-compiler`
10

11
## Core Imports
12

13
### Binary Path Resolution
14

15
```javascript
16
const relayBinary = require('relay-compiler');
17
// Returns platform-specific binary path or null for unsupported platforms
18
```
19

20
### CLI Usage
21

22
```bash
23
# Install globally
24
npm install -g relay-compiler
25

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

29
# Or via npx
30
npx relay-compiler --watch --validate
31
```
32

33
## Basic Usage
34

35
```bash
36
# Basic compilation
37
relay-compiler --src ./src --schema ./schema.graphql --artifact-directory ./src/__generated__
38

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

42
# Validation mode for CI/CD
43
relay-compiler --validate --src ./src --schema ./schema.graphql
44
```
45

46
## Architecture
47

48
The relay-compiler consists of several key components:
49

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

56
## Capabilities
57

58
### [CLI Usage](./cli-usage.md)
59
Primary command-line interface for compiling GraphQL files, including compilation options, watch mode, validation, and platform-specific binary handling.
60

61
**Key APIs:**
62
```bash
63
relay-compiler [OPTIONS]
64
relay-compiler lsp [OPTIONS]
65
relay-compiler config-json-schema
66
relay-compiler codemod <CODEMOD> [OPTIONS]
67
```
68

69
### [Configuration](./configuration.md)
70
Comprehensive configuration system supporting both single-project and multi-project setups with extensive customization options.
71

72
**Key APIs:**
73
```typescript
74
{ .api }
75
interface SingleProjectConfigFile {
76
  language: "javascript" | "typescript" | "flow";
77
  src?: string;
78
  schema?: string;
79
  artifactDirectory?: string;
80
  // 25+ additional configuration options
81
}
82

83
interface MultiProjectConfigFile {
84
  sources: Record<string, string>;
85
  projects: Record<string, ProjectConfig>;
86
  // Additional global options
87
}
88
```
89

90
### [Programmatic API](./programmatic-api.md)
91
Full Rust crate API for building custom tooling, including build system integration, artifact generation, and custom file source handling.
92

93
**Key APIs:**
94
```rust
95
// Core build functions
96
pub fn build_programs(config: &Config) -> Result<Programs, BuildProjectFailure>;
97
pub fn generate_artifacts(programs: &Programs) -> Result<Vec<Artifact>, Error>;
98

99
// Configuration and project management
100
pub struct Config { /* ... */ }
101
pub struct ProjectConfig { /* ... */ }
102
```
103

104
### [Language Server](./language-server.md)
105
LSP implementation providing IDE integration with real-time GraphQL validation, auto-completion, and go-to-definition functionality.
106

107
**Key APIs:**
108
```bash
109
relay-compiler lsp [--config PATH] [--output KIND] [--locate-command SCRIPT]
110
```
111

112
### [Codemods](./codemods.md)
113
Automated code transformation tools for migrating and improving Relay codebases with built-in safety and rollout controls.
114

115
**Key APIs:**
116
```bash
117
relay-compiler codemod mark-dangerous-conditional-fragment-spreads [--rollout-percentage PERCENT]
118
relay-compiler codemod remove-unnecessary-required-directives
119
```
120

121
## Platform Support
122

123
The relay-compiler provides pre-built binaries for:
124
- **macOS**: x64 and ARM64 architectures
125
- **Linux**: x64 and ARM64 architectures  
126
- **Windows**: x64 architecture
127

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

130
## Error Handling
131

132
The compiler provides comprehensive error types for different failure scenarios:
133

134
```typescript
135
{ .api }
136
type CompilerError = 
137
  | "ProjectFilterError"    // Invalid project selection
138
  | "LSPError"             // Language server failures
139
  | "ConfigError"          // Configuration validation failures
140
  | "CompilerError"        // Compilation failures
141
  | "CodemodError";        // Codemod application failures
142
```