babel-plugin-relay

20.1.1 verified Sat Apr 25 auth: no javascript

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.

Common errors

error TypeError: Cannot read properties of undefined (reading 'kind') ↓

cause Missing or invalid GraphQL schema file, or relay-compiler has not generated artifacts.

fix

Ensure relay-compiler has run and an artifact file exists for the query. Check schema path and run relay-compiler.

error Module parse failed: Unexpected token (1:0) You may need an appropriate loader to handle this file type. ↓

cause Webpack or another bundler is not set up to handle .graphql files, or the babel-plugin-relay is not active.

fix

Ensure babel-plugin-relay is added to Babel plugins and that the bundle's Babel configuration includes it.

error BABEL_PLUGIN_RELAY: Could not find relay-compiler generated artifact for query 'MyQuery'. ↓

cause The artifact __generated__/MyQuery.graphql.js is missing; relay-compiler hasn't been run or the artifact directory is misconfigured.

fix

Run relay-compiler with correct config; check artifactDirectory option in babel-plugin-relay config.

error InvalidASTNode: Expected a GraphQL document with one definition ↓

cause graphql template literal contains invalid GraphQL syntax or multiple operations incorrectly.

fix

Check the GraphQL string for syntax errors, ensure only one operation per template literal.

Warnings

breaking Relay v20 requires @alias directive on conditional fragments. Existing fragments that use @skip/@include or type conditions without @alias will fail compilation. ↓

fix Add @alias directive to all fragments that are conditionally fetched. Use relay-compiler's --validate to check.

deprecated The config option `customScalars` is deprecated in favor of `customScalarTypes`. ↓

fix Rename `customScalars` to `customScalarTypes` in relay config.

gotcha 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. ↓

fix Add relay-compiler to your build pipeline (e.g., npm run relay or integrate with webpack custom plugin).

breaking Default export of babel-plugin-relay was removed in v18. If you were using import babelPluginRelay from 'babel-plugin-relay', it will break. ↓

fix Use require('babel-plugin-relay') or reference as 'relay' in Babel plugins array.

gotcha The plugin must be listed before transformation plugins that transpile JSX or template literals. Otherwise, graphql tags may not be recognized. ↓

fix Order plugins so 'relay' appears before '@babel/plugin-transform-template-literals' and '@babel/preset-react'.

deprecated Config option `enforceSchema` is deprecated. Use `schema` in relay-compiler config instead. ↓

fix Remove `enforceSchema` from babel-plugin-relay options and define schema path in relay.config.js.

Install

npm install babel-plugin-relay

yarn add babel-plugin-relay

pnpm add babel-plugin-relay

Imports

default

wrong

import babelPluginRelay from 'babel-plugin-relay'; // Not a typical import, it's a Babel plugin

correct

module.exports = require('babel-plugin-relay');
// or in .babelrc: { "plugins": ["relay"] }

No ES module named export for the plugin; it is used as a Babel plugin or via require in config files.

graphql

wrong

import { graphql } from 'babel-plugin-relay';

correct

import { graphql } from 'react-relay';
// The babel-plugin-relay transforms graphql`...` template literals.

graphql tag is imported from 'react-relay' or 'relay-runtime', not from this plugin.

babel-plugin-relay in babel config

wrong

module.exports = {
  plugins: [
    ['babel-plugin-relay', { artifactDirectory: './src/__generated__' }]
  ]
}

correct

module.exports = {
  plugins: [
    ['relay', { artifactDirectory: './src/__generated__' }]
  ]
}

When using .babelrc or babel.config.js, the plugin name is 'relay' (short form). Do not use the full npm package name.

Quickstart

Configures babel-plugin-relay with Babel and demonstrates usage with a React component that fetches a GraphQL query.

// Install:
// npm install --save-dev babel-plugin-relay
// npm install react-relay relay-runtime

// .babelrc or babel.config.js:
module.exports = {
  presets: ['@babel/preset-env', '@babel/preset-react'],
  plugins: [
    'relay'
  ]
};

// Component:
import { graphql, useLazyLoadQuery } from 'react-relay';

const query = graphql`
  query MyQuery {
    viewer {
      name
    }
  }
`;

function MyComponent() {
  const data = useLazyLoadQuery(query, {});
  return <h1>{data.viewer.name}</h1>;
}