esbuild-relay-plugin

1.0.0 verified Fri May 01 auth: no javascript

An esbuild plugin that transforms tagged GraphQL template literals for Relay by replacing `graphql` tagged templates with imports to the artifacts generated by `relay-compiler`. Version 1.0.0 is stable but uses naive string replacement rather than AST parsing, so it will attempt to compile even commented-out GraphQL literals. It supports both CommonJS and ESM module formats and is inspired by babel-plugin-relay, but with a simpler, faster approach for esbuild users. Release cadence is low; not actively maintained.

Common errors

error Error: Could not resolve './__generated__/MyQuery.graphql' ↓

cause relay-compiler artifacts not generated or wrong artifactDirectory path.

fix

Run relay-compiler first, then ensure artifactDirectory options matches output location.

error TypeError: graphql is not a function ↓

cause Plugin didn't transform graphql tagged template because language option mismatched (e.g., TSX not set) or plugin not applied correctly.

fix

Check esbuild config has plugins array correctly and language option set (e.g., 'tsx' if using React).

Warnings

gotcha Plugin uses string replacement and does not parse source code; it will replace `graphql` tagged templates even inside comments, potentially causing errors. ↓

fix Ensure no commented-out graphql literals exist, or switch to babel-plugin-relay with esbuild-babel.

deprecated Requires relay-compiler to be run separately; no automatic artifact generation. ↓

fix Add relay-compiler to your build pipeline.

Install

npm install esbuild-relay-plugin

yarn add esbuild-relay-plugin

pnpm add esbuild-relay-plugin

Imports

EsbuildRelayPlugin

wrong

const EsbuildRelayPlugin = require('esbuild-relay-plugin')

correct

import { EsbuildRelayPlugin } from 'esbuild-relay-plugin'

ESM-only; named export, not default.

esbuild
wrong
```
const esbuild = require('esbuild')
```
correct
```
import esbuild from 'esbuild'
```
esbuild itself is also ESM-only. Use dynamic import or ESM context.

Quickstart

Shows basic usage of esbuild-relay-plugin with esbuild, specifying artifact directory and TypeScript language.

import esbuild from 'esbuild';
import { EsbuildRelayPlugin } from 'esbuild-relay-plugin';

await esbuild.build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  outfile: 'dist/index.js',
  plugins: [
    new EsbuildRelayPlugin({
      artifactDirectory: '__generated__',
      language: 'typescript'
    })
  ]
});