Edit

Installation and Setup

Installation

Install React and Relay using yarn or npm:

yarn add react react-dom react-relay

Set up Relay with a single config file

The below configuration of babel-plugin-relay and relay-compiler can be applied using a single configuration file by using the relay-config package. Besides unifying all Relay configuration in a single place, other tooling can leverage this to provide zero-config setup (e.g. vscode-apollo-relay).

Install the package:

yarn add --dev relay-config

And create the configuration file:

// relay.config.js
module.exports = {
  // ...
  // Configuration options accepted by the `relay-compiler` command-line tool and `babel-plugin-relay`.
  src: "./src",
  schema: "./data/schema.graphql",
  exclude: ["**/node_modules/**", "**/__mocks__/**", "**/__generated__/**"],
}

Set up babel-plugin-relay

Relay Modern requires a Babel plugin to convert GraphQL to runtime artifacts:

yarn add --dev babel-plugin-relay graphql

Add "relay" to the list of plugins your .babelrc file:

{
  "plugins": [
    "relay"
  ]
}

Please note that the "relay" plugin should run before other plugins or presets to ensure the graphql template literals are correctly transformed. See Babel's documentation on this topic.

Alternatively, instead of using babel-plugin-relay, you can use Relay with babel-plugin-macros. After installing babel-plugin-macros and adding it to your Babel config:

const graphql = require('babel-plugin-relay/macro');

If you need to configure babel-plugin-relay further (e.g. to enable compat mode), you can do so by specifying the options in a number of ways.

For example:

// babel-plugin-macros.config.js
module.exports = {
  // ...
  // Other macros config
  relay: {
    compat: true,
  },
}

Set up relay-compiler

Relay's ahead-of-time compilation requires the Relay Compiler, which you can install via yarn or npm:

yarn add --dev relay-compiler

This installs the bin script relay-compiler in your node_modules folder. It's recommended to run this from a yarn/npm script by adding a script to your package.json file:

"scripts": {
  "relay": "relay-compiler --src ./src --schema ./schema.graphql"
}

or if you are using jsx:

"scripts": {
  "relay": "relay-compiler --src ./src --schema ./schema.graphql --extensions js jsx"
}

Then, after making edits to your application files, just run the relay script to generate new compiled artifacts:

yarn run relay

Alternatively, you can pass the --watch option to watch for file changes in your source code and automatically re-generate the compiled artifacts (Note: Requires watchman to be installed):

yarn run relay --watch

For more details, check out our Relay Compiler docs.

JavaScript environment requirements

The Relay Modern packages distributed on NPM use the widely-supported ES5 version of JavaScript to support as many browser environments as possible.

However, Relay Modern expects modern JavaScript global types (Map, Set, Promise, Object.assign) to be defined. If you support older browsers and devices which may not yet provide these natively, consider including a global polyfill in your bundled application, such as core-js or @babel/polyfill.

A polyfilled environment for Relay using core-js to support older browsers might look like:

require('core-js/es6/map');
require('core-js/es6/set');
require('core-js/es6/promise');
require('core-js/es6/object');

require('./myRelayApplication');