tessl/npm-minify

Minifier of js, css, html and img files with CLI and programmatic interfaces

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Image Processing (Base64 Inlining)

Name: tessl/npm-minify
Author: tessl

CSS image optimization through base64 inlining to reduce HTTP requests and improve web performance by embedding small images directly in stylesheets.

Capabilities

Image Base64 Inlining Function

Converts CSS image references to base64 data URIs for reduced network requests.

/**
 * Converts CSS images to base64 inline format
 * @param name - File path for directory context and resolution
 * @param data - CSS data containing image URL references
 * @param userOptions - Configuration options for image processing
 * @returns Promise resolving to CSS with inlined base64 images
 */
function minify.img(name: string, data: string, userOptions?: MinifyOptions): Promise<string>;

interface MinifyOptions {
  img?: {
    maxSize?: number;                         // Maximum file size for inlining (bytes)
  };
}

// Default configuration
const defaultImageOptions = {
  maxSize: 102400  // 100KB (100 * 1024 bytes)
};

Usage Examples:

import { minify } from "minify";

// Basic image inlining
const cssWithImages = `
  .logo {
    background-image: url('assets/logo.png');
  }
  .icon {
    background: url('../icons/star.svg') center no-repeat;
  }
`;

const inlined = await minify.img('/path/to/style.css', cssWithImages);
// Result: CSS with base64 data URIs replacing compatible image URLs

// Custom size limit
const customInlined = await minify.img('/path/to/style.css', cssWithImages, {
  img: {
    maxSize: 50000  // 50KB limit instead of default 100KB
  }
});

// Integration with CSS minification
const optimized = await minify.css(cssWithImages, {
  css: { type: 'clean-css' },
  img: { maxSize: 25000 }  // 25KB limit for inlining
});

Image Processing Workflow

File Resolution Process

Parse CSS: Extract url() references from CSS content
Resolve Paths: Convert relative URLs to absolute file paths using the name parameter context
Check File Size: Compare image file size against maxSize threshold
Encode Eligible Images: Convert qualifying images to base64 data URIs
Replace URLs: Substitute original URLs with inline data URIs

Path Resolution

The name parameter provides directory context for resolving relative image paths:

interface PathResolution {
  baseDirectory: string;                    // Directory containing the CSS file
  relativeDirectory: string;                // Parent directory for relative resolution
}

// Path resolution examples:
// CSS file: /project/styles/main.css
// Base directory: /project/styles/
// Relative directory: /project/styles/../ = /project/

Path Resolution Examples:

// CSS file path: /project/assets/css/styles.css
const cssContent = `
  .header { background: url('images/header.jpg'); }      // → /project/assets/css/images/header.jpg
  .logo { background: url('../images/logo.png'); }       // → /project/assets/images/logo.png
  .icon { background: url('../../icons/star.svg'); }     // → /project/icons/star.svg
`;

const result = await minify.img('/project/assets/css/styles.css', cssContent);

Size Threshold Management

Default Size Limits

Images are only inlined if they meet the size criteria:

const ONE_KB = 1024;                        // 1 kilobyte in bytes

const defaultThresholds = {
  maxSize: 100 * ONE_KB,                    // 102,400 bytes (100KB)
  
  // Size considerations:
  // - Small icons (< 5KB): Always inline for performance
  // - Medium images (5-50KB): Inline for fewer requests
  // - Large images (> 100KB): Keep as external files
};

Custom Size Configuration

Configure size limits based on your performance requirements:

// Conservative inlining (small images only)
const conservative = await minify.img(cssFile, cssData, {
  img: { maxSize: 10000 }  // 10KB limit
});

// Aggressive inlining (larger images)
const aggressive = await minify.img(cssFile, cssData, {
  img: { maxSize: 500000 }  // 500KB limit
});

// Disable inlining completely
const noInlining = await minify.img(cssFile, cssData, {
  img: { maxSize: 0 }  // No images will be inlined
});

Supported Image Formats

Base64 inlining works with all common web image formats:

interface SupportedFormats {
  'image/png': string;                      // PNG images
  'image/jpeg': string;                     // JPEG/JPG images
  'image/gif': string;                      // GIF images
  'image/svg+xml': string;                  // SVG vector graphics
  'image/webp': string;                     // WebP images
  'image/bmp': string;                      // Bitmap images
  'image/ico': string;                      // Icon files
}

Format-Specific Examples:

const multiFormatCSS = `
  .png-icon { background: url('icon.png'); }           // PNG support
  .jpg-photo { background: url('photo.jpg'); }         // JPEG support
  .gif-animation { background: url('spinner.gif'); }   // GIF support
  .svg-vector { background: url('arrow.svg'); }        // SVG support
  .webp-modern { background: url('image.webp'); }      // WebP support
`;

const inlined = await minify.img('/css/styles.css', multiFormatCSS);
// All compatible formats converted to appropriate data URIs

Performance Considerations

Benefits of Image Inlining

Reduced HTTP Requests: Fewer network round trips
Faster Page Loading: Eliminates image download delays
Better Caching: Images cached with CSS
Simplified Deployment: Fewer asset files to manage

Drawbacks to Consider

Increased CSS Size: Base64 encoding adds ~33% overhead
Cache Inefficiency: Images re-downloaded with every CSS change
Memory Usage: Base64 data uses more browser memory
Processing Overhead: Encoding/decoding computational cost

Best Practices

// Optimal size thresholds for different use cases
const performanceOptimized = {
  // Critical path icons and sprites
  criticalAssets: { maxSize: 5000 },        // 5KB - inline critical icons
  
  // General UI elements
  uiElements: { maxSize: 25000 },           // 25KB - moderate inlining
  
  // Background images and photos
  backgroundImages: { maxSize: 0 },         // Don't inline large images
};

// Example usage
const criticalCSS = await minify.img(cssFile, criticalStyles, {
  img: performanceOptimized.criticalAssets
});

Integration with CSS Minification

Image inlining is automatically applied during CSS file minification:

// Automatic image processing during CSS minification
const optimizedCSS = await minify('./styles.css', {
  css: {
    type: 'clean-css',
    'clean-css': { level: 2 }
  },
  img: {
    maxSize: 30000  // 30KB threshold for images
  }
});

// The process:
// 1. CSS is minified using clean-css
// 2. Image inlining is automatically applied
// 3. Final result contains both optimizations

Error Handling

Image processing handles various error conditions gracefully:

File Access Errors: Missing image files are skipped with warnings
Path Resolution Errors: Invalid paths are logged but don't break processing
Encoding Errors: Corrupted images are skipped with error messages
Size Validation: Files exceeding limits are left as external references

Error Examples:

// Missing image file
const cssWithMissing = `.icon { background: url('missing.png'); }`;
const result = await minify.img('/css/style.css', cssWithMissing);
// Result: Original CSS unchanged, error logged

// Invalid path resolution
try {
  await minify.img('', cssContent);  // Empty name parameter
} catch (error) {
  console.log(error); // AssertionError for missing name
}

// File size exceeded
const cssWithLargeImage = `.bg { background: url('large-photo.jpg'); }`;
const result = await minify.img('/css/style.css', cssWithLargeImage, {
  img: { maxSize: 1000 }  // 1KB limit
});
// Result: Large image URL preserved, not inlined