zcompress-vite-plugin 0.1.2 → 0.1.4

package/README.md

@@ -8,7 +8,7 @@ Vite 生产构建资源压缩插件 — gzip / zstd / brotli，多线程并行
 npm install zcompress-vite-plugin --save-dev
 ```
 
-安装后自动下载对应平台的 zcompress 二进制。如果下载失败，手动安装：
+安装后会自动下载对应平台的 `zcompress` 二进制。下载失败可手动安装：
 
 | 平台 | 命令 |
 |------|------|
@@ -35,17 +35,7 @@ export default {
 };
 ```
 
-`vite build` 后，`dist-compressed/` 目录下就是压缩后的文件：
-
-```
-dist-compressed/
-├── index.html.gz
-├── style.css.gz
-├── app.js.gz
-└── logo.svg.gz
-```
-
-配合 Nginx 的 `gzip_static on` 直接使用。
+`vite build` 后，`dist-compressed/` 目录下就是压缩后的文件。
 
 ## 选项
 
@@ -56,13 +46,35 @@ dist-compressed/
 | `threads` | `number` | `0` | 线程数 (0=CPU 核心数) |
 | `verbose` | `boolean` | `false` | 显示详细输出 |
 | `cache` | `boolean` | `false` | 跳过未修改文件 |
-| `include` | `string[]` | `[]` | 额外压缩的扩展名 (如 `['.ts']`) |
-| `exclude` | `string[]` | `[]` | 排除的扩展名 (如 `['.map']`) |
+| `include` | `string[]` | `[]` | 额外压缩扩展名 |
+| `exclude` | `string[]` | `[]` | 排除扩展名 |
 | `binaryPath` | `string` | 自动 | 手动指定二进制路径 |
+| `failOnError` | `boolean` | `true` | 压缩失败时让 `vite build` 失败 |
 
-## 默认压缩的文件类型
+## 故障排查
+
+### `postinstall` 下载二进制 404
+
+如果看到类似：
+
+```txt
+https://github.com/luochuan2008/zcompress/releases/download/vX.Y.Z/zcompress-macos-arm64 → 404
+```
 
-`.js` `.mjs` `.cjs` `.css` `.html` `.htm` `.json` `.svg` `.png` `.jpg` `.jpeg` `.gif` `.ico` `.ttf` `.woff` `.woff2` `.xml` `.csv` `.wasm`
+说明 npm 版本已发布，但对应 GitHub Release 还没上传该平台二进制。
+
+解决方式：
+
+1. 手动安装 CLI（上面安装表）
+2. 在插件里指定 `binaryPath`
+
+```js
+zcompress({
+  binaryPath: '/absolute/path/to/zcompress',
+})
+```
+
+默认 `failOnError: true`，失败会直接中断构建（不会静默跳过压缩）。
 
 ## License
 
@@ -80,11 +92,16 @@ High-performance multi-threaded asset compression for Vite production builds. 5-
 npm install zcompress-vite-plugin --save-dev
 ```
 
-The correct platform binary is downloaded automatically. If that fails:
+The package auto-downloads a platform binary. If that fails, install/build manually:
 
 ```bash
-brew install zcompress          # macOS
-zig build install               # from source
+# macOS
+brew install zstd brotli
+zig build -Doptimize=ReleaseFast
+
+# Linux
+sudo apt-get install -y libzstd-dev libbrotli-dev
+zig build -Doptimize=ReleaseFast
 ```
 
 ## Usage
@@ -97,7 +114,7 @@ export default {
   plugins: [
     zcompress({
       algo: 'brotli',   // 'gzip' | 'zstd' | 'brotli'
-      level: 11,        // 1-9
+      level: 9,         // 1-9
       threads: 0,       // 0 = auto
       cache: true,      // skip unchanged files
     })
@@ -105,15 +122,7 @@ export default {
 };
 ```
 
-After `vite build`, find compressed assets in `dist-compressed/`:
-
-```
-dist-compressed/
-├── index.html.br
-├── style.css.br
-├── app.js.br
-└── logo.svg.br
-```
+After `vite build`, compressed assets are written to `dist-compressed/`.
 
 ## Options
 
@@ -127,6 +136,32 @@ dist-compressed/
 | `include` | `string[]` | `[]` | Extra extensions to compress |
 | `exclude` | `string[]` | `[]` | Extensions to skip |
 | `binaryPath` | `string` | auto | Override binary path |
+| `failOnError` | `boolean` | `true` | Fail `vite build` when compression fails |
+
+## Troubleshooting
+
+### `postinstall` binary download returns 404
+
+If you see:
+
+```txt
+https://github.com/luochuan2008/zcompress/releases/download/vX.Y.Z/zcompress-macos-arm64 → 404
+```
+
+that npm version exists, but the matching GitHub Release binary asset is missing.
+
+Workarounds:
+
+1. Install/build the CLI manually
+2. Set `binaryPath` explicitly
+
+```js
+zcompress({
+  binaryPath: '/absolute/path/to/zcompress',
+})
+```
+
+Default `failOnError: true` ensures builds fail loudly (instead of silently skipping compression).
 
 ## License
 

