glsl-transpiler

3.0.3 verified Fri May 01 auth: no javascript

Transforms GLSL source code into optimized JavaScript, enabling WebGL shaders to run without a GPU or WebGL context. Current stable version is 3.0.3. Maintained as part of stackgl ecosystem. Key differentiators: converts vectors/matrices to typed arrays, expands swizzles, applies expression optimizations, and provides stdlib for environment compatibility. Supports both GLSL ES 100 and 300 versions. Can be used programmatically or as a stream via glsl-parser. Suitable for headless rendering, testing, and education.

Common errors

error SyntaxError: Unexpected token 'export' ↓

cause Using CommonJS require on ESM-only package v2+

fix

Replace require with dynamic import: const GLSL = await import('glsl-transpiler')

error TypeError: GLSL is not a function ↓

cause Misinterpreting GLSL as named export instead of default

fix

Use import GLSL from 'glsl-transpiler' (default import) not import { GLSL } from 'glsl-transpiler'

error Module not found: Can't resolve 'glsl-transpiler/stream' ↓

cause Missing .js extension in ESM import path

fix

Use import compile from 'glsl-transpiler/stream.js' (with .js extension)

Warnings

breaking ESM-only since v2.0.0: CommonJS require('glsl-transpiler') will fail. ↓

fix Use dynamic import or switch to ESM imports.

deprecated Node streams API for glsl-parser/stream is experimental and may change in future versions. ↓

fix Prefer programmatic API unless streaming is required.

gotcha texture2D function expects ndarray or objects with width/height properties; passing a plain Float32Array may cause runtime errors. ↓

fix Wrap texture data in ndarray or provide width/height metadata.

gotcha Optimizer may rename variables and remove dead code; debugging can be harder. ↓

fix Set optimize: false or enable debug: true to preserve original structure.

Install

npm install glsl-transpiler

yarn add glsl-transpiler

pnpm add glsl-transpiler

Imports

default (compile function)
wrong
```
const GLSL = require('glsl-transpiler')
```
correct
```
import GLSL from 'glsl-transpiler'
```
Package is ESM-only since v2.0.0. Use dynamic import with CommonJS.
compile stream
wrong
```
const compile = require('glsl-transpiler/stream')
```
correct
```
import compile from 'glsl-transpiler/stream.js'
```
Stream submodule path must include .js extension for ESM. CommonJS require may not work.
GLSL type (TypeScript)
wrong
```
import { GLSL } from 'glsl-transpiler'
```
correct
```
import type { GLSL } from 'glsl-transpiler'
```
TypeScript users should import the type separately. The default export is the compile function, not a named export.

Quickstart

Transpile a basic GLSL vertex shader to JavaScript using custom uniform/attribute mappers.

import GLSL from 'glsl-transpiler';

const compile = GLSL({
  uniform: (name) => `uniforms.${name}`,
  attribute: (name) => `attributes.${name}`
});

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