{"id":25636,"library":"glsl-transpiler","title":"glsl-transpiler","description":"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.","status":"active","version":"3.0.3","language":"javascript","source_language":"en","source_url":"https://github.com/stackgl/glsl-transpiler","tags":["javascript","headless-gl","gl","glsl","glsl.js","glsl-transpiler","transpiler","stackgl","js"],"install":[{"cmd":"npm install glsl-transpiler","lang":"bash","label":"npm"},{"cmd":"yarn add glsl-transpiler","lang":"bash","label":"yarn"},{"cmd":"pnpm add glsl-transpiler","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Builds GLSL AST from tokenized GLSL source","package":"glsl-parser","optional":false},{"reason":"Tokenizes GLSL source code into tokens","package":"glsl-tokenizer","optional":false}],"imports":[{"note":"Package is ESM-only since v2.0.0. Use dynamic import with CommonJS.","wrong":"const GLSL = require('glsl-transpiler')","symbol":"default (compile function)","correct":"import GLSL from 'glsl-transpiler'"},{"note":"Stream submodule path must include .js extension for ESM. CommonJS require may not work.","wrong":"const compile = require('glsl-transpiler/stream')","symbol":"compile stream","correct":"import compile from 'glsl-transpiler/stream.js'"},{"note":"TypeScript users should import the type separately. The default export is the compile function, not a named export.","wrong":"import { GLSL } from 'glsl-transpiler'","symbol":"GLSL type (TypeScript)","correct":"import type { GLSL } from 'glsl-transpiler'"}],"quickstart":{"code":"import GLSL from 'glsl-transpiler';\n\nconst compile = GLSL({\n  uniform: (name) => `uniforms.${name}`,\n  attribute: (name) => `attributes.${name}`\n});\n\nconst result = compile(`\n  precision mediump float;\n  attribute vec2 uv;\n  attribute vec4 color;\n  varying vec4 fColor;\n  uniform vec2 uScreenSize;\n\n  void main(void) {\n    fColor = color;\n    vec2 position = vec2(uv.x, -uv.y) * 1.0;\n    position.x *= uScreenSize.y / uScreenSize.x;\n    gl_Position = vec4(position, 0, 1);\n  }\n`);\n\nconsole.log(result);","lang":"typescript","description":"Transpile a basic GLSL vertex shader to JavaScript using custom uniform/attribute mappers."},"warnings":[{"fix":"Use dynamic import or switch to ESM imports.","message":"ESM-only since v2.0.0: CommonJS require('glsl-transpiler') will fail.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Prefer programmatic API unless streaming is required.","message":"Node streams API for glsl-parser/stream is experimental and may change in future versions.","severity":"deprecated","affected_versions":">=1.0.0"},{"fix":"Wrap texture data in ndarray or provide width/height metadata.","message":"texture2D function expects ndarray or objects with width/height properties; passing a plain Float32Array may cause runtime errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Set optimize: false or enable debug: true to preserve original structure.","message":"Optimizer may rename variables and remove dead code; debugging can be harder.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Replace require with dynamic import: const GLSL = await import('glsl-transpiler')","cause":"Using CommonJS require on ESM-only package v2+","error":"SyntaxError: Unexpected token 'export'"},{"fix":"Use import GLSL from 'glsl-transpiler' (default import) not import { GLSL } from 'glsl-transpiler'","cause":"Misinterpreting GLSL as named export instead of default","error":"TypeError: GLSL is not a function"},{"fix":"Use import compile from 'glsl-transpiler/stream.js' (with .js extension)","cause":"Missing .js extension in ESM import path","error":"Module not found: Can't resolve 'glsl-transpiler/stream'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}