{"id":26475,"library":"threeify-glsl-transpiler","title":"threeify-glsl-transpiler","description":"A GLSL-to-JavaScript module transpiler for the threeify ecosystem. Version 2.0.7 offers CLI and configuration-based compilation of raw GLSL files (.glsl, .frag, .vert) into ES modules, with support for #pragma once include guards, watch mode, minification, and optional JavaScript/TypeScript includes. It integrates seamlessly into build pipelines, preserving IDE syntax highlighting and linting for shader source files. Unlike runtime shader compilers, this transpiler generates static JS modules, enabling tree-shaking and optimized bundling. Released under MIT license with TypeScript type definitions included.","status":"active","version":"2.0.7","language":"javascript","source_language":"en","source_url":"https://github.com/threeify/threeify-glsl-transpiler","tags":["javascript","glsl","compiler","threeify","transpiler","shaders","typescript"],"install":[{"cmd":"npm install threeify-glsl-transpiler","lang":"bash","label":"npm"},{"cmd":"yarn add threeify-glsl-transpiler","lang":"bash","label":"yarn"},{"cmd":"pnpm add threeify-glsl-transpiler","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Transpiled modules export a default string. Named import will fail.","wrong":"import { glslCode } from './shader.glsl.js';","symbol":"default","correct":"import glslCode from './shader.glsl.js';"},{"note":"Package is ESM-only. Do not use require().","wrong":"const transpileCLI = require('threeify-glsl-transpiler').transpileCLI;","symbol":"transpileCLI","correct":"import { transpileCLI } from 'threeify-glsl-transpiler';"},{"note":"TypeScript types included; prefer named import for tree-shaking.","wrong":"const { transpileFile } = require('threeify-glsl-transpiler');","symbol":"transpileFile","correct":"import { transpileFile } from 'threeify-glsl-transpiler';"},{"note":"GlslConfig is a type-only export (used in threeify.json). Use type import to avoid runtime error.","wrong":"import { GlslConfig } from 'threeify-glsl-transpiler';","symbol":"GlslConfig","correct":"import type { GlslConfig } from 'threeify-glsl-transpiler';"}],"quickstart":{"code":"// 1. Install the package\n// npm i -D threeify-glsl-transpiler\n\n// 2. Create a threeify.json in project root:\n{\n  \"glsl\": {\n    \"rootDir\": \"./src/shaders\",\n    \"outDir\": \"./dist/shaders\",\n    \"extensions\": [\"glsl\", \"frag\", \"vert\"],\n    \"minify\": true,\n    \"allowJSIncludes\": false\n  }\n}\n\n// 3. Add a build script in package.json:\n// \"build:shaders\": \"threeify-glsl-transpiler\"\n\n// 4. Run it:\n// npx threeify-glsl-transpiler\n\n// 5. Example source: src/shaders/vertex.glsl\n// #pragma once\n// void main() { gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0); }\n\n// 6. Output: dist/shaders/vertex.glsl.js\n// import { transpileFile } from 'threeify-glsl-transpiler';\n// const result = transpileFile('src/shaders/vertex.glsl', 'dist/shaders/vertex.glsl.js');\n// console.log('Transpiled:', result.success);","lang":"typescript","description":"Demonstrates configuration via threeify.json, CLI usage, and programmatic transpilation of a GLSL file into an ES module."},"warnings":[{"fix":"Always import from the generated .glsl.js file, e.g., import code from './shader.glsl.js';","message":"Transpiled output uses .glsl.js extension. Importing from the base .glsl file directly will fail at runtime or during bundling.","severity":"gotcha","affected_versions":">=1.0"},{"fix":"Update imports from 'require()' to 'import' statements. Ensure your project is ESM-compatible (use \"type\": \"module\" in package.json).","message":"Version 2.0 changed the default output format from CommonJS to ESM. Existing require() imports will break.","severity":"breaking","affected_versions":">=2.0"},{"fix":"Avoid using this option in production. If needed, pin version to 1.x and monitor releases.","message":"The CLI option --allowJSIncludes (-j) is experimental and may be removed in future releases.","severity":"deprecated","affected_versions":">=1.0"},{"fix":"Use consistent folder structures and avoid identical shader content across multiple paths.","message":"Include guards (#pragma once) generate long unique identifiers. Files with identical content in different paths will produce different IDs, potentially causing duplication.","severity":"gotcha","affected_versions":">=1.0"},{"fix":"Run a separate GLSL linter (e.g., glslangValidator) on your source files before transpilation.","message":"The transpiler does not validate GLSL syntax; it merely wraps the source. Syntax errors in the original .glsl file will be passed through and may cause runtime shader compilation failures.","severity":"gotcha","affected_versions":">=1.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Change to dynamic import: const { transpileFile } = await import('threeify-glsl-transpiler');","cause":"The package is ESM-only; using require() returns undefined for named exports.","error":"TypeError: threeify_glsl_transpiler.transpileFile is not a function"},{"fix":"Change import to './shader.glsl.js' (the generated output).","cause":"Importing the .glsl file directly instead of the transpiled .glsl.js file.","error":"Error: Cannot find module './shader.glsl'"},{"fix":"Either create a threeify.json in the project root or pass all flags via command line: threeify-glsl-transpiler -p ./src -o ./dist","cause":"CLI expects a threeify.json configuration file or explicit flags.","error":"WARNING: No threeify.json found in project root"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}