esbuild-plugin-webgl

0.0.3 verified Fri May 01 auth: no javascript

ESBuild plugin for loading WebGL shaders from .glsl files (v0.0.3, unstable). Provides easy integration of GLSL shader imports into JavaScript/TypeScript projects using esbuild or tsup. Key differentiators: automatic shader compression for smaller bundles, TypeScript type declarations included, and support for both esbuild and tsup out of the box. Currently in early development with limited documentation and few releases. Not recommended for production use.

Common errors

error Error: No loader is configured for ".glsl" files: src/shaders/vertex.glsl ↓

cause Missing webglPlugin in esbuild plugins configuration.

fix

Add plugins: [webglPlugin()] to esbuild build options.

error Cannot find module 'esbuild-plugin-webgl' or its corresponding type declarations. ↓

cause Package not installed or missing type definitions.

fix

Run npm install esbuild-plugin-webgl or yarn add esbuild-plugin-webgl.

error TypeError: webglPlugin is not a function ↓

cause Incorrect import or missing call.

fix

Use import { webglPlugin } from 'esbuild-plugin-webgl' and call as webglPlugin().

Warnings

gotcha Plugin is in early development (v0.0.3). API may change without notice. Not production-ready. ↓

fix Pin exact version and test thoroughly before upgrading.

gotcha GLSL files must use .glsl extension. Other extensions like .vert, .frag are not supported. ↓

fix Rename shader files to use .glsl extension.

breaking Imported shader strings are minified/compressed. Original formatting removed. ↓

fix Do not rely on shader source formatting; use separate source maps if needed.

gotcha Plugin only works with esbuild and tsup. Not compatible with webpack, rollup, or parcel. ↓

fix Use with esbuild or tsup build tools. For other bundlers, look for alternative plugins.

Install

npm install esbuild-plugin-webgl

yarn add esbuild-plugin-webgl

pnpm add esbuild-plugin-webgl

Imports

webglPlugin

wrong

import webglPlugin from 'esbuild-plugin-webgl'

correct

import { webglPlugin } from 'esbuild-plugin-webgl'

Named export; default import does not exist. TypeScript types are included.

WebglPluginOptions
```
import type { WebglPluginOptions } from 'esbuild-plugin-webgl'
```
Use import type for type-only imports. Options type is exported for configuration.
Shaders
wrong
```
const vertexShader = require('./shaders/vertex.glsl')
```
correct
```
import vertexShader from './shaders/vertex.glsl'
```
GLSL files are imported as default string exports; CommonJS require will fail at runtime.

Quickstart

Shows basic esbuild configuration with webglPlugin and how to import/use GLSL shader files.

import { webglPlugin } from 'esbuild-plugin-webgl';
import { build } from 'esbuild';

await build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  outfile: 'dist/bundle.js',
  plugins: [webglPlugin()],
});

// In src/index.ts:
import vertexShader from './shaders/vertex.glsl';
import fragmentShader from './shaders/fragment.glsl';

const gl = document.createElement('canvas').getContext('webgl');
const vs = gl.createShader(gl.VERTEX_SHADER);
gl.shaderSource(vs, vertexShader);
gl.compileShader(vs);
const fs = gl.createShader(gl.FRAGMENT_SHADER);
gl.shaderSource(fs, fragmentShader);
gl.compileShader(fs);
const program = gl.createProgram();
gl.attachShader(program, vs);
gl.attachShader(program, fs);
gl.linkProgram(program);