package/index.d.ts

@@ -16,6 +16,8 @@ declare module 'zcompress-vite-plugin' {
     exclude?: string[];
     /** Override path to zcompress binary */
     binaryPath?: string;
+    /** Fail Vite build if compression fails (default: true) */
+    failOnError?: boolean;
   }
 
   import type { Plugin } from 'vite';

package/index.js

@@ -2,7 +2,7 @@
  * zcompress Vite Plugin
  *
  * A Vite plugin that compresses build output using the zcompress CLI.
- * Provides multi-threaded gzip/zstd compression for production builds.
+ * Provides multi-threaded gzip/zstd/brotli compression for production builds.
  *
  * @example
  * // vite.config.js
@@ -15,9 +15,12 @@
  * };
  */
 
-import { execSync } from 'node:child_process';
-import { existsSync, statSync } from 'node:fs';
-import { join } from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { existsSync, statSync, readdirSync } from 'node:fs';
+import { join, dirname, isAbsolute } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
 
 /**
  * @typedef {Object} ZCompressOptions
@@ -29,6 +32,7 @@ import { join } from 'node:path';
  * @property {string[]} [include] - Extra file extensions to include
  * @property {string[]} [exclude] - File extensions to exclude
  * @property {string} [binaryPath] - Path to zcompress binary
+ * @property {boolean} [failOnError=true] - Fail Vite build if compression fails
  */
 
 /** @type {ZCompressOptions} */
