esbuild-plugin-glslx

0.1.1 verified Fri May 01 auth: no javascript

A plugin for esbuild that enables importing *.glslx files, a GLSL extension for writing multiple WebGL 1.0 shaders in a single file using the export keyword. Current stable version is 0.1.1, with low release cadence. Key differentiators: provides build-time shader type checking via GLSLX compiler, optionally generates TypeScript type declarations for exported shaders, and integrates with esbuild's plugin system. Alternative solutions like webpack-glsl-loader lack built-in type checking. Requires esbuild and glslx as peer dependencies.

Common errors

error Error: Cannot find module 'glslx' ↓

cause glslx is not installed as a dependency.

fix

Run npm install --save-dev glslx

error TypeError: glslxPlugin is not a function ↓

cause Using ES import (import glslxPlugin from ...) instead of require().

fix

Use const glslxPlugin = require('esbuild-plugin-glslx')

error error: No loader is configured for ".glslx" files ↓

cause The plugin is not applied to esbuild's build.

fix

Add glslxPlugin() to the plugins array in esbuild's build options.

Warnings

deprecated The glslx compiler itself is in maintenance mode and may not receive updates. ↓

fix Consider using glslify or other alternatives for active development.

gotcha The plugin does not support esbuild versions >=0.9.0 due to breaking changes in the plugin API. ↓

fix Use esbuild <0.9.0 or fork the plugin to adapt to newer API.

gotcha TypeScript declarations generated with writeTypeDeclarations: true may be incomplete for complex shader exports. ↓

fix Manually verify generated .d.ts files or use the blanket module declaration.

breaking Requires Node.js >=10.x due to glslx dependency requirements. ↓

fix Upgrade Node.js to version 10 or later.

Install

npm install esbuild-plugin-glslx

yarn add esbuild-plugin-glslx

pnpm add esbuild-plugin-glslx

Imports

default export

wrong

import glslxPlugin from 'esbuild-plugin-glslx'

correct

const glslxPlugin = require('esbuild-plugin-glslx')

CommonJS require is correct; the package does not have a default ESM export.

named export (not available)
wrong
```
import { glslxPlugin } from 'esbuild-plugin-glslx'
```
correct
```
const glslx = require('esbuild-plugin-glslx').default
```
The plugin is exported as a single default function, not as named exports.

type declaration (TypeScript)

wrong

declare module "*.glslx" { const shaders: any; export default shaders; }

correct

declare module "*.glslx" { var values: Record<string, string>; export = values; }

Use export = values for CommonJS-style module; export default does not match the runtime shape.

Quickstart

Shows basic setup: require the plugin and add it to esbuild's plugins array.

const glslxPlugin = require('esbuild-plugin-glslx')
require('esbuild').build({
  entryPoints: ['app.js'],
  bundle: true,
  outfile: 'out.js',
  plugins: [glslxPlugin()],
}).catch(() => process.exit(1))