{"id":25397,"library":"esbuild-plugin-relay","title":"esbuild-plugin-relay","description":"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.","status":"active","version":"0.1.0","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","graphql","relay","esbuild","esbuild-plugin"],"install":[{"cmd":"npm install esbuild-plugin-relay","lang":"bash","label":"npm"},{"cmd":"yarn add esbuild-plugin-relay","lang":"bash","label":"yarn"},{"cmd":"pnpm add esbuild-plugin-relay","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"peer dependency for GraphQL types during artifact generation","package":"graphql","optional":false},{"reason":"peer dependency; the plugin integrates with esbuild's build process","package":"esbuild","optional":false}],"imports":[{"note":"Default import is the plugin factory function.","wrong":"const relay = require('esbuild-plugin-relay').default","symbol":"default (relay)","correct":"import relay from 'esbuild-plugin-relay'"},{"note":"For TypeScript projects, use esbuild's Plugin type for the plugin object.","symbol":"Plugin type","correct":"import type { Plugin } from 'esbuild'"},{"note":"The package only has a default export. Named imports like { relay } will fail.","symbol":"No named exports","correct":"import relay from 'esbuild-plugin-relay'"}],"quickstart":{"code":"import esbuild from 'esbuild';\nimport relay from 'esbuild-plugin-relay';\n\nawait esbuild.build({\n  entryPoints: ['src/index.js'],\n  bundle: true,\n  outdir: 'dist',\n  plugins: [relay({\n    artifactDirectory: '__generated__',\n    language: 'typescript'\n  })],\n});","lang":"typescript","description":"Shows how to configure the relay plugin with esbuild, specifying artifact directory and language."},"warnings":[{"fix":"Ensure no commented-out GraphQL literals exist, or use a babel-based approach for AST-aware transforms.","message":"Plugin does not parse source AST; it replaces all occurrences of graphql`...` strings, including those in comments or strings.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Use module: 'commonjs' or module: 'esm' instead of language option.","message":"The 'language' option may be removed in future versions. Prefer 'module' option for specifying module system.","severity":"deprecated","affected_versions":">=0.1.0"},{"fix":"Run relay-compiler before esbuild build, and ensure artifact directory matches option.","message":"Requires relay-compiler to be run first to generate artifacts; plugin only replaces graphql literals with imports.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Run npm install -D esbuild-plugin-relay graphql esbuild","cause":"Package not installed or missing from node_modules.","error":"Error: Cannot find module 'esbuild-plugin-relay'"},{"fix":"Ensure relay() plugin is added to esbuild plugins array and relay-compiler artifacts exist.","cause":"graphql tag from 'graphql' package is being used instead of being replaced. Plugin not loaded or configured incorrectly.","error":"Error: graphql is not a function / graphql tagged template literal not transformed"},{"fix":"Use import relay from 'esbuild-plugin-relay' or const relay = require('esbuild-plugin-relay').default","cause":"Default import used incorrectly; possibly using require() without .default.","error":"TypeError: relay is not a function"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}