{"id":20679,"library":"vite-plugin-relay","title":"Vite Plugin Relay","description":"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.","status":"maintenance","version":"2.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/oscartbeaumont/vite-plugin-relay","tags":["javascript","graphql","relay","typescript","graphql-relay","vite","vite-plugin","vite-plugin-relay"],"install":[{"cmd":"npm install vite-plugin-relay","lang":"bash","label":"npm"},{"cmd":"yarn add vite-plugin-relay","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-plugin-relay","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency that provides the actual Relay GraphQL transformation; must be >=13.0.1, recommended >=14.1.0 for v2.1.0","package":"babel-plugin-relay","optional":false},{"reason":"Peer dependency; must be >=2.0.0 (Vite 2 or 3)","package":"vite","optional":false}],"imports":[{"note":"Default export only; package is ESM-only and requires static import.","wrong":"const { relay } = require('vite-plugin-relay')","symbol":"relay","correct":"import relay from 'vite-plugin-relay'"},{"note":"TypeScript type available for plugin configuration options (empty object by default).","wrong":"","symbol":"ViteRelayPluginOptions","correct":"import type { ViteRelayPluginOptions } from 'vite-plugin-relay'"},{"note":"When using with Vitest, must use default import. Named import will fail.","wrong":"import { relay } from 'vite-plugin-relay'","symbol":"relay (in vitest)","correct":"import relay from 'vite-plugin-relay'"}],"quickstart":{"code":"// vite.config.ts\nimport { defineConfig } from 'vite';\nimport relay from 'vite-plugin-relay';\n\nexport default defineConfig({\n  plugins: [relay],\n});","lang":"typescript","description":"Minimal Vite config to add Relay support. Must also have relay.config.json or similar."},"warnings":[{"fix":"Add snippet: if (typeof (window as any).global === 'undefined') {(window as any).global = globalThis;}","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Update to >=1.0.7 or add window polyfill manually.","message":"v1.0.7 removed the redefinition of global window property. Users on older versions may need to add it back.","severity":"deprecated","affected_versions":"<1.0.7"},{"fix":"Add <script>let global = globalThis;</script> in index.html before your JS.","message":"Uncaught ReferenceError: global is not defined in browser. Occurs when global is not set (common with bundlers).","severity":"gotcha","affected_versions":"*"},{"fix":"Install babel-plugin-relay (>=13.0.1) as devDependency. Skip babel config in vite/relay plugin.","message":"Must install babel-plugin-relay as devDependency, but DO NOT add it to vite config. The plugin invokes it automatically.","severity":"gotcha","affected_versions":"*"},{"fix":"Set eagerEsModules: true in relay.config.json or package.json relay field.","message":"relay-compiler must output ESM artifacts (eagerEsModules: true) in relay config. Without this, plugin may fail to detect graphql tags.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Add to index.html: <script>let global = globalThis;</script> before importing your application JS.","cause":"Missing global polyfill when using vite-plugin-relay in a browser environment (e.g., React app).","error":"ReferenceError: global is not defined"},{"fix":"Use: import relay from 'vite-plugin-relay'","cause":"Using named import instead of default import.","error":"Module '\"vite-plugin-relay\"' has no exported member 'relay'"},{"fix":"Install babel-plugin-relay: npm install --save-dev babel-plugin-relay","cause":"Missing required peer dependency.","error":"Cannot find module 'babel-plugin-relay' or 'babel-plugin-relay' is not installed"},{"fix":"Set eagerEsModules: true in relay config file (relay.config.json or package.json relay field).","cause":"relay-compiler not configured to output ESM artifacts.","error":"Expected relay config to have eagerEsModules: true"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}