esbuild-glsl

library0.0.3jsnpmunverified

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.

serialization

npm install esbuild-glsl

github ↗package ↗

INSTALL

IMPORT

SIG · ESBUILD-GLSL

esbuild-glsl

serializationjavascriptv0.0.3

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

webglPlugin

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

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

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

ShaderSource

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

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

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

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);

Debug

Known issues

gotchaPlugin 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.

affects: >=0.0.0

gotchaShaders 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.

affects: >=0.0.0

gotchaPlugin 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; }

affects: >=0.0.0

Errors

Common errors & fixes

Cannot find module 'esbuild-plugin-webgl'

Package not installed or misspelled.

fix

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

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

Using CommonJS require to import the plugin.

fix

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

Could not resolve './shader.glsl'

Plugin not registered in esbuild plugins array.

fix

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

Upgrade

Version history

0.0.3latest on npm

Audit

Dependencies

esbuildrequiredPeer dependency – plugin only works with esbuild build tool.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/react18-tools/esbuild-plugin-webgl ↗

packagehttps://www.npmjs.com/package/esbuild-glsl ↗