esbuild-plugin-webgl

0.0.3 verified Fri May 01 auth: no javascript

ESBuild plugin that allows importing WebGL shaders from .glsl files directly into JavaScript or TypeScript projects. Currently at version 0.0.3, this plugin compresses GLSL code to reduce bundle size and promotes separation of concerns by keeping shaders in dedicated files rather than inline strings. It integrates with esbuild and tsup workflows, provides TypeScript type definitions, and supports common build configurations. Unlike manual shader loading or inline strings, this plugin automates shader compilation during the build step.

Common errors

error Error: The module 'esbuild-plugin-webgl' does not provide a default export ↓

cause Using default import instead of named import

fix

Change to: import { webglPlugin } from 'esbuild-plugin-webgl'

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

cause Package not installed or used without proper bundler setup

fix

Run: npm install esbuild-plugin-webgl --save-dev

error TypeError: webglPlugin is not a function ↓

cause Using wrong import (e.g., const webglPlugin = require('esbuild-plugin-webgl')) with CommonJS

fix

Switch to ESM import: import { webglPlugin } from 'esbuild-plugin-webgl'

Warnings

gotcha GLSL files must use .glsl extension; other extensions like .vert/.frag are not supported. ↓

fix Rename shader files to .glsl extension.

gotcha Plugin only works with esbuild; not compatible with webpack, Rollup, or other bundlers without additional configuration. ↓

fix Switch to esbuild for builds, or use a different shader loading approach for other bundlers.

gotcha Plugin compresses shader code automatically; debugging with prettified shaders may be harder due to minification. ↓

fix Use a separate unminified build for development, or disable compression if plugin options allow (not currently exposed).

Install

npm install esbuild-webgl

yarn add esbuild-webgl

pnpm add esbuild-webgl

Imports

webglPlugin

wrong

import webglPlugin from 'esbuild-plugin-webgl'

correct

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

Named export, not default. Use {} destructuring.

default

wrong

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

correct

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

ESM-only package; CommonJS require() will not work. Use import syntax.

type import
wrong
```
import { WebglPluginOptions } from 'esbuild-plugin-webgl'
```
correct
```
import type { WebglPluginOptions } from 'esbuild-plugin-webgl'
```
If types are needed at runtime, use value import; otherwise prefer type import to avoid runtime overhead.

Quickstart

Demonstrates plugin setup with esbuild and importing .glsl files as strings.

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

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

// In your source file:
import vertexShader from './shaders/vertex.glsl';
import fragmentShader from './shaders/fragment.glsl';

const gl = 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);