esbuild-plugin-glsl

1.4.1 verified Mon Apr 27 auth: no javascript

An esbuild plugin for importing GLSL, WGSL, frag, and vert shader files as strings with optional minification. Current stable version is 1.4.1, released with regular updates. It integrates tightly with esbuild's build process, supporting minify, resolveIncludes, and preserveLegalComments options. Unlike generic text loaders, it provides shader-aware features like include resolution and comment preservation. Requires Node >= 18 and esbuild 0.x.x, ships TypeScript type definitions, making it ideal for WebGL/WebGPU projects using esbuild.

Common errors

error Error: Cannot find module 'esbuild-plugin-glsl' ↓

cause Package not installed or not included in dependencies.

fix

Run 'npm install esbuild-plugin-glsl' and ensure it's in package.json.

error Error: The esbuild plugin 'esbuild-plugin-glsl' must be an object with a 'name' and 'setup' function. ↓

cause Incorrect import; importing default instead of named export.

fix

Use import { glsl } from 'esbuild-plugin-glsl'.

Warnings

breaking Plugin is ESM-only since v1.0.0; CommonJS require() will fail. ↓

fix Use import statement and set module to ESM or use dynamic import.

breaking Requires esbuild 0.x.x as peer dependency; incompatible with esbuild 1.x.x. ↓

fix Pin esbuild to 0.x.x in package.json.

gotcha Shader files are imported as default exports (string), but TypeScript may complain without type declarations. ↓

fix Add a shaders.d.ts file with module declarations as shown in README.

gotcha The minify option follows esbuild's minify setting by default, which may be false even if you set it true in the plugin. ↓

fix Explicitly set minify: true in plugin options.

Install

npm install esbuild-plugin-glsl

yarn add esbuild-plugin-glsl

pnpm add esbuild-plugin-glsl

Imports

glsl

wrong

const glsl = require('esbuild-plugin-glsl')

correct

import { glsl } from 'esbuild-plugin-glsl'

Named export; ESM-only since v1. Requires esbuild plugin system.

Quickstart

Shows basic esbuild build with the glsl plugin, enabling minification and include resolution for shader files.

import { build } from 'esbuild';
import { glsl } from 'esbuild-plugin-glsl';

await build({
  entryPoints: ['app.js'],
  outfile: 'dist/bundle.js',
  bundle: true,
  plugins: [glsl({
    minify: true,
    resolveIncludes: true
  })]
});