compress-shader-literals 0.0.5 → 0.0.7

package/README.md

@@ -2,12 +2,14 @@
 
 > **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)
 
-Smaller WebGL & WebGPU bundles for free — shrink your shaders at build time, in any bundler.
+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)
 
@@ -26,10 +28,18 @@ Measured on the real shaders shipped by popular libraries:
 | `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-23_
+_Auto-generated by [`tests/e2e.js`](tests/e2e.js) · packages [verified](tests/validate.js) loadable · 2026-06-24_
 
 <!-- STATS:END -->
 
+<!-- <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
 
 ```sh
@@ -53,45 +63,56 @@ export default { plugins: [compressShaderLiterals.vite({ outputRatio: true })] }
 // Rspack / Rolldown / Farm       →  .rspack() / .rolldown() / .farm()
 ```
 
-## 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 |
-
----
-
-## What it compresses
-
-Comments, indentation, and blank lines — stripped from your `glsl` / `wgsl` literals before your bundler even runs. Zero source changes, full sourcemaps. One [unplugin](https://github.com/unjs/unplugin) covers **Vite, Rollup, webpack, esbuild, Rspack, Rolldown & Farm**.
+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 (keeps editor syntax highlighting)
 const frag = /* wgsl */ `
   /* fragment */
   fn main() {}
 `;
 ```
 
-Both collapse to a single tight line — no comments, no padding.
+Both collapse to a single tight line. No comments, no padding, no touched source files.
+
+**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            |
+| `transform`   | built-in `minifyShader`      | Custom minifier — `(shader: string) => string`     |
+| `debug`       | `false`                      | Log each file's discovered literals to the console |
+
+**Programmatic API** — the two core helpers are exported for tooling authors (validators, ESLint rules, CLIs), no plugin required:
+
+```js
+import { extractShaderLiterals, minifyShader } from 'compress-shader-literals';
+
+extractShaderLiterals('const v = glsl`void main() {}`');
+// → [{ tag: 'glsl', value: 'void main() {}', start: 10, end: 26 }]
+
+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.
 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](https://github.com/jayf0x)

package/dist/index.d.ts

@@ -12,6 +12,18 @@ export interface CompressShaderLiteralsOptions {
   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;
 }
 
 /**
@@ -21,3 +33,9 @@ export interface CompressShaderLiteralsOptions {
  * `.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

@@ -65,6 +65,7 @@ function minifyShader(src) {
 // src/plugin.js
 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/]);
   let beforeText = "";
   let afterText = "";
@@ -79,10 +80,13 @@ 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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "compress-shader-literals",
-  "version": "0.0.5",
+  "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": [
@@ -69,7 +69,7 @@
     "@babel/parser": "^8.0.0",
     "@babel/traverse": "^8.0.0",
     "@rollup/pluginutils": "^5.4.0",
-    "byte-snap": "^1.0.0",
+    "byte-snap": "^1.0.3",
     "magic-string": "^0.30.21",
     "unplugin": "^3.0.0"
   },