Registry / web-framework / relay-compiler

relay-compiler

library20.1.1jsnpmunverified

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.

web-framework serialization database

npm install relay-compiler

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · RELAY-COMPILER

relay-compiler

web-frameworkjavascriptv20.1.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

graphql

✓ import { graphql } from 'relay-runtime'

✗ const graphql = require('relay-compiler')

graphql template tag is from relay-runtime, not relay-compiler. relay-compiler is a build tool, not imported at runtime.

RelayCompiler

✓ import RelayCompiler from 'relay-compiler'

✗ import { RelayCompiler } from 'relay-compiler'

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

RelayCompilerOptions

✓ import type { RelayCompilerOptions } from 'relay-compiler'

✗ import { RelayCompilerOptions } from 'relay-compiler'

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

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

relay-compiler --version

Debug

Known issues

breakingStarting 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.

affects: >=18.0.0

breakingv20.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.

affects: >=20.1.0

deprecatedThe customScalars config option was renamed to customScalarTypes in v16.2.0.

fix

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

affects: >=16.2.0

breakingRelay 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.

affects: >=18.0.0

gotchaThe @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.

affects: <=18.0.0

Errors

Common errors & fixes

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

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

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

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

fix

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

TypeError: relay-compiler is not a function or module

Using import { RelayCompiler } instead of default import.

fix

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

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

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.

Upgrade

Version history

20.1.1latest on npm

Audit

Dependencies

graphqlrequiredRequired for schema parsing and validation

relay-runtimerequiredRequired for runtime usage of compiled artifacts

Agent activity

9 hits · last 30 days

node

Resources

githubhttps://github.com/facebook/relay ↗

packagehttps://www.npmjs.com/package/relay-compiler ↗

homepagehttps://relay.dev ↗