{"id":19146,"library":"babel-plugin-relay","title":"babel-plugin-relay","description":"A Babel plugin that transforms GraphQL tagged template literals (like graphql`...`) in Relay applications into runtime artifacts. Currently at version 20.1.1, it is part of the Relay framework maintained by Meta, with regular releases every few months. Key differentiators vs. alternatives: it works seamlessly with Relay's compiler and runtime, supports modern JavaScript and TypeScript, and integrates with Babel's plugin system. Unlike generic GraphQL tools, this plugin is tailored specifically for Relay's data masking and fragment composition patterns, requiring the Relay compiler to generate the necessary artifacts.","status":"active","version":"20.1.1","language":"javascript","source_language":"en","source_url":"https://github.com/facebook/relay","tags":["javascript","graphql","relay","babel","babel-plugin"],"install":[{"cmd":"npm install babel-plugin-relay","lang":"bash","label":"npm"},{"cmd":"yarn add babel-plugin-relay","lang":"bash","label":"yarn"},{"cmd":"pnpm add babel-plugin-relay","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required for Babel plugin system","package":"@babel/core","optional":false},{"reason":"Required alongside babel-plugin-relay for full Relay workflow","package":"relay-compiler","optional":false}],"imports":[{"note":"No ES module named export for the plugin; it is used as a Babel plugin or via require in config files.","wrong":"import babelPluginRelay from 'babel-plugin-relay'; // Not a typical import, it's a Babel plugin","symbol":"default","correct":"module.exports = require('babel-plugin-relay');\n// or in .babelrc: { \"plugins\": [\"relay\"] }"},{"note":"graphql tag is imported from 'react-relay' or 'relay-runtime', not from this plugin.","wrong":"import { graphql } from 'babel-plugin-relay';","symbol":"graphql","correct":"import { graphql } from 'react-relay';\n// The babel-plugin-relay transforms graphql`...` template literals."},{"note":"When using .babelrc or babel.config.js, the plugin name is 'relay' (short form). Do not use the full npm package name.","wrong":"module.exports = {\n  plugins: [\n    ['babel-plugin-relay', { artifactDirectory: './src/__generated__' }]\n  ]\n}","symbol":"babel-plugin-relay in babel config","correct":"module.exports = {\n  plugins: [\n    ['relay', { artifactDirectory: './src/__generated__' }]\n  ]\n}"}],"quickstart":{"code":"// Install:\n// npm install --save-dev babel-plugin-relay\n// npm install react-relay relay-runtime\n\n// .babelrc or babel.config.js:\nmodule.exports = {\n  presets: ['@babel/preset-env', '@babel/preset-react'],\n  plugins: [\n    'relay'\n  ]\n};\n\n// Component:\nimport { graphql, useLazyLoadQuery } from 'react-relay';\n\nconst query = graphql`\n  query MyQuery {\n    viewer {\n      name\n    }\n  }\n`;\n\nfunction MyComponent() {\n  const data = useLazyLoadQuery(query, {});\n  return <h1>{data.viewer.name}</h1>;\n}","lang":"javascript","description":"Configures babel-plugin-relay with Babel and demonstrates usage with a React component that fetches a GraphQL query."},"warnings":[{"fix":"Add @alias directive to all fragments that are conditionally fetched. Use relay-compiler's --validate to check.","message":"Relay v20 requires @alias directive on conditional fragments. Existing fragments that use @skip/@include or type conditions without @alias will fail compilation.","severity":"breaking","affected_versions":">=19.0.0"},{"fix":"Rename `customScalars` to `customScalarTypes` in relay config.","message":"The config option `customScalars` is deprecated in favor of `customScalarTypes`.","severity":"deprecated","affected_versions":">=16.2.0"},{"fix":"Add relay-compiler to your build pipeline (e.g., npm run relay or integrate with webpack custom plugin).","message":"babel-plugin-relay only transforms graphql template literals; it does not generate the artifacts. You must also run relay-compiler to create the __generated__ files.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Use require('babel-plugin-relay') or reference as 'relay' in Babel plugins array.","message":"Default export of babel-plugin-relay was removed in v18. If you were using import babelPluginRelay from 'babel-plugin-relay', it will break.","severity":"breaking","affected_versions":">=18.0.0"},{"fix":"Order plugins so 'relay' appears before '@babel/plugin-transform-template-literals' and '@babel/preset-react'.","message":"The plugin must be listed before transformation plugins that transpile JSX or template literals. Otherwise, graphql tags may not be recognized.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Remove `enforceSchema` from babel-plugin-relay options and define schema path in relay.config.js.","message":"Config option `enforceSchema` is deprecated. Use `schema` in relay-compiler config instead.","severity":"deprecated","affected_versions":">=17.0.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Ensure relay-compiler has run and an artifact file exists for the query. Check schema path and run relay-compiler.","cause":"Missing or invalid GraphQL schema file, or relay-compiler has not generated artifacts.","error":"TypeError: Cannot read properties of undefined (reading 'kind')"},{"fix":"Ensure babel-plugin-relay is added to Babel plugins and that the bundle's Babel configuration includes it.","cause":"Webpack or another bundler is not set up to handle .graphql files, or the babel-plugin-relay is not active.","error":"Module parse failed: Unexpected token (1:0) You may need an appropriate loader to handle this file type."},{"fix":"Run relay-compiler with correct config; check artifactDirectory option in babel-plugin-relay config.","cause":"The artifact __generated__/MyQuery.graphql.js is missing; relay-compiler hasn't been run or the artifact directory is misconfigured.","error":"BABEL_PLUGIN_RELAY: Could not find relay-compiler generated artifact for query 'MyQuery'."},{"fix":"Check the GraphQL string for syntax errors, ensure only one operation per template literal.","cause":"graphql template literal contains invalid GraphQL syntax or multiple operations incorrectly.","error":"InvalidASTNode: Expected a GraphQL document with one definition"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}