threeify-glsl-transpiler

2.0.7 verified Fri May 01 auth: no javascript

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.

Common errors

error TypeError: threeify_glsl_transpiler.transpileFile is not a function ↓

cause 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 Error: Cannot find module './shader.glsl' ↓

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

fix

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

error WARNING: No threeify.json found in project root ↓

cause 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

Warnings

gotcha Transpiled 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';

breaking Version 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).

deprecated The 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.

gotcha Include 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.

gotcha 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. ↓

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

Install

npm install threeify-glsl-transpiler

yarn add threeify-glsl-transpiler

pnpm add threeify-glsl-transpiler

Imports

default

wrong

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

correct

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

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

transpileCLI

wrong

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

correct

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

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

transpileFile

wrong

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

correct

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

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

GlslConfig

wrong

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

correct

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

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

Quickstart

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