Squeezit Image Optimizer

Common errors

• command not found: squeezit

  cause The `squeezit` CLI tool is not installed globally or is not in your system's PATH.
  fix Install globally with `npm install -g squeezit` or `bun add -g squeezit`. Alternatively, if installed locally, run with `npx squeezit`.

• Error: Cannot find module 'webpack' from 'squeezit/webpack'

  cause A Squeezit bundler plugin (e.g., Webpack, Vite, Gulp) was used without its corresponding peer dependency installed in the project.
  fix Install the missing peer dependency: `npm install webpack` (or `vite`, `gulp`, etc., depending on the plugin in use).

• Error: Image processing failed for file 'path/to/image.png': [detailed error message]

  cause An unexpected issue occurred during the image optimization process, potentially due to a corrupted file, unsupported image format variant, or an internal library error.
  fix Check the detailed error message for clues. Verify the image file's integrity and ensure it's a supported format. Consider reporting the issue to the Squeezit project with the full error and file details.

Warnings

• gotcha When using Squeezit's bundler plugins (e.g., for Webpack, Vite, Gulp), their respective peer dependencies (e.g., 'webpack', 'vite', 'gulp') must be installed separately in your project. Failure to do so, or using incompatible versions, will result in runtime errors. Squeezit will not install these automatically.
  Fix: Manually install the required peer dependencies using your package manager (e.g., `npm install webpack` or `yarn add gulp`) ensuring version compatibility as specified in Squeezit's `peerDependencies`.
• gotcha The `squeezit` CLI is often installed globally (`npm install -g squeezit`). While convenient, ensure the global version aligns with any local project dependencies or specific plugin requirements to avoid unexpected behavior or command failures due to version mismatches.
  Fix: Prefer local installation (`npm install squeezit`) and run via `npx squeezit` in projects to ensure correct versioning, or use a version manager like `fnm` or `nvm` for global installations.
• gotcha Squeezit emphasizes a 'lossless-first' approach. While it provides aggressive compression, users expecting significant file size reductions that typically come with lossy compression might find the results less dramatic than anticipated. For maximum reduction, additional lossy steps might be required.
  Fix: Review the optimization goals. If aggressive lossy compression is needed, integrate a separate lossy optimization step or tool into your workflow before or after Squeezit, or explore Squeezit's options for near-lossless modes if available.
• gotcha When using glob expressions (e.g., `images/**/*.jpg`) with the CLI, recursive scanning is not enabled by default. You must explicitly include the `-r` or `--recursive` flag for Squeezit to process files in subdirectories.
  Fix: Always use `squeezit -r "your/glob/**/*.pattern"` when you intend to optimize images within nested folders.

Install

• npm install squeezit npm
• yarn add squeezit yarn
• pnpm add squeezit pnpm

Imports

• optimizeFile
  wrong:

  const { optimizeFile } = require('squeezit')

  correct:

  import { optimizeFile } from 'squeezit'

  The primary API functions are ESM-first. While CJS might work via transpilation, direct require is not the idiomatic usage.
• squeezitGulp
  wrong:

  import squeezitGulp from 'squeezit/gulp'

  correct:

  import { squeezitGulp } from 'squeezit/gulp'

  Gulp plugin is a named export from its specific subpath.
• registerSqueezitTask
  wrong:

  import { registerSqueezitTask } from 'squeezit/grunt'

  correct:

  const { registerSqueezitTask } = require('squeezit/grunt')

  The Grunt plugin is designed for CommonJS `require` due to typical Gruntfile environments.
• squeezitVite
  wrong:

  const { squeezitVite } = require('squeezit/vite')

  correct:

  import { squeezitVite } from 'squeezit/vite'

  Vite plugin is a named ESM export.

Quickstart

Demonstrates programmatic image optimization using the core `optimizeFile` API, creating a temporary file and reporting optimization results.

import { optimizeFile } from 'squeezit';
import { promises as fs } from 'fs';
import path from 'path';

async function runOptimization() {
  const imagePath = path.join(process.cwd(), 'example.png');
  const outputPath = path.join(process.cwd(), 'optimized-example.png');

  // Create a dummy image file for demonstration if it doesn't exist
  try {
    await fs.access(imagePath);
  } catch (error) {
    console.log(`Creating dummy file at ${imagePath}`);
    // Minimal PNG base64 representation (1x1 transparent PNG)
    const dummyPngBuffer = Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=', 'base64');
    await fs.writeFile(imagePath, dummyPngBuffer);
  }

  console.log(`Optimizing ${imagePath}...`);
  const result = await optimizeFile(imagePath, { 
    output: outputPath,
    overwrite: true, // Overwrite if target path is the same
    dryRun: false // Set to true to preview without saving
  });

  if (result.success) {
    console.log(`Optimization successful:`);
    console.log(`  Original size: ${result.originalSize} bytes`);
    console.log(`  Optimized size: ${result.optimizedSize} bytes`);
    console.log(`  Reduction: ${((1 - result.optimizedSize / result.originalSize) * 100).toFixed(2)}%`);
    console.log(`  Output to: ${outputPath}`);
  } else {
    console.error(`Optimization failed: ${result.error}`);
  }

  // Clean up the dummy file
  await fs.unlink(imagePath);
  if (result.success) {
    await fs.unlink(outputPath);
  }
}

runOptimization().catch(console.error);