Registry / web-framework / threeify-glsl-transpiler

threeify-glsl-transpiler

library2.0.7jsnpmunverified

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.

web-framework

npm install threeify-glsl-transpiler

github ↗package ↗

INSTALL

IMPORT

SIG · THREEIFY-GLSL-TRAN

threeify-glsl-transpiler

web-frameworkjavascriptv2.0.7

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ import glslCode from './shader.glsl.js';

✗ import { glslCode } from './shader.glsl.js';

Transpiled modules export a default string. Named import will fail.

transpileCLI

✓ import { transpileCLI } from 'threeify-glsl-transpiler';

✗ const transpileCLI = require('threeify-glsl-transpiler').transpileCLI;

Package is ESM-only. Do not use require().

transpileFile

✓ import { transpileFile } from 'threeify-glsl-transpiler';

✗ const { transpileFile } = require('threeify-glsl-transpiler');

TypeScript types included; prefer named import for tree-shaking.

GlslConfig

✓ import type { GlslConfig } from 'threeify-glsl-transpiler';

✗ import { GlslConfig } from 'threeify-glsl-transpiler';

GlslConfig is a type-only export (used in threeify.json). Use type import to avoid runtime error.

Demonstrates configuration via threeify.json, CLI usage, and programmatic transpilation of a GLSL file into an ES module.

// 1. Install the package // npm i -D threeify-glsl-transpiler // 2. Create a threeify.json in project root: { "glsl": { "rootDir": "./src/shaders", "outDir": "./dist/shaders", "extensions": ["glsl", "frag", "vert"], "minify": true, "allowJSIncludes": false } } // 3. Add a build script in package.json: // "build:shaders": "threeify-glsl-transpiler" // 4. Run it: // npx threeify-glsl-transpiler // 5. Example source: src/shaders/vertex.glsl // #pragma once // void main() { gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0); } // 6. Output: dist/shaders/vertex.glsl.js // import { transpileFile } from 'threeify-glsl-transpiler'; // const result = transpileFile('src/shaders/vertex.glsl', 'dist/shaders/vertex.glsl.js'); // console.log('Transpiled:', result.success);

threeify-glsl-transpiler --version

Debug

Known issues

gotchaTranspiled output uses .glsl.js extension. Importing from the base .glsl file directly will fail at runtime or during bundling.

fix

Always import from the generated .glsl.js file, e.g., import code from './shader.glsl.js';

affects: >=1.0

breakingVersion 2.0 changed the default output format from CommonJS to ESM. Existing require() imports will break.

fix

Update imports from 'require()' to 'import' statements. Ensure your project is ESM-compatible (use "type": "module" in package.json).

affects: >=2.0

deprecatedThe CLI option --allowJSIncludes (-j) is experimental and may be removed in future releases.

fix

Avoid using this option in production. If needed, pin version to 1.x and monitor releases.

affects: >=1.0

gotchaInclude guards (#pragma once) generate long unique identifiers. Files with identical content in different paths will produce different IDs, potentially causing duplication.

fix

Use consistent folder structures and avoid identical shader content across multiple paths.

affects: >=1.0

gotchaThe 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.

fix

Run a separate GLSL linter (e.g., glslangValidator) on your source files before transpilation.

affects: >=1.0

Errors

Common errors & fixes

TypeError: threeify_glsl_transpiler.transpileFile is not a function

The package is ESM-only; using require() returns undefined for named exports.

fix

Change to dynamic import: const { transpileFile } = await import('threeify-glsl-transpiler');

Error: Cannot find module './shader.glsl'

Importing the .glsl file directly instead of the transpiled .glsl.js file.

fix

Change import to './shader.glsl.js' (the generated output).

WARNING: No threeify.json found in project root

CLI expects a threeify.json configuration file or explicit flags.

fix

Either create a threeify.json in the project root or pass all flags via command line: threeify-glsl-transpiler -p ./src -o ./dist

Upgrade

Version history

2.0.7latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

10 hits · last 30 days

node

Resources

githubhttps://github.com/threeify/threeify-glsl-transpiler ↗

packagehttps://www.npmjs.com/package/threeify-glsl-transpiler ↗