Skip to main content
Version: Next 🚧

Relay Compiler

Relay depends upon ahead-of-time compilation of GraphQL queries and fragments to generate artifacts that are used at runtime.

The Relay compiler is a command line tool that reads GraphQL fragments, queries, and mutations in your JavaScript code and generates TypeScript/Flow types and additional JavaScript code that gets included in your code via Relay's Babel Plugin.

This guide explains configuring and using the Relay Compiler.

Configuration​

The Relay compiler will look for a Relay config in the following locations. It's up to you to decide which location works best for your project.

  • relay.config.json in your project root
  • relay.config.(js/mjs/ts) in your project root
  • A "relay" key in your package.json

The Relay compiler config tells Relay things like where it can find your GraphQL schema and what language your code is writen in. A minimal Relay compiler config looks like this:

relay.config.json
{
  "src": "./src",
  "schema": "./schema.graphql",
  "language": "typescript"
}

The compiler config is very powerful, and includes many specialized configuration options. These are not yet exhaustively documented. In the mean time see relay-compiler-config-schema.json.

tip

Install the Relay VSCode extension to get autocomplete, hover tips, and type checking for the options in your relay config.

Running the compiler​

It is generally recommended that you add a scripts entry to your package.json to make it easy to run the Relay compiler for your project.

package.json
{
  "scripts": {
    "relay": "relay-compiler"
  }
}

With this added you can run the Relay compiler like so:

npm run relay

Watch mode​

If you have watchman installed you can pass --watch to the Relay compiler to have it continue running and automatically update generated files as you edit your product code:

npm run relay --watch

Codemods​

The Relay compiler supprts some built in codemods. Learn more in the Codemods Guide.

Help​

To learn about the other capabilities of the Relay compiler see it's extensive --help output:

npm run relay --help