{"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,"search_vec":"'2.0.7':17 'base':23 'build':53 'bundl':81 'cli':19 'compil':24,68,93 'configur':22 'configuration-bas':21 'definit':89 'ecosystem':15 'enabl':75 'es':33 'file':28,64 'frag':30 'generat':71 'glsl':3,7,27,29,92 'glsl-to-javascript':6 'guard':41 'highlight':58 'ide':56 'includ':40,48,90 'integr':50 'javascript':9,91 'javascript/typescript':47 'js':73 'licens':85 'lint':60 'minif':44 'mit':84 'mode':43 'modul':10,34,74 'offer':18 'optim':80 'option':46 'pipelin':54 'pragma':38 'preserv':55 'raw':26 'releas':82 'runtim':66 'seamless':51 'shader':62,67,96 'shake':78 'sourc':63 'static':72 'support':36 'syntax':57 'threeifi':2,14,94 'threeify-glsl-transpil':1 'transpil':4,11,70,95 'tree':77 'tree-shak':76 'type':88 'typescript':87,97 'unlik':65 'version':16 'vert':31 'watch':42","created_at":"2026-05-01T13:50:10.254547+00:00","updated_at":"2026-05-01T13:50:10.254547+00:00","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,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"threeify-glsl-transpiler","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/threeify/threeify-glsl-transpiler","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/threeify-glsl-transpiler","openapi_spec":null,"status_page":null,"smithery":null,"categories":["web-framework"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-05-01","next_check":"2026-07-30","install_tag":null}}