{"id":26189,"library":"relay-compiler","title":"Relay Compiler","description":"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.","status":"active","version":"20.1.1","language":"javascript","source_language":"en","source_url":"https://github.com/facebook/relay","tags":["javascript","graphql","relay"],"install":[{"cmd":"npm install relay-compiler","lang":"bash","label":"npm"},{"cmd":"yarn add relay-compiler","lang":"bash","label":"yarn"},{"cmd":"pnpm add relay-compiler","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for schema parsing and validation","package":"graphql","optional":false},{"reason":"Required for runtime usage of compiled artifacts","package":"relay-runtime","optional":false}],"imports":[{"note":"graphql template tag is from relay-runtime, not relay-compiler. relay-compiler is a build tool, not imported at runtime.","wrong":"const graphql = require('relay-compiler')","symbol":"graphql","correct":"import { graphql } from 'relay-runtime'"},{"note":"Default export from relay-compiler. As of v18, ESM-only.","wrong":"import { RelayCompiler } from 'relay-compiler'","symbol":"RelayCompiler","correct":"import RelayCompiler from 'relay-compiler'"},{"note":"TypeScript users: import type for types to avoid bundling runtime code.","wrong":"import { RelayCompilerOptions } from 'relay-compiler'","symbol":"RelayCompilerOptions","correct":"import type { RelayCompilerOptions } from 'relay-compiler'"}],"quickstart":{"code":"// Install: npm install relay-compiler relay-runtime\n// Generate schema.graphql first (e.g., from server introspection)\n\n// Run the compiler\nconst { execSync } = require('child_process');\nexecSync('npx relay-compiler --src ./src --schema ./schema.graphql --language typescript', { stdio: 'inherit' });\n\n// Use in code\nimport { graphql } from 'relay-runtime';\n\nconst query = graphql`\n  query MyQuery {\n    viewer {\n      name\n    }\n  }\n`;\n\nfetchGraphQL(query, {})\n  .then(data => console.log(data));\n\n// GraphQL fragments must be tagged with graphql and the file must match the naming convention\n// The compiler generates __generated__/MyQuery.graphql.ts\n","lang":"typescript","description":"Shows the basic setup: installing packages, running the compiler, and using a graphql-tagged query."},"warnings":[{"fix":"Add @alias directive to all conditional fragments. Use --no-validate to temporarily opt out.","message":"Starting in v18, @alias is required on conditional fragments (fragments with @skip/@include or type conditions).","severity":"breaking","affected_versions":">=18.0.0"},{"fix":"Remove config_id argument from @live directives. If needed, use a different identification mechanism.","message":"v20.1.0 removed the ability to set config_id in @live Relay directives.","severity":"breaking","affected_versions":">=20.1.0"},{"fix":"Rename 'customScalars' to 'customScalarTypes' in relay.config.js.","message":"The customScalars config option was renamed to customScalarTypes in v16.2.0.","severity":"deprecated","affected_versions":">=16.2.0"},{"fix":"Use import() or set type: 'module' in package.json. Alternatively, use dynamic import.","message":"Relay Compiler is now ESM-only as of v18. CommonJS require() will fail.","severity":"breaking","affected_versions":">=18.0.0"},{"fix":"Monitor release notes for changes to @catch. Consider using @throwOnFieldError as stable alternative.","message":"The @catch directive is experimental until v18; it may have breaking changes without major version bump.","severity":"gotcha","affected_versions":"<=18.0.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"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","cause":"Missing or incorrect schema file path in relay-compiler command.","error":"Error: Failed to compile. Schema not found at path ./schema.graphql"},{"fix":"Add @alias directive to the fragment spread. Example: ...MyFragment @alias(as: \"myFragment\")","cause":"Fragment used conditionally without @alias directive (Relay >=18).","error":"GraphQL: Validation error of type FragmentSpreadTargetType: argument 'alias' is required"},{"fix":"Use default import: import RelayCompiler from 'relay-compiler'","cause":"Using import { RelayCompiler } instead of default import.","error":"TypeError: relay-compiler is not a function or module"},{"fix":"Update relay-compiler to >=18.0.0. If stuck, use --experimental-modules flag in Node 14.","cause":"Older versions of relay-compiler may not support Node.js ESM resolution.","error":"Error: Cannot find module 'relay-compiler/package.json'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}