@@ -40,19 +44,19 @@ const DEFAULT_OPTIONS = {
   cache: false,
   include: [],
   exclude: [],
+  failOnError: true,
 };
 
 /**
  * Find the zcompress binary.
- * Order: 1) downloaded by postinstall  2) PATH  3) local zig build
+ * Order: 1) downloaded by postinstall 2) local zig build 3) PATH
  */
 function findBinary() {
-  // 1. Check for postinstall-downloaded binary
-  const binDir = join(__dirname, 'bin');
-  const localBin = join(binDir, process.platform === 'win32' ? 'zcompress.exe' : 'zcompress');
-  if (existsSync(localBin)) return localBin;
+  // 1) postinstall-downloaded binary inside package
+  const packagedBin = join(__dirname, 'bin', process.platform === 'win32' ? 'zcompress.exe' : 'zcompress');
+  if (existsSync(packagedBin)) return packagedBin;
 
-  // 2. Check local zig build
+  // 2) local zig build
   const zigPaths = [
     join(process.cwd(), 'zig-out', 'bin', 'zcompress'),
     join(process.cwd(), 'zig-out', 'bin', 'zcompress.exe'),
@@ -61,7 +65,7 @@ function findBinary() {
     if (existsSync(p)) return p;
   }
 
-  // 3. Fall back to PATH
+  // 3) PATH
   return 'zcompress';
 }
 
@@ -74,20 +78,29 @@ function findBinary() {
 export default function zcompressPlugin(userOptions = {}) {
   const options = { ...DEFAULT_OPTIONS, ...userOptions };
 
+  // ESM-safe plugin state (do not use `this`)
+  let active = false;
+  let resolvedOutDir = 'dist';
+
   return {
     name: 'zcompress',
     apply: 'build',
     enforce: 'post',
 
     configResolved(config) {
-      // Only run in production build mode
-      this.active = config.command === 'build';
+      active = config.command === 'build';
+
+      // Save outDir from Vite config (Bug #2 fix)
+      const configuredOutDir = config.build?.outDir || 'dist';
+      resolvedOutDir = isAbsolute(configuredOutDir)
+        ? configuredOutDir
+        : join(config.root || process.cwd(), configuredOutDir);
     },
 
     closeBundle() {
-      if (!this.active) return;
+      if (!active) return;
 
-      const outDir = this.outDir || 'dist';
+      const outDir = resolvedOutDir;
       const compressedDir = `${outDir}-compressed`;
 
       if (!existsSync(outDir)) {
@@ -103,18 +116,12 @@ export default function zcompressPlugin(userOptions = {}) {
         '-l', String(options.level),
       ];
 
-      if (options.threads > 0) {
-        args.push('-t', String(options.threads));
-      }
+      if (options.threads > 0) args.push('-t', String(options.threads));
       if (options.verbose) args.push('--verbose');
       if (options.cache) args.push('--cache');
 
-      for (const ext of options.include) {
-        args.push(`--include=${ext}`);
-      }
-      for (const ext of options.exclude) {
-        args.push(`--exclude=${ext}`);
-      }
+      for (const ext of options.include) args.push(`--include=${ext}`);
+      for (const ext of options.exclude) args.push(`--exclude=${ext}`);
 
       const cmd = `${binary} ${args.join(' ')}`;
 
@@ -125,10 +132,9 @@ export default function zcompressPlugin(userOptions = {}) {
       const startTime = Date.now();
 
       try {
-        execSync(cmd, { stdio: 'inherit' });
+        execFileSync(binary, args, { stdio: 'inherit' });
         const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
 
-        // Calculate size stats
         const srcSize = getDirSize(outDir);
         const destSize = getDirSize(compressedDir);
         const savedPct = srcSize > 0
@@ -137,8 +143,18 @@ export default function zcompressPlugin(userOptions = {}) {
 
         console.log(`[zcompress] ✅ Compressed ${formatSize(srcSize)} → ${formatSize(destSize)} (saved ${savedPct}%) in ${elapsed}s`);
       } catch (err) {
-        console.error(`[zcompress] ❌ Compression failed: ${err.message}`);
-        console.error('[zcompress] Make sure zcompress is installed: zig build install');
+        const message = [
+          `[zcompress] ❌ Compression failed: ${err.message}`,
+          `[zcompress] Binary used: ${binary}`,
+          '[zcompress] If this is a 404 download issue, GitHub Release may be missing prebuilt binaries for this version.',
+          '[zcompress] Workaround: install CLI manually (`zig build -Doptimize=ReleaseFast`) and set `binaryPath` in plugin options.',
+        ].join('\n');
+
+        if (options.failOnError !== false) {
+          throw new Error(message);
+        }
+
+        console.error(message);
       }
     },
   };
@@ -152,17 +168,19 @@ export default function zcompressPlugin(userOptions = {}) {
  */
 function getDirSize(dirPath) {
   if (!existsSync(dirPath)) return 0;
-  // Simple approximation — list files and sum their sizes
+
   let total = 0;
   try {
-    const { readdirSync } = require('node:fs');
-    const { join } = require('node:path');
     walkDir(dirPath, (filePath) => {
       try {
         total += statSync(filePath).size;
-      } catch (_) { /* ignore */ }
+      } catch {
+        // ignore unreadable files
+      }
     });
-  } catch (_) { /* ignore */ }
+  } catch {
+    // ignore traversal failures
+  }
   return total;
 }
 
@@ -173,8 +191,6 @@ function getDirSize(dirPath) {
  * @param {(path: string) => void} fn
  */
 function walkDir(dir, fn) {
-  const { readdirSync } = require('node:fs');
-  const { join } = require('node:path');
   try {
     const entries = readdirSync(dir, { withFileTypes: true });
     for (const entry of entries) {
@@ -185,7 +201,9 @@ function walkDir(dir, fn) {
         fn(full);
       }
     }
-  } catch (_) { /* ignore */ }
+  } catch {
+    // ignore traversal failures
+  }
 }
 
 /**

package/install.js

@@ -5,8 +5,7 @@
  * Falls back gracefully if the binary can't be downloaded (e.g. air-gapped, unsupported platform).
  */
 
-import { execSync } from 'node:child_process';
-import { createWriteStream, existsSync, chmodSync, mkdirSync, unlinkSync } from 'node:fs';
+import { createWriteStream, existsSync, chmodSync, mkdirSync, unlinkSync, readFileSync } from 'node:fs';
 import { get } from 'node:https';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -14,8 +13,11 @@ import { pipeline } from 'node:stream/promises';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const BIN_DIR = join(__dirname, 'bin');
-const VERSION = '0.1.0'; // Update on each release
-const REPO = 'luochuan2008/zcompress'; // Change to your GitHub username/repo
+const REPO = 'luochuan2008/zcompress';
+
+// Read package version dynamically to avoid manual sync bugs.
+const pkgJson = JSON.parse(readFileSync(join(__dirname, 'package.json'), 'utf8'));
+const VERSION = pkgJson.version;
 
 const PLATFORM_MAP = {
   'darwin-arm64':  'zcompress-macos-arm64',
@@ -84,7 +86,14 @@ async function downloadBinary() {
     console.log(`[zcompress] ✓ Binary installed: ${destPath}`);
     return true;
   } catch (err) {
-    console.log(`[zcompress] ⚠ Could not download binary (${err.message}). Build from source: cd zcompress && zig build install`);
+    if (String(err.message).includes('HTTP 404')) {
+      console.log(`[zcompress] ⚠ Release asset not found for v${VERSION}: ${binaryName}`);
+      console.log(`[zcompress] ⚠ Expected URL: ${url}`);
+      console.log('[zcompress] ⚠ This usually means the npm version was published before uploading binary assets to GitHub Releases.');
+    } else {
+      console.log(`[zcompress] ⚠ Could not download binary (${err.message}).`);
+    }
+    console.log('[zcompress] ℹ Build from source: cd zcompress && zig build -Doptimize=ReleaseFast');
     // Clean up partial download
     try { unlinkSync(destPath); } catch (_) { /* ignore */ }
     return false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zcompress-vite-plugin",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "High-performance multi-threaded asset compression for Vite — powered by Zig",
   "type": "module",
   "main": "index.js",