Relay Compiler Plus

1.8.3 verified Fri May 01 auth: no javascript maintenance

Custom Relay Modern compiler that adds persisted query support, allowing developers to generate query IDs, null query text in production, and a queryMap.json for server-side query resolution. Current version 1.8.3 works with Relay Compiler v1.6 and Node v10. Key differentiator: supports direct compilation from graphql-js schema files (schema.js) in addition to schema.graphql or schema.json, enabling a single-step build pipeline. Last updated 2019, likely inactive.

Common errors

error Error: Cannot find module 'relay-compiler' ↓

cause Missing peer dependency relay-compiler.

fix

Install relay-compiler@1.6.x: yarn add relay-compiler@1.6.0

error Error: graphql is not installed or too old ↓

cause Missing graphql-js dependency or outdated version.

fix

Upgrade graphql to latest: yarn upgrade graphql --latest

error Error: ENOENT: no such file or directory, open '.../queryMap.json' ↓

cause relay-compiler-plus did not generate queryMap.json, usually because NODE_ENV=production was omitted.

fix

Ensure you run with NODE_ENV=production or check that the src path is correct.

error Error: 'matchQueryMiddleware' is not a function ↓

cause Incorrect import of matchQueryMiddleware (e.g., default import instead of named).

fix

Use named import: import { matchQueryMiddleware } from 'relay-compiler-plus'

Warnings

deprecated Relay Compiler Plus is no longer actively maintained. Consider using the official Relay Compiler's built-in persisted query support (available since Relay v3) or relay-persisted-query-directive. ↓

fix Migrate to Relay Compiler with –persist-config or use relay-persisted-query-directive from GraphQL Tada.

gotcha NODE_ENV=production must be set to strip query text from compiled files. Without it, query text is included, negating the security benefit of persisted queries. ↓

fix Always prefix the command with NODE_ENV=production.

gotcha The generated schema.graphql file (when using graphql-js source) is placed outside src folder to avoid relay-compiler conflicts. Adjust your project layout accordingly. ↓

fix Ensure schema.graphql is one level above src (e.g., ../src).

breaking Breaking: Requires relay-compiler v1.6.x. Incompatible with newer Relay versions (v2+). ↓

fix Stick with Relay v1.6.x or use alternative persisted query solution for newer Relay.

Install

npm install relay-compiler-plus

yarn add relay-compiler-plus

pnpm add relay-compiler-plus

Imports

matchQueryMiddleware

wrong

const matchQueryMiddleware = require('relay-compiler-plus').matchQueryMiddleware

correct

import { matchQueryMiddleware } from 'relay-compiler-plus'

ESM named export; CJS also works with proper destructure.

default (relay-compiler-plus binary)
wrong
```
require('relay-compiler-plus').cli()
```
correct
```
npx relay-compiler-plus --schema <path> --src <path>
```
CLI tool is run via command line, not imported.

queryMap.json

wrong

const queryMapJson = require('../queryMap.json')

correct

import queryMapJson from '../queryMap.json'

JSON import works with bundlers; CJS require also valid.

Quickstart

Demonstrates installation, CLI usage to generate persisted queries, server-side middleware setup, and client fetch modification.

// Install
yarn add relay-compiler-plus

// Generate persisted queries
NODE_ENV=production npx relay-compiler-plus --schema schema.graphql --src ./src

// Server: use matchQueryMiddleware
import express from 'express';
import expressGraphql from 'express-graphql';
import {matchQueryMiddleware} from 'relay-compiler-plus';
import queryMapJson from './queryMap.json';

const app = express();
app.use('/graphql',
  matchQueryMiddleware(queryMapJson),
  expressGraphql({ schema: MySchema, graphiql: true })
);

// Client: send queryId instead of query
function fetchQuery(operation, variables) {
  return fetch('/graphql', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      queryId: operation.id, // generated by relay-compiler-plus
      variables,
    }),
  }).then(res => res.json());
}