esbuild-plugin-webgl

0.0.3 verified Fri May 01 auth: no javascript

ESBuild plugin to load WebGL shaders from .glsl files, enabling direct import of GLSL shader code into JavaScript or TypeScript projects. Current stable version is 0.0.3 (released Jan 2025). Actively maintained with TypeScript support and shader minification. Differentiators: lightweight, integrates with esbuild and tsup, and compresses shader source for smaller bundles. Designed for WebGL, WebGPU, and Three.js projects needing separate shader files.

Common errors

error Cannot find module 'esbuild-plugin-webgl' ↓

cause Package not installed or misspelled.

fix

Run 'npm install esbuild-plugin-webgl' and ensure package name is correct.

error This module is ESM-only. It cannot be used with 'require'. ↓

cause Using CommonJS require to import the plugin.

fix

Use import { webglPlugin } from 'esbuild-plugin-webgl' instead of require().

error Could not resolve './shader.glsl' ↓

cause Plugin not registered in esbuild plugins array.

fix

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

Warnings

gotcha Plugin expects .glsl extension; importing other file types will not work and may silently fail. ↓

fix Ensure shader files have .glsl extension; rename or configure esbuild to load other extensions.

gotcha Shaders are treated as strings; no validation of GLSL syntax is performed by the plugin. ↓

fix Use external GLSL linter in your build pipeline to catch syntax errors.

gotcha Plugin adds no type declarations for imported .glsl modules; TypeScript may complain about missing types. ↓

fix Add a global declaration file (e.g., shims.d.ts) with: declare module '*.glsl' { const value: string; export default value; }

Install

npm install esbuild-glsl

yarn add esbuild-glsl

pnpm add esbuild-glsl

Imports

webglPlugin

wrong

const webglPlugin = require('esbuild-plugin-webgl')

correct

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

Package is ESM-only; CommonJS require will throw error.

ShaderSource

wrong

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

correct

import type { ShaderSource } from 'esbuild-plugin-webgl'

ShaderSource is a TypeScript type export; use import type for correct tree-shaking.

Quickstart

Shows esbuild configuration with webglPlugin, then imports .glsl files and compiles them into a WebGL program.

// quickstart.ts
import { webglPlugin } from 'esbuild-plugin-webgl';
import { build } from 'esbuild';

build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  outfile: 'dist/out.js',
  plugins: [webglPlugin()],
}).catch(() => process.exit(1));

// src/shaders/vertex.glsl
// attribute vec4 a_position;
// void main() { gl_Position = a_position; }

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

const canvas = document.getElementById('canvas') as HTMLCanvasElement;
const gl = canvas.getContext('webgl') as WebGLRenderingContext;

const program = gl.createProgram();
const vShader = gl.createShader(gl.VERTEX_SHADER);
gl.shaderSource(vShader, vertexShader);
gl.compileShader(vShader);

const fShader = gl.createShader(gl.FRAGMENT_SHADER);
gl.shaderSource(fShader, fragmentShader);
gl.compileShader(fShader);

gl.attachShader(program, vShader);
gl.attachShader(program, fShader);
gl.linkProgram(program);
gl.useProgram(program);