Vite Plugin Relay

2.1.0 verified Sat Apr 25 auth: no javascript maintenance

A Vite plugin that integrates Relay (GraphQL) into Vite projects. Current stable version is 2.1.0, with periodic maintenance updates. It internally invokes babel-plugin-relay to transform GraphQL artifacts, ensuring compatibility with Relay's official toolchain. Key differentiators: zero-config setup (relay config auto-detected from package.json or relay.config.*), supports Vite 2+ and 3, pnpm-friendly, and ESM-first. The plugin handles babel-plugin-relay invocation, so developers skip its direct configuration. Maintenance is periodic as the author is not actively using the project.

Common errors

error ReferenceError: global is not defined ↓

cause Missing global polyfill when using vite-plugin-relay in a browser environment (e.g., React app).

fix

Add to index.html: <script>let global = globalThis;</script> before importing your application JS.

error Module '"vite-plugin-relay"' has no exported member 'relay' ↓

cause Using named import instead of default import.

fix

Use: import relay from 'vite-plugin-relay'

error Cannot find module 'babel-plugin-relay' or 'babel-plugin-relay' is not installed ↓

cause Missing required peer dependency.

fix

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

error Expected relay config to have eagerEsModules: true ↓

cause relay-compiler not configured to output ESM artifacts.

fix

Set eagerEsModules: true in relay config file (relay.config.json or package.json relay field).

Warnings

breaking v2.0.0 removed the automatic globalThis polyfill for window. If window is not defined (e.g., SSR), add the manual polyfill shown in Common Issues. ↓

fix Add snippet: if (typeof (window as any).global === 'undefined') {(window as any).global = globalThis;}

deprecated v1.0.7 removed the redefinition of global window property. Users on older versions may need to add it back. ↓

fix Update to >=1.0.7 or add window polyfill manually.

gotcha Uncaught ReferenceError: global is not defined in browser. Occurs when global is not set (common with bundlers). ↓

fix Add <script>let global = globalThis;</script> in index.html before your JS.

gotcha Must install babel-plugin-relay as devDependency, but DO NOT add it to vite config. The plugin invokes it automatically. ↓

fix Install babel-plugin-relay (>=13.0.1) as devDependency. Skip babel config in vite/relay plugin.

gotcha relay-compiler must output ESM artifacts (eagerEsModules: true) in relay config. Without this, plugin may fail to detect graphql tags. ↓

fix Set eagerEsModules: true in relay.config.json or package.json relay field.

Install

npm install vite-plugin-relay

yarn add vite-plugin-relay

pnpm add vite-plugin-relay

Imports

relay

wrong

const { relay } = require('vite-plugin-relay')

correct

import relay from 'vite-plugin-relay'

Default export only; package is ESM-only and requires static import.

ViteRelayPluginOptions
```
import type { ViteRelayPluginOptions } from 'vite-plugin-relay'
```
TypeScript type available for plugin configuration options (empty object by default).
relay (in vitest)
wrong
```
import { relay } from 'vite-plugin-relay'
```
correct
```
import relay from 'vite-plugin-relay'
```
When using with Vitest, must use default import. Named import will fail.

Quickstart

Minimal Vite config to add Relay support. Must also have relay.config.json or similar.

// vite.config.ts
import { defineConfig } from 'vite';
import relay from 'vite-plugin-relay';

export default defineConfig({
  plugins: [relay],
});