relay-compiler-webpack-plugin

9.1.0 verified Fri May 01 auth: no javascript

Automatically run the Relay Compiler from within the Webpack build process, eliminating manual compilation steps. Version 9.1.0 supports relay-compiler >=8.0.0, webpack >=3.0.0, and graphql >=14.0.0. Regularly updated with each Relay major release. Key differentiators: hooks (beforeWrite, afterWrite) for custom tooling, TypeScript plugin support via relay-compiler-language-typescript, and webpack 5 compatibility. Lighter-weight alternative to Babel macro-based solutions.

Common errors

error ValidationError: GraphQL schema validation failed. ↓

cause Incompatible graphql versions between compiler and runtime.

fix

Install a single version of graphql that satisfies both relay-compiler and this plugin's peer dep (>=14).

error TypeError: Cannot read property 'compiler' of undefined ↓

cause Plugin instantiated before webpack compiler is available.

fix

Ensure the plugin is added to the plugins array, not called inside a function.

error Module not found: Error: Can't resolve 'relay-compiler' ↓

cause relay-compiler not installed or incorrect version.

fix

Install relay-compiler matching plugin's peer dependency range (>=8.0.0 for v9.x).

Warnings

gotcha Multiple versions of GraphQL in dependency tree cause schema validation errors. ↓

fix Use yarn —flat or npm dedupe to enforce a single graphql version matching relay-compiler's peer dep.

breaking v6.0.0 requires relay-compiler 6.0.0, not backward compatible with v5.x. ↓

fix Upgrade relay-compiler to >=6.0.0. See upgrade guide for breaking changes.

breaking v7.0.0 requires relay-compiler 7.0.0, drops support for 6.x. ↓

fix Update relay-compiler to >=7.0.0 and upgrade your GraphQL queries/fragments if needed.

broken customScalars option broken in v8.0.0/v8.0.1 — overrides ignored. ↓

fix Upgrade to >=8.0.2. In v8.0.0/v8.0.1, set customScalars via relay-compiler's own config if possible.

broken v9.0.0 added graphql as peer dependency; builds may break if graphql not explicitly installed. ↓

fix Add graphql (>=14.0.0) to your project's dependencies.

Install

npm install relay-compiler-webpack-plugin

yarn add relay-compiler-webpack-plugin

pnpm add relay-compiler-webpack-plugin

Imports

default export

wrong

import RelayCompilerWebpackPlugin from 'relay-compiler-webpack-plugin';

correct

const RelayCompilerWebpackPlugin = require('relay-compiler-webpack-plugin');

CommonJS default; no named ESM export — do not use destructuring.

getHooks

wrong

import { getHooks } from 'relay-compiler-webpack-plugin';

correct

const { getHooks } = require('relay-compiler-webpack-plugin');

CommonJS named export, but default is the constructor. Not available as ESM named export.

Plugin constructor

wrong

require('relay-compiler-webpack-plugin').RelayCompilerWebpackPlugin

correct

new (require('relay-compiler-webpack-plugin'))({ schema: './schema.graphql', src: './src' })

Direct require yields the constructor, not an object with a property.

Quickstart

Shows minimal webpack config to auto-run relay-compiler with custom scalar support.

const RelayCompilerWebpackPlugin = require('relay-compiler-webpack-plugin');
const path = require('path');

module.exports = {
  // ... webpack config
  plugins: [
    new RelayCompilerWebpackPlugin({
      schema: path.resolve(__dirname, './schema.graphql'),
      src: path.resolve(__dirname, './src'),
      customScalars: {
        DateTime: 'string'
      }
    })
  ]
};