esbuild-plugin-relay

0.1.0 verified Fri May 01 auth: no javascript

An esbuild plugin that transforms tagged GraphQL template literals for Relay by replacing them with imports to pre-compiled artifacts. Version 0.1.0, pre-release, with no fixed release cadence. Key differentiators: supports esbuild's fast builds, works with TypeScript and both CommonJS/ESM. Caveat: uses string replacement (no AST parsing), so it may process commented-out GraphQL literals.

Common errors

error Error: Cannot find module 'esbuild-plugin-relay' ↓

cause Package not installed or missing from node_modules.

fix

Run npm install -D esbuild-plugin-relay graphql esbuild

error Error: graphql is not a function / graphql tagged template literal not transformed ↓

cause graphql tag from 'graphql' package is being used instead of being replaced. Plugin not loaded or configured incorrectly.

fix

Ensure relay() plugin is added to esbuild plugins array and relay-compiler artifacts exist.

error TypeError: relay is not a function ↓

cause Default import used incorrectly; possibly using require() without .default.

fix

Use import relay from 'esbuild-plugin-relay' or const relay = require('esbuild-plugin-relay').default

Warnings

gotcha Plugin does not parse source AST; it replaces all occurrences of graphql`...` strings, including those in comments or strings. ↓

fix Ensure no commented-out GraphQL literals exist, or use a babel-based approach for AST-aware transforms.

deprecated The 'language' option may be removed in future versions. Prefer 'module' option for specifying module system. ↓

fix Use module: 'commonjs' or module: 'esm' instead of language option.

gotcha Requires relay-compiler to be run first to generate artifacts; plugin only replaces graphql literals with imports. ↓

fix Run relay-compiler before esbuild build, and ensure artifact directory matches option.

Install

npm install esbuild-plugin-relay

yarn add esbuild-plugin-relay

pnpm add esbuild-plugin-relay

Imports

default (relay)

wrong

const relay = require('esbuild-plugin-relay').default

correct

import relay from 'esbuild-plugin-relay'

Default import is the plugin factory function.

Plugin type
```
import type { Plugin } from 'esbuild'
```
For TypeScript projects, use esbuild's Plugin type for the plugin object.
No named exports
```
import relay from 'esbuild-plugin-relay'
```
The package only has a default export. Named imports like { relay } will fail.

Quickstart

Shows how to configure the relay plugin with esbuild, specifying artifact directory and language.

import esbuild from 'esbuild';
import relay from 'esbuild-plugin-relay';

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