tessl/npm-relay-compiler
A high-performance GraphQL compilation tool built in Rust for building Relay applications with optimized queries and type generation.
—
Pending
cli-usage.mddocs/
CLI Usage
The Relay Compiler command-line interface provides powerful tools for compiling GraphQL files, running in watch mode, validating changes, and managing LSP integration.
Installation
# Install globally
npm install -g relay-compiler
# Install locally
npm install relay-compilerPlatform Binary Resolution
The relay-compiler package automatically detects your platform and uses the appropriate binary:
const relayBinary = require('relay-compiler');
console.log(relayBinary); // Returns path to platform-specific binary or nullSupported Platforms:
- macOS x64:
macos-x64/relay - macOS ARM64:
macos-arm64/relay - Linux x64:
linux-x64/relay - Linux ARM64:
linux-arm64/relay - Windows x64:
win-x64/relay.exe
Main Compiler Command
The default command compiles Relay files and writes generated files.
{ .api }
relay-compiler [OPTIONS]Options
{ .api }
--watch, -w # Compile and watch for changes
--project, -p <PROJECT> # Compile specific project (repeatable)
--config <PATH> # Use specific config file
--src <PATH> # Path to source directory
--schema <PATH> # Path to schema file
--artifact-directory <PATH> # Output directory for artifacts
--repersist # Force re-persistence of queries
--output <KIND> # Verbosity level
--validate # Check for changes without writingOutput Levels
{ .api }
type OutputKind = "debug" | "quiet" | "quiet-with-errors" | "verbose";Usage Examples
# Basic compilation
relay-compiler --src ./src --schema ./schema.graphql
# Watch mode for development
relay-compiler --watch --src ./src --schema ./schema.graphql
# Compile specific projects
relay-compiler --project web --project mobile
# Validation mode (no file writes)
relay-compiler --validate --src ./src --schema ./schema.graphql
# Custom artifact directory
relay-compiler --src ./src --schema ./schema.graphql --artifact-directory ./generated
# Verbose output with re-persistence
relay-compiler --output verbose --repersist --src ./src --schema ./schema.graphqlLanguage Server Command
Run the LSP server for IDE integration.
{ .api }
relay-compiler lsp [OPTIONS]LSP Options
{ .api }
--config <PATH> # Config file path
--output <KIND> # Verbosity level (default: quiet-with-errors)
--locate-command <SCRIPT> # Script for GraphQL entity location lookupUsage Examples
# Start LSP server
relay-compiler lsp
# Start with custom config
relay-compiler lsp --config ./relay.config.json
# Start with entity location script
relay-compiler lsp --locate-command "./scripts/find-graphql-entity.sh"
# Start with debug output
relay-compiler lsp --output debugConfiguration Schema Command
Print the JSON schema for Relay compiler configuration.
{ .api }
relay-compiler config-json-schemaThis outputs the complete JSON schema definition for configuration validation and IDE support.
# Output schema to file
relay-compiler config-json-schema > relay-config.schema.jsonCodemod Commands
Apply automated code transformations with safety controls.
{ .api }
relay-compiler codemod <CODEMOD> [OPTIONS]Available Codemods
Mark Dangerous Conditional Fragment Spreads
{ .api }
relay-compiler codemod mark-dangerous-conditional-fragment-spreads [OPTIONS]Options:
--rollout-percentage, -r <PERCENT>: Percentage or range (e.g., "50" or "20-30")--project, -p <PROJECT>: Target specific projects--config <PATH>: Use specific config file
Usage Examples:
# Apply to 50% of files
relay-compiler codemod mark-dangerous-conditional-fragment-spreads --rollout-percentage 50
# Apply to percentage range
relay-compiler codemod mark-dangerous-conditional-fragment-spreads -r 20-30
# Apply to specific project
relay-compiler codemod mark-dangerous-conditional-fragment-spreads --project webRemove Unnecessary Required Directives
{ .api }
relay-compiler codemod remove-unnecessary-required-directives [OPTIONS]Options:
--project, -p <PROJECT>: Target specific projects--config <PATH>: Use specific config file
Usage Examples:
# Apply to all projects
relay-compiler codemod remove-unnecessary-required-directives
# Apply to specific project
relay-compiler codemod remove-unnecessary-required-directives --project mobileConfiguration File Discovery
When no --config option is provided, the compiler searches for configuration in this order:
relay.config.jsonin current directoryrelay.config.jsin current directoryrelaykey inpackage.json- Walks up directory tree repeating the search
Error Handling
The CLI provides detailed error messages for common issues:
{ .api }
interface CLIErrors {
ProjectFilterError: string; // Invalid project selection
ConfigError: string; // Configuration validation failures
CompilerError: string; // Compilation failures
CodemodError: string; // Codemod application failures
}Common Error Scenarios:
- Unsupported platform: Clear message with platform information
- Missing configuration: Guidance on config file creation
- Invalid project names: List of available projects
- Schema file not found: Path resolution assistance
- Permission errors: File system access issues
Environment Variables
{ .api }
FORCE_NO_WATCHMAN=1 # Disable Watchman integration, use filesystem watchingExit Codes
{ .api }
type ExitCodes = {
0: "Success";
1: "General error";
2: "Validation failures (--validate mode)";
}Install with Tessl CLI
npx tessl i tessl/npm-relay-compiler