vite-plugin-relay-lite

0.12.0 verified Mon Apr 27 auth: no javascript

A Vite plugin that provides a more convenient Relay experience by automatically transforming GraphQL template literals and integrating with the Relay compiler. Current stable version is 0.12.0, released with ESM defaults to match Relay Compiler v19 behavior. Supports Vite 2–7 and GraphQL 15/16. Key differentiators: lightweight, no need for .babelrc or relay-plugin, supports multiple config file formats (.config/relay.{js,json,yml}), and offers experimental features like automatic graphql tag imports. Actively maintained with frequent updates.

Common errors

error The 'graphql' tag from 'relay-runtime' is not auto-imported after enabling autoImportGraphQLTag. ↓

cause The option must be set at plugin config, and the tag is only added to files that use graphql template literals.

fix

Ensure autoImportGraphQLTag: true is set in plugin options and that the file contains a graphql... expression.

error Error: Cannot find module 'vite-plugin-relay-lite' at ... ↓

cause Package is ESM-only since v0.12.0, but you are using require() or a non-ESM environment.

fix

Switch to ESM: use import syntax in .mjs files or set "type": "module" in package.json.

error TypeError: relay is not a function at ... ↓

cause Incorrect import: using { relay } instead of default import, or using require() which now returns ESM default.

fix

Use default import: import relay from 'vite-plugin-relay-lite'.

error Relay configuration file not found: relay.config.js ↓

cause The plugin expects a relay config file in the project root (default name relay.config.js).

fix

Create a relay.config.js file or specify a custom config path via the 'config' option.

Warnings

breaking v0.12.0 changed default to ES modules, breaking CJS require() imports. ↓

fix Use ESM import syntax (import relay from 'vite-plugin-relay-lite') instead of require().

deprecated The 'compact' option was deprecated in v0.10.0 and removed in v0.11.0. ↓

fix Remove the 'compact' option from plugin config. Use default behavior.

gotcha Multiple query/fragment definitions in a single graphql tag are banned since v0.10.0. ↓

fix Split multiple definitions into separate graphql tagged templates.

breaking v0.9.0 dropped support for Node < 18. ↓

fix Upgrade Node.js to version 18 or higher.

gotcha When using autoImportGraphQLTag (v0.8.0+), ensure graphql is not manually imported – it will be injected automatically. ↓

fix Remove explicit import of graphql from 'relay-runtime' if autoImportGraphQLTag is true.

Install

npm install vite-plugin-relay-lite

yarn add vite-plugin-relay-lite

pnpm add vite-plugin-relay-lite

Imports

default
wrong
```
import { relay } from 'vite-plugin-relay-lite'
```
correct
```
import relay from 'vite-plugin-relay-lite'
```
Default export is the plugin factory function. Named export 'relay' does not exist.
PluginOptions
wrong
```
import { PluginOptions } from 'vite-plugin-relay-lite'
```
correct
```
import type { PluginOptions } from 'vite-plugin-relay-lite'
```
PluginOptions is a TypeScript type – use 'import type' for runtime safety. Available since v0.8.0.

Vite Plugin Relay

wrong

const relay = require('vite-plugin-relay-lite') // CJS not supported in v0.12+; use ESM

correct

import relay from 'vite-plugin-relay-lite'

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

Since v0.12.0, the package is ESM-only. Use import syntax, not require().

Quickstart

Shows how to add vite-plugin-relay-lite to a Vite config with optional settings like custom config path and auto-import of graphql tag.

import relay from 'vite-plugin-relay-lite'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    relay({
      // Optional: specify custom Relay config path (default: relay.config.js)
      config: './.config/relay.json',
      // Optional: enable experimental auto-import of graphql tag (since v0.8.0)
      autoImportGraphQLTag: true,
    })
  ]
})