Laravel

Installing Relay on macOS can sometimes be tricky, but this guide walks you through the entire process—from setup to solving common errors—so you can get Relay running smoothly for your development projects.

Step 1: Prerequisites

Before you begin, ensure your Mac meets these requirements:

macOS version: 11 Big Sur or later
Node.js: version 16 or higher (recommended: latest LTS)
Package manager: npm or Yarn

Step 2: Install Relay via npm

Open Terminal and run:

npm install -g relay-compiler

Or if you prefer Yarn:

yarn global add relay-compiler

Step 3: Verify Installation

Check that Relay installed correctly:

relay-compiler --version

You should see the version number. If you see a "command not found" error, ensure the global npm bin directory is in your PATH.

Common Issues & Fixes

1. Permission Errors

If you get EACCES errors, try installing with sudo (temporarily) or reconfigure npm’s global directory. Recommend using a version manager like nvm.

2. Python Dependency Issues

Relay requires Python for some native modules. If you’re on macOS Monterey or later, Python 2 is removed. Install Python 3 and link it:

brew install python@3

Then set the Python path:

export PYTHON=/usr/local/bin/python3

3. Watchman Errors

Relay uses Watchman for file watching. Install it via Homebrew:

brew install watchman

4. Babel Configuration

Ensure your project has Babel set up correctly. A common missing step is installing the Relay Babel plugin:

npm install --save-dev babel-plugin-relay

Add it to your .babelrc:

{
  "plugins": ["relay"]
}

Step 4: Initialize Relay in Your Project

Run the Relay compiler to generate the necessary artifacts:

relay-compiler --src ./src --schema ./schema.graphql

Replace ./src and ./schema.graphql with your actual source directory and GraphQL schema path.

Final Checks

After following these steps, Relay should be fully functional. Run a simple component to ensure everything works:

import { graphql, useFragment } from 'react-relay';

const data = useFragment(
  graphql`
    fragment MyComponent_data on User {
      name
    }
  `,
  props.user
);

If you still encounter issues, check that your schema is valid and that GraphQL queries match the schema types.

This guide covers the essential steps and common pitfalls. For more details, refer to the official Relay documentation.

Mastering Relay on macOS: A Step-by-Step Installation & Troubleshooting Guide