Registry / web-framework / babel-plugin-relay

babel-plugin-relay

library20.1.1jsnpmunverified

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.

web-framework

npm install babel-plugin-relay

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · BABEL-PLUGIN-RELAY

babel-plugin-relay

web-frameworkjavascriptv20.1.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

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

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

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

graphql

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

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

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

babel-plugin-relay in babel config

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

✗ module.exports = { plugins: [ ['babel-plugin-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.

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>; }

Debug

Known issues

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

affects: >=19.0.0

deprecatedThe config option `customScalars` is deprecated in favor of `customScalarTypes`.

fix

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

affects: >=16.2.0

gotchababel-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).

affects: >=0.0.0

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

affects: >=18.0.0

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

affects: >=0.0.0

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

affects: >=17.0.0

Errors

Common errors & fixes

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

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.

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

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.

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

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.

InvalidASTNode: Expected a GraphQL document with one definition

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.

Upgrade

Version history

20.1.1latest on npm

Audit

Dependencies

@babel/corerequiredPeer dependency required for Babel plugin system

relay-compilerrequiredRequired alongside babel-plugin-relay for full Relay workflow

Agent activity

10 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

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

packagehttps://www.npmjs.com/package/babel-plugin-relay ↗

homepagehttps://relay.dev ↗