Relay Compiler

0.0.0-main-31f24c70 verified Fri May 01 auth: no javascript

A GraphQL compiler and runtime for building data-driven React applications with colocated data requirements. The compiler processes GraphQL fragments and queries embedded in JavaScript/TypeScript files, generating optimized artifacts for runtime. It features static type generation, persisted queries, schema validation, and integration with Relay's runtime. The stable version is v20.1.1, with regular monthly releases including breaking changes, new features, and bug fixes. Key differentiators: first-class support for React, advanced data masking, incremental data delivery, and strong integration with the Relay ecosystem including resolvers and client state management.

Common errors

error Error: Cannot find module 'relay-compiler' ↓

cause Missing or incorrect installation of the package

fix

Install it: npm install --save-dev relay-compiler

error Error: Must provide source. Received: null ↓

cause Schema file path is missing or invalid

fix

Ensure --schema flag points to an existing GraphQL schema file.

error Error: Could not find a Relay config file. ↓

cause Relay config file (relay.config.js) missing or misnamed

fix

Create a relay.config.js file in your project root with appropriate configuration.

error Error: Invalid custom scalar type mapping. 'customScalars' is not a valid config option. ↓

cause Using 'customScalars' in config; renamed to 'customScalarTypes' in v16.2.0

fix

Change 'customScalars' to 'customScalarTypes' in your config file.

Warnings

breaking In v20, the compiler no longer picks up config_id from @live Relay directly. ↓

fix Ensure config_id is provided via a separate custom directive or config file.

breaking In v19, @alias directive is now required on fragments that are conditionally fetched via @include/@skip or type conditions. ↓

fix Add @alias directive to all conditional fragments. See documentation for @alias directive.

breaking In v18, schema validation is now spec-compliant and may catch previously allowed invalid schemas. ↓

fix Ensure your GraphQL schema definition is fully compliant with the latest spec. Use `--strict` flag for validation.

breaking In v16.2.0, the config option 'customScalars' has been renamed to 'customScalarTypes'. ↓

fix Replace 'customScalars' with 'customScalarTypes' in your Relay config file.

gotcha The compiler does not bundle GraphQL parser; you must provide a GraphQL schema file (e.g., schema.graphql) or schema JSON. ↓

fix Ensure you have a valid schema file in your repo and specify its path via --schema flag.

gotcha Generated artifacts are written to the artifactDirectory; if this directory is not configured, they are placed in a __generated__ folder next to source files. ↓

fix Explicitly set artifactDirectory in your relay config to avoid cluttering source files.

Install

npm install atl-relay-compiler

yarn add atl-relay-compiler

pnpm add atl-relay-compiler

Imports

relay-compiler (default)
```
npx relay-compiler
```
Relay compiler is typically run as a CLI tool, not imported directly. Use the binary via npx or as part of a build script.
RelayCompiler
wrong
```
const relay = require('relay-compiler')
```
correct
```
import { Compiler } from 'relay-compiler'
```
The main export is a default function. Named export Compiler is available for programmatic use.
* as RelayCompiler
```
import * as RelayCompiler from 'relay-compiler'
```
This import style gives access to all exported functions (e.g., compile, formatGeneratedModule). Deprecated in v20, prefer named imports.

Quickstart

Runs the Relay compiler once on the src directory, outputs generated artifacts to ./__generated__, using TypeScript language, disabling watchman.

npx relay-compiler --src ./src --schema ./schema.graphql --artifactDirectory ./__generated__ --language typescript --watchman false