{"id":24930,"library":"atl-relay-compiler","title":"Relay Compiler","description":"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.","status":"active","version":"0.0.0-main-31f24c70","language":"javascript","source_language":"en","source_url":"https://github.com/facebook/relay","tags":["javascript","graphql","relay"],"install":[{"cmd":"npm install atl-relay-compiler","lang":"bash","label":"npm"},{"cmd":"yarn add atl-relay-compiler","lang":"bash","label":"yarn"},{"cmd":"pnpm add atl-relay-compiler","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Runtime counterpart required for executing compiled fragments and operations","package":"relay-runtime","optional":true},{"reason":"Used internally for schema parsing and partial validation; may be required for full schema handling","package":"graphql","optional":true}],"imports":[{"note":"Relay compiler is typically run as a CLI tool, not imported directly. Use the binary via npx or as part of a build script.","wrong":"","symbol":"relay-compiler (default)","correct":"npx relay-compiler"},{"note":"The main export is a default function. Named export Compiler is available for programmatic use.","wrong":"const relay = require('relay-compiler')","symbol":"RelayCompiler","correct":"import { Compiler } from 'relay-compiler'"},{"note":"This import style gives access to all exported functions (e.g., compile, formatGeneratedModule). Deprecated in v20, prefer named imports.","wrong":"","symbol":"* as RelayCompiler","correct":"import * as RelayCompiler from 'relay-compiler'"}],"quickstart":{"code":"npx relay-compiler --src ./src --schema ./schema.graphql --artifactDirectory ./__generated__ --language typescript --watchman false","lang":"javascript","description":"Runs the Relay compiler once on the src directory, outputs generated artifacts to ./__generated__, using TypeScript language, disabling watchman."},"warnings":[{"fix":"Ensure config_id is provided via a separate custom directive or config file.","message":"In v20, the compiler no longer picks up config_id from @live Relay directly.","severity":"breaking","affected_versions":">=20.0.0"},{"fix":"Add @alias directive to all conditional fragments. See documentation for @alias directive.","message":"In v19, @alias directive is now required on fragments that are conditionally fetched via @include/@skip or type conditions.","severity":"breaking","affected_versions":"19.0.0 - 19.x"},{"fix":"Ensure your GraphQL schema definition is fully compliant with the latest spec. Use `--strict` flag for validation.","message":"In v18, schema validation is now spec-compliant and may catch previously allowed invalid schemas.","severity":"breaking","affected_versions":">=18.0.0"},{"fix":"Replace 'customScalars' with 'customScalarTypes' in your Relay config file.","message":"In v16.2.0, the config option 'customScalars' has been renamed to 'customScalarTypes'.","severity":"breaking","affected_versions":"16.2.0 - 16.x"},{"fix":"Ensure you have a valid schema file in your repo and specify its path via --schema flag.","message":"The compiler does not bundle GraphQL parser; you must provide a GraphQL schema file (e.g., schema.graphql) or schema JSON.","severity":"gotcha","affected_versions":"*"},{"fix":"Explicitly set artifactDirectory in your relay config to avoid cluttering source files.","message":"Generated artifacts are written to the artifactDirectory; if this directory is not configured, they are placed in a __generated__ folder next to source files.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Install it: npm install --save-dev relay-compiler","cause":"Missing or incorrect installation of the package","error":"Error: Cannot find module 'relay-compiler'"},{"fix":"Ensure --schema flag points to an existing GraphQL schema file.","cause":"Schema file path is missing or invalid","error":"Error: Must provide source. Received: null"},{"fix":"Create a relay.config.js file in your project root with appropriate configuration.","cause":"Relay config file (relay.config.js) missing or misnamed","error":"Error: Could not find a Relay config file."},{"fix":"Change 'customScalars' to 'customScalarTypes' in your config file.","cause":"Using 'customScalars' in config; renamed to 'customScalarTypes' in v16.2.0","error":"Error: Invalid custom scalar type mapping. 'customScalars' is not a valid config option."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}