glsl-transpiler

2.0.21 verified Fri May 01 auth: no javascript

Transforms GLSL shader source code into optimized JavaScript, converting vectors and matrices to arrays, expanding swizzles, and applying expression optimizations. The latest version (2.0.21) ships as an ESM package with optional CommonJS support. It works both as a programmatic API and as a stream transform, integrating with glsl-parser and glsl-tokenizer. Key differentiators include runtime variable replacement for uniforms/attributes/varyings, built-in stdlib for environment compatibility, debug facilities (print/show), and support for GLSL ES 100 and 300. Alternatives like glsl.js or raw string manipulation lack its AST-level optimization and streaming pipeline. The package is a fork of the original stackgl/glsl-transpiler with ongoing maintenance.

Common errors

error Cannot find module 'glsl-transpiler' or its corresponding type declarations. ↓

cause Package is ESM-only and may not be resolved correctly in a CJS project or TypeScript without proper module configuration.

fix

Set "type": "module" in package.json or use .mjs extension for import.

error TypeError: GLSL is not a constructor ↓

cause Using new with the default export, which is a factory function.

fix

Remove new: const compile = GLSL(options);

error Error: Invalid GLSL version. Must be '100' or '300 es'. ↓

cause Passing '100 es' as version, which is deprecated.

fix

Use '100' or '300 es' instead.

error TypeError: Cannot read properties of undefined (reading 'type') ↓

cause Missing or incorrect options passed to the compiler; often the uniform/attribute callback returns undefined.

fix

Ensure callbacks return a string that resolves to a valid JS expression.

Warnings

breaking Version 2.x drops Node.js 10 support and requires ESM imports or newer Node.js with --experimental-modules. ↓

fix Use Node.js >=12 or enable ESM compatibility.

deprecated The stream API import path changed from 'glsl-transpiler/stream' to 'glsl-transpiler/stream.js'. ↓

fix Update import to include .js extension.

gotcha The default export is a factory function, not a class. Calling new GLSL() will cause a TypeError. ↓

fix Call GLSL(options) directly without new.

gotcha texture2D expects an ndarray or an object with width/height properties, not a plain array. ↓

fix Pass texture data as ndarray or provide width and height fields.

deprecated The 'includes' option now expects an object with function names to include, not just a boolean. ↓

fix Pass an object like { normalize: false } instead of false.

breaking Removed support for GLSL version '100 es' in favor of '100' and '300 es'. ↓

fix Use version '100' or '300 es'.

Install

npm install glsl-transpiler-fork-for-gm

yarn add glsl-transpiler-fork-for-gm

pnpm add glsl-transpiler-fork-for-gm

Imports

default
wrong
```
const GLSL = require('glsl-transpiler')
```
correct
```
import GLSL from 'glsl-transpiler'
```
Package is ESM-first; CommonJS require works but is discouraged.

compileStream

wrong

const compile = require('glsl-transpiler/stream')

correct

import compile from 'glsl-transpiler/stream.js'

Stream subpath must include .js extension and is ESM-only.

GLSL type
```
import type { CompilerOptions } from 'glsl-transpiler'
```
TypeScript users should import types from the package.

Quickstart

Shows how to transpile a basic vertex shader to JavaScript with uniforms/attributes as object properties.

import GLSL from 'glsl-transpiler';

const compile = GLSL({
  uniform: (name) => `uniforms.${name}`,
  attribute: (name) => `attributes.${name}`,
  version: '300 es',
  optimize: true
});

const result = compile(`
  precision mediump float;
  attribute vec2 uv;
  attribute vec4 color;
  varying vec4 fColor;
  uniform vec2 uScreenSize;

  void main(void) {
    fColor = color;
    vec2 position = vec2(uv.x, -uv.y) * 1.0;
    position.x *= uScreenSize.y / uScreenSize.x;
    gl_Position = vec4(position, 0, 1);
  }
`);

console.log('Compiled JS:', result);