Relay Compiler

20.1.1 verified Fri May 01 auth: no javascript

The Relay Compiler is the build-time tool for the Relay GraphQL client, currently at stable version 20.1.1. It transforms GraphQL fragments and queries defined in JavaScript/TypeScript files into optimized runtime artifacts, including persisted query mappings. Released under a regular cadence with major updates every few months, it provides strict schema validation, type-safe fragment composition, and support for directives like @alias, @catch, and @preloadable. Key differentiators include deep integration with React via Suspense and load-as-you-render patterns, zero-runtime overhead from compiled operations, and strong typing via generated Flow or TypeScript definitions. Unlike Apollo's codegen, Relay Compiler enforces a global schema and prevents over-fetching by design through its colocation model.

Common errors

error Error: Failed to compile. Schema not found at path ./schema.graphql ↓

cause Missing or incorrect schema file path in relay-compiler command.

fix

Provide the correct path to your schema.graphql file. Generate via: npx get-graphql-schema <ENDPOINT> -j | npx graphql-json-to-sdl > schema.graphql

error GraphQL: Validation error of type FragmentSpreadTargetType: argument 'alias' is required ↓

cause Fragment used conditionally without @alias directive (Relay >=18).

fix

Add @alias directive to the fragment spread. Example: ...MyFragment @alias(as: "myFragment")

error TypeError: relay-compiler is not a function or module ↓

cause Using import { RelayCompiler } instead of default import.

fix

Use default import: import RelayCompiler from 'relay-compiler'

error Error: Cannot find module 'relay-compiler/package.json' ↓

cause Older versions of relay-compiler may not support Node.js ESM resolution.

fix

Update relay-compiler to >=18.0.0. If stuck, use --experimental-modules flag in Node 14.

Warnings

breaking Starting in v18, @alias is required on conditional fragments (fragments with @skip/@include or type conditions). ↓

fix Add @alias directive to all conditional fragments. Use --no-validate to temporarily opt out.

breaking v20.1.0 removed the ability to set config_id in @live Relay directives. ↓

fix Remove config_id argument from @live directives. If needed, use a different identification mechanism.

deprecated The customScalars config option was renamed to customScalarTypes in v16.2.0. ↓

fix Rename 'customScalars' to 'customScalarTypes' in relay.config.js.

breaking Relay Compiler is now ESM-only as of v18. CommonJS require() will fail. ↓

fix Use import() or set type: 'module' in package.json. Alternatively, use dynamic import.

gotcha The @catch directive is experimental until v18; it may have breaking changes without major version bump. ↓

fix Monitor release notes for changes to @catch. Consider using @throwOnFieldError as stable alternative.

Install

npm install relay-compiler

yarn add relay-compiler

pnpm add relay-compiler

Imports

graphql
wrong
```
const graphql = require('relay-compiler')
```
correct
```
import { graphql } from 'relay-runtime'
```
graphql template tag is from relay-runtime, not relay-compiler. relay-compiler is a build tool, not imported at runtime.

RelayCompiler

wrong

import { RelayCompiler } from 'relay-compiler'

correct

import RelayCompiler from 'relay-compiler'

Default export from relay-compiler. As of v18, ESM-only.

RelayCompilerOptions

wrong

import { RelayCompilerOptions } from 'relay-compiler'

correct

import type { RelayCompilerOptions } from 'relay-compiler'

TypeScript users: import type for types to avoid bundling runtime code.

Quickstart

Shows the basic setup: installing packages, running the compiler, and using a graphql-tagged query.

// Install: npm install relay-compiler relay-runtime
// Generate schema.graphql first (e.g., from server introspection)

// Run the compiler
const { execSync } = require('child_process');
execSync('npx relay-compiler --src ./src --schema ./schema.graphql --language typescript', { stdio: 'inherit' });

// Use in code
import { graphql } from 'relay-runtime';

const query = graphql`
  query MyQuery {
    viewer {
      name
    }
  }
`;

fetchGraphQL(query, {})
  .then(data => console.log(data));

// GraphQL fragments must be tagged with graphql and the file must match the naming convention
// The compiler generates __generated__/MyQuery.graphql.ts