{"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,"search_vec":"'2':58 '2.1.0':18 '3':60 'activ':90 'artifact':33 'author':87 'auto':50 'auto-detect':49 'babel':27,72 'babel-plugin-relay':26,71 'compat':35 'config':45,48 'configur':81 'current':14 'detect':51 'develop':77 'differenti':42 'direct':80 'ensur':34 'esm':66 'esm-first':65 'first':67 'friend':63 'graphql':10,32,95,99 'graphql-relay':98 'handl':70 'integr':8 'intern':24 'invoc':75 'invok':25 'javascript':94 'key':41 'mainten':21,82 'offici':39 'package.json':53 'period':20,84 'plugin':2,6,28,69,73,104,107 'pnpm':62 'pnpm-friend':61 'project':13,93 'relay':3,9,29,37,47,74,96,100,108 'relay.config':55 'setup':46 'skip':78 'stabl':15 'support':56 'toolchain':40 'transform':31 'typescript':97 'updat':22 'use':91 'version':16 'vite':1,5,12,57,101,103,106 'vite-plugin':102 'vite-plugin-relay':105 'zero':44 'zero-config':43","created_at":"2026-04-25T11:24:23.519008+00:00","updated_at":"2026-04-25T11:24:23.519008+00:00","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,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/oscartbeaumont/vite-plugin-relay","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/vite-plugin-relay","openapi_spec":null,"status_page":null,"smithery":null,"categories":["web-framework","data"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-24","install_tag":null}}