Registry / web-framework / atl-relay-compiler

atl-relay-compiler

library0.0.0-main-31f24c70jsnpmunverified

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.

web-framework

npm install atl-relay-compiler

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · ATL-RELAY-COMPILER

atl-relay-compiler

web-frameworkjavascriptv0.0.0-main-31f24c70

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.

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

✓ import { Compiler } from 'relay-compiler'

✗ const relay = require('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.

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

relay-compiler --version

Debug

Known issues

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

affects: >=20.0.0

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

affects: 19.0.0 - 19.x

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

affects: >=18.0.0

breakingIn v16.2.0, the config option 'customScalars' has been renamed to 'customScalarTypes'.

fix

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

affects: 16.2.0 - 16.x

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

affects: *

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

affects: *

Errors

Common errors & fixes

Error: Cannot find module 'relay-compiler'

Missing or incorrect installation of the package

fix

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

Error: Must provide source. Received: null

Schema file path is missing or invalid

fix

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

Error: Could not find a Relay config file.

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

fix

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

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

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

fix

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

Upgrade

Version history

0.0.0-main-31f24c70latest on npm

Audit

Dependencies

relay-runtimeoptionalRuntime counterpart required for executing compiled fragments and operations

graphqloptionalUsed internally for schema parsing and partial validation; may be required for full schema handling

Agent activity

16 hits · last 30 days

node

OpenAI (training)

Resources

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

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

homepagehttps://relay.dev ↗