compress-shader-literals 0.0.4 → 0.0.7

package/README.md

@@ -1,15 +1,44 @@
 # compress-shader-literals
 
-> **Size matters.** Minify your GLSL & WGSL shader strings at build time — automatically, in any bundler.
+> **Size matters.** Strip everything strippable from your GLSL & WGSL shaders at build time.
+
+> ⭐ Star this repository to support development and help others discover it.
 
 [![npm version](https://img.shields.io/npm/v/compress-shader-literals?color=cb3837&logo=npm)](https://www.npmjs.com/package/compress-shader-literals)
 [![minzipped size](https://img.shields.io/bundlephobia/minzip/compress-shader-literals?color=success)](https://bundlephobia.com/package/compress-shader-literals)
 [![npm downloads](https://img.shields.io/npm/dm/compress-shader-literals?color=success)](https://www.npmjs.com/package/compress-shader-literals)
 [![license](https://img.shields.io/npm/l/compress-shader-literals?color=blue)](./LICENSE)
 
-Your shaders ship with every comment, indent, and blank line you wrote them with. This strips all of it — block comments, line comments, redundant whitespace — from `glsl` / `wgsl` template literals, **before** your bundler minifies the rest. Smaller bundles, zero source changes, full sourcemaps.
+Your shaders ship to users as strings. This strips the comments and whitespace out of them at build time, before your bundler ever sees them — in any bundler.
+
+![Alt Preview](./assets/preview.png)
+
+## Stats
+
+Measured on the real shaders shipped by popular libraries:
+
+<!-- STATS:START -->
+
+| Package               | Shaders |    Before |     After |     Saved |
+| --------------------- | ------: | --------: | --------: | --------: |
+| `three`               |     281 | 240,772 B | 203,428 B | **15.5%** |
+| `@jayf0x/fluidity-js` |       9 |   9,524 B |   7,133 B | **25.1%** |
+| `ogl`                 |      22 |   6,109 B |   5,335 B | **12.7%** |
+| `shader-park-core`    |      18 |  10,794 B |   9,033 B | **16.3%** |
+| `curtainsjs`          |       7 |   3,406 B |   2,563 B | **24.8%** |
+| **Total**             |     337 | 270,605 B | 227,492 B | **15.9%** |
+
+_Auto-generated by [`tests/e2e.js`](tests/e2e.js) · packages [verified](tests/validate.js) loadable · 2026-06-24_
+
+<!-- STATS:END -->
 
-Built on [unplugin](https://github.com/unjs/unplugin), so it runs in **Vite, Rollup, webpack, esbuild, Rspack, Rolldown & Farm** from one package.
+<!-- <a href="https://star-history.com/#jayf0x/compress-shader-literals&Date">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=jayf0x/compress-shader-literals&type=Date&theme=dark&legend=top-left" />
+    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=jayf0x/compress-shader-literals&type=Date&legend=top-left" />
+    <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=jayf0x/compress-shader-literals&type=Date&legend=top-left" />
+  </picture>
+</a> -->
 
 ## Install
 
@@ -34,74 +63,56 @@ export default { plugins: [compressShaderLiterals.vite({ outputRatio: true })] }
 // Rspack / Rolldown / Farm       →  .rspack() / .rolldown() / .farm()
 ```
 
-That's it. Shaders are compressed on the way through; everything else is untouched.
-
-## What it compresses
+It finds tagged and comment-prefixed literals — and yes, the comment form keeps your editor's syntax highlighting:
 
 ```ts
-// Tagged template literal
 const vert = glsl`
   // vertex shader  ← stripped
   precision highp float;
   void main() { gl_Position = vec4(0.0); }
 `;
 
-// Comment-prefixed template literal (great for editor syntax highlighting)
 const frag = /* wgsl */ `
   /* fragment */
   fn main() {}
 `;
 ```
 
-→ both become a single tight line, no comments, no padding.
-
-## Options
-
-| Option        | Default                      | Description                             |
-| ------------- | ---------------------------- | --------------------------------------- |
-| `tags`        | `['glsl', 'wgsl', 'shader']` | Tag names / comment markers to match    |
-| `include`     | `[/\.[jt]sx?$/]`             | Files to process                        |
-| `exclude`     | `[/node_modules/, /dist/]`   | Files to skip                           |
-| `outputRatio` | `false`                      | Print a bytes-saved summary after build |
-
-With `outputRatio: true`:
-
-```
-compress-shader-literals
-────────────────────────
-215.00 B → 134.00 B
-saved: 81.00 B (37.67% smaller)
-shaders: 1
-```
-
-## Real-world stats
+Both collapse to a single tight line. No comments, no padding, no touched source files.
 
-Run against the actual shaders shipped in **[three.js](https://www.npmjs.com/package/three)**, **[ogl](https://www.npmjs.com/package/ogl)**, **[shader-park-core](https://www.npmjs.com/package/shader-park-core)**, **[curtains.js](https://www.npmjs.com/package/curtainsjs)** and more — measured by this plugin's own engine ([`tests/e2e.js`](tests/e2e.js)):
+**Options**
 
-<!-- STATS:START -->
+| Option        | Default                      | Description                                        |
+| ------------- | ---------------------------- | -------------------------------------------------- |
+| `tags`        | `['glsl', 'wgsl', 'shader']` | Tag names / comment markers to match               |
+| `include`     | `[/\.[jt]sx?$/]`             | Files to process                                   |
+| `exclude`     | `[/node_modules/, /dist/]`   | Files to skip                                      |
+| `outputRatio` | `false`                      | Print a bytes-saved summary after build            |
+| `transform`   | built-in `minifyShader`      | Custom minifier — `(shader: string) => string`     |
+| `debug`       | `false`                      | Log each file's discovered literals to the console |
 
-| Package               | Shaders |    Before |     After |     Saved |
-| --------------------- | ------: | --------: | --------: | --------: |
-| `three`               |     281 | 240,772 B | 203,428 B | **15.5%** |
-| `@jayf0x/fluidity-js` |       9 |   9,524 B |   7,133 B | **25.1%** |
-| `ogl`                 |      22 |   6,109 B |   5,335 B | **12.7%** |
-| `shader-park-core`    |      18 |  10,794 B |   9,033 B | **16.3%** |
-| `curtainsjs`          |       7 |   3,406 B |   2,563 B | **24.8%** |
-| **Total**             |     337 | 270,605 B | 227,492 B | **15.9%** |
+**Programmatic API** — the two core helpers are exported for tooling authors (validators, ESLint rules, CLIs), no plugin required:
 
-_337 real shaders from 5 package(s), compressed by this plugin's engine._
+```js
+import { extractShaderLiterals, minifyShader } from 'compress-shader-literals';
 
-<!-- STATS:END -->
+extractShaderLiterals('const v = glsl`void main() {}`');
+// → [{ tag: 'glsl', value: 'void main() {}', start: 10, end: 26 }]
 
-Free bytes off code you already ship — no source changes. Marginal per shader, but it compounds across every shader in every bundle, and at infra scale even 1% is worth shipping.
+minifyShader('// comment\nvoid  main() {}'); // → 'void main() {}'
+```
 
 ## How it works
 
+Nothing clever, which is the point:
+
 1. Parses each matched file with Babel (TS/JSX aware).
-2. Finds tagged and comment-prefixed shader literals (see [What it compresses](#what-it-compresses)).
-3. Strips comments + collapses whitespace, rewriting via [`magic-string`](https://github.com/Rich-Harris/magic-string) so **sourcemaps stay intact**.
+2. Finds tagged and comment-prefixed shader literals.
+3. Strips comments + collapses whitespace via [`magic-string`](https://github.com/Rich-Harris/magic-string), so **sourcemaps stay intact**.
 4. Runs as a `pre` transform, so your bundler's own minifier still sees the result.
 
+One [unplugin](https://github.com/unjs/unplugin) covers **Vite, Rollup, webpack, esbuild, Rspack, Rolldown & Farm**.
+
 ## License
 
-[MIT](./LICENSE) © jayF0x
+[MIT](./LICENSE) © [jayF0x](https://github.com/jayf0x)

package/dist/index.d.ts

@@ -0,0 +1,41 @@
+import type { UnpluginInstance } from 'unplugin';
+
+/** A picomatch glob string, RegExp, or a list of them — matched against module ids. */
+type FilterPattern = string | RegExp | ReadonlyArray<string | RegExp> | null;
+
+export interface CompressShaderLiteralsOptions {
+  /** Tag names / comment markers to match. Default: `['glsl', 'wgsl', 'shader']` */
+  tags?: string[];
+  /** Files to process. Default: `[/\.[jt]sx?$/]` */
+  include?: FilterPattern;
+  /** Files to skip. Default: `[/node_modules/, /dist/]` */
+  exclude?: FilterPattern;
+  /** Print a bytes-saved summary after build. Default: `false` */
+  outputRatio?: boolean;
+  /** Custom minifier, replaces the built-in `minifyShader`. Receives the raw literal, returns the transformed source. */
+  transform?: (shader: string) => string;
+  /** Log each file's discovered literals to the console. Default: `false` */
+  debug?: boolean;
+}
+
+/** A shader literal discovered in source. */
+export interface ShaderLiteral {
+  tag: string;
+  value: string;
+  start: number;
+  end: number;
+}
+
+/**
+ * Minify GLSL/WGSL shader template literals at build time.
+ *
+ * Universal plugin — call the bundler you use: `.vite()`, `.rollup()`,
+ * `.webpack()`, `.esbuild()`, `.rspack()`, `.rolldown()`, `.farm()`.
+ */
+export declare const compressShaderLiterals: UnpluginInstance<CompressShaderLiteralsOptions | undefined, boolean>;
+
+/** Find tagged (`glsl\`...\``) and comment-prefixed (`/* wgsl *\/ \`...\``) shader literals in source. */
+export declare function extractShaderLiterals(code: string, tags?: string[]): ShaderLiteral[];
+
+/** Strip comments and collapse whitespace in a shader source string. */
+export declare function minifyShader(src: string): string;

package/dist/index.js

@@ -1,5 +1,6 @@
 // src/plugin.js
 import { createFilter } from "@rollup/pluginutils";
+import { diff, snap } from "byte-snap";
 import MagicString from "magic-string";
 import { createUnplugin } from "unplugin";
 
@@ -62,31 +63,12 @@ function minifyShader(src) {
 }
 
 // src/plugin.js
-function fmtBytes(bytes) {
-  const units = ["B", "KB", "MB", "GB"];
-  let v = bytes;
-  let u = 0;
-  while (v >= 1024 && u < units.length - 1) {
-    v /= 1024;
-    u++;
-  }
-  return `${v.toFixed(2)} ${units[u]}`;
-}
-function printRatio(beforeBytes, afterBytes, files) {
-  const saved = beforeBytes - afterBytes;
-  const pct = beforeBytes === 0 ? 0 : saved / beforeBytes * 100;
-  console.log(`
-compress-shader-literals`);
-  console.log("────────────────────────");
-  console.log(`${fmtBytes(beforeBytes)} → ${fmtBytes(afterBytes)}`);
-  console.log(`saved: ${fmtBytes(saved)} (${pct.toFixed(2)}% smaller)`);
-  console.log(`shaders: ${files}
-`);
-}
 var compressShaderLiterals = createUnplugin((options = {}) => {
   const tags = options.tags || ["glsl", "wgsl", "shader"];
+  const minify = options.transform || minifyShader;
   const filter = createFilter(options.include || [/\.[jt]sx?$/], options.exclude || [/node_modules/, /dist/]);
-  const stats = { before: 0, after: 0, files: 0 };
+  let beforeText = "";
+  let afterText = "";
   return {
     name: "compress-shader-literals",
     enforce: "pre",
@@ -98,31 +80,32 @@ var compressShaderLiterals = createUnplugin((options = {}) => {
       const literals = extractShaderLiterals(code, tags);
       if (literals.length === 0)
         return null;
+      if (options.debug) {
+        console.log(`[compress-shader-literals] ${id}: ${literals.length} literal(s) — ${literals.map((l) => l.tag).join(", ")}`);
+      }
       const ms = new MagicString(code);
       let hasChanges = false;
       for (const literal of literals) {
-        const minified = minifyShader(literal.value);
+        const minified = minify(literal.value);
         if (literal.value !== minified) {
           ms.overwrite(literal.start, literal.end, `\`${minified}\``);
           hasChanges = true;
         }
+        if (options.outputRatio) {
+          beforeText += literal.value;
+          afterText += minified;
+        }
       }
       if (!hasChanges)
         return null;
-      const resultCode = ms.toString();
-      if (options.outputRatio) {
-        stats.before += Buffer.byteLength(code);
-        stats.after += Buffer.byteLength(resultCode);
-        stats.files += 1;
-      }
       return {
-        code: resultCode,
+        code: ms.toString(),
         map: ms.generateMap({ hires: true, source: id })
       };
     },
     buildEnd() {
-      if (options.outputRatio && stats.files > 0) {
-        printRatio(stats.before, stats.after, stats.files);
+      if (options.outputRatio && beforeText) {
+        diff(snap.text(beforeText), snap.text(afterText)).print();
       }
     }
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "compress-shader-literals",
-  "version": "0.0.4",
+  "version": "0.0.7",
   "type": "module",
   "description": "Size matters. Minify GLSL/WGSL shader template literals at build time — universal plugin for Vite, Rollup, webpack, esbuild & more.",
   "keywords": [
@@ -8,7 +8,13 @@
     "glsl",
     "wgsl",
     "minify",
+    "minification",
     "compress",
+    "compression",
+    "bundle-size",
+    "optimization",
+    "code-size",
+    "typescript",
     "webgl",
     "webgpu",
     "three",
@@ -36,8 +42,10 @@
   },
   "main": "./dist/index.js",
   "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     }
   },
@@ -46,9 +54,11 @@
   ],
   "sideEffects": false,
   "scripts": {
-    "build": "bun build src/plugin.js --outdir dist --entry-naming index.js --target node --format esm --external @babel/parser --external @babel/traverse --external @rollup/pluginutils --external magic-string --external unplugin && node scripts/compress-dist.js",
+    "build": "bun build src/plugin.js --outdir dist --entry-naming index.js --target node --format esm --external @babel/parser --external @babel/traverse --external @rollup/pluginutils --external byte-snap --external magic-string --external unplugin && cp src/index.d.ts dist/index.d.ts && node scripts/compress-dist.js",
+    "typecheck": "tsc --noEmit --strict --skipLibCheck src/index.d.ts",
     "test": "bun test",
     "test:run": "bun test",
+    "test:validate": "cd tests && bun install && node validate.js",
     "test:e2e": "cd tests && bun install && node e2e.js",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
@@ -59,11 +69,13 @@
     "@babel/parser": "^8.0.0",
     "@babel/traverse": "^8.0.0",
     "@rollup/pluginutils": "^5.4.0",
+    "byte-snap": "^1.0.3",
     "magic-string": "^0.30.21",
     "unplugin": "^3.0.0"
   },
   "devDependencies": {
     "@trivago/prettier-plugin-sort-imports": "^5.0.0",
-    "prettier": "^3.0.0"
+    "prettier": "^3.0.0",
+    "typescript": "^5.6.0"
   }
 }