lite-asset

A lightweight resource usage analyzer that helps you identify unused assets in your project and track their usage frequency.

Features

• Resource Analysis: Analyzes resource files (images, fonts, videos, etc.) in your project
• Usage Tracking: Tracks how frequently each resource is used in your source code
• Duplicate Detection: Identifies duplicate files based on content hash
• Package List Generation: Extracts package information from package.json
• Multiple Output Formats: Supports both Markdown and CSV output formats
• Configurable: Customizable file inclusion/exclusion patterns
• Asset Compression: Optimizes images (WebP conversion) and fonts (WOFF2 compression)

Installation

Global Installation

npm install -g lite-asset

Local Usage

npx lite-asset

Prerequisites for WOFF2 Support

lite-asset uses the woff2 library for font compression, which requires native compilation.

macOS Users

Important: macOS users must ensure the following prerequisites are met:

1. Xcode Command Line Tools (Required)

   • Install: xcode-select --install
   • Verify: xcode-select --print-path should return /Library/Developer/CommandLineTools
   • If not installed, run: sudo xcode-select --install

2. Node.js Version (Critical)

   • Required: Node.js v18.17.0 or higher
   • Check version: node --version
   • If using nvm: nvm install 18.17.0 && nvm use 18.17.0

3. Environment Variables (If compilation fails)

   export SDKROOT=$(xcrun --show-sdk-path)
   export CXX=/usr/bin/clang++
   export CC=/usr/bin/clang
   export PYTHON=/usr/bin/python3

Windows Users

To install successfully on Windows, you need the following prerequisites:

Required Software

1. Python (3.x recommended)

   • Download from python.org
   • Make sure to check "Add Python to PATH" during installation

2. Visual Studio Build Tools

   • Download Visual Studio Installer from visualstudio.microsoft.com
   • Install "C++ build tools" workload
   • Include these components:
     • MSVC v143 - VS 2022 C++ x64/x86 build tools
     • Windows 10/11 SDK (latest version)
     • CMake tools for Visual Studio

3. Node.js (v14 or higher)

   • Download from nodejs.org

Installation Steps

1. Install Python and Visual Studio Build Tools as described above
2. Restart your command prompt/terminal
3. Install lite-asset:

   npm install -g lite-asset

Troubleshooting

If you encounter build errors during installation:

1. Check Python installation:

   python --version

2. Verify Visual Studio Build Tools:

   • Open Visual Studio Installer
   • Ensure "C++ build tools" workload is installed

3. Set npm configuration:

   npm config set msvs_version 2022
   npm config set python python3

4. Clear npm cache and retry:

   npm cache clean --force
   npm install -g lite-asset

Usage

Basic Usage

# Use default configuration
lite-asset

# Specify output file
lite-asset --out report.md

# Generate CSV report
lite-asset --out report.csv --format csv

# Generate package list from package.json
lite-asset --packages --out packages.md

# Generate package list in CSV format
lite-asset --packages --format csv --out packages.csv

# Use custom configuration
lite-asset --out report.md --config ./my-config.json

# Enable compression (converts images to WebP and fonts to WOFF2)
lite-asset --compress --out compressed-report.md

Command Line Options

| Option | Description | Default | |--------|-------------|---------| | --config <path> | Path to configuration file | ./config.json | | --out <path> | Output file path | lite-asset.md | | --format <format> | Output format (markdown or csv) | markdown | | --packages | Generate package list from package.json | false | | --compress | Enable asset compression (WebP for images, WOFF2 for fonts) | false |

Configuration File

Create a config.json file in your project root:

{
  "except": [
    "webpack.config.base.js",
    "webpack.config.dev.js",
    "scripts/**/*.js",
    "dist/**/*"
  ],
  "condition": {
    "extension": [
      "svg", "png", "jpg", "jpeg", "ttf", "woff", "woff2", "eot", "mp4", "mp3", "wav", "avi", "css", "js"
    ],
    "size": {
      "min": 100,
      "max": 5000
    },
    "usage": {
      "min": 1,
      "max": 50
    }
  },
  "source": ["src", "public"]
}

Configuration Options

• except: Array of glob patterns to exclude from analysis
• condition.extension: Array of file extensions to include in resource analysis
• condition.size: Object with min and max properties for file size filtering
• condition.usage: Object with min and max properties for usage frequency filtering
• source: Array of directories to search for usage references

Note: The include field has been replaced with condition.extension for better organization and future extensibility.

Asset Compression

When using the --compress option, lite-asset will:

• Convert images to WebP: PNG, JPG, JPEG, GIF, BMP, TIFF files are converted to WebP format with 85% quality
• Convert fonts to WOFF2: TTF files are compressed to WOFF2 format
• Update file references: Automatically updates all source code references to point to the new compressed files
• Replace original files: Original files are deleted and replaced with compressed versions

Compression Example

# Analyze and compress assets
lite-asset --compress --out compressed-report.md

This will:

1. Analyze your assets
2. Convert images to WebP
3. Convert TTF fonts to WOFF2
4. Update all file references in your source code
5. Generate a report showing compression ratios and savings

Output

Markdown Format

# Resource Usage Report

| Name | Usage Frequency | Size | Directory | Hash | Paths |
|------|----------------|------|-----------|------|-------|
| logo.png | 5 | 1.2 KB | assets/images | `a1b2c3d4` | - assets/images/logo.png<br/>- public/logo.png |
| style.css | 3 | 0.8 KB | public | `e5f6g7h8` | - public/style.css |

CSV Format

Name,Usage Frequency,Size,Directory,Hash,Paths
logo.png,5,1.2 KB,assets/images,a1b2c3d4e5f6...,- assets/images/logo.png
,,,,,- public/logo.png
style.css,3,0.8 KB,public,e5f6g7h8i9j0...,- public/style.css

How It Works

1. File Discovery: Scans your project for resource files based on configured extensions
2. Hash Generation: Creates content-based hashes using first 50 bytes + file size + filename
3. Usage Analysis: Searches source code for filename references using regex patterns
4. Duplicate Detection: Groups files with identical content hashes
5. Path Tracking: Shows all file paths for duplicate files in the Paths column
6. Report Generation: Outputs usage statistics in your chosen format
7. Asset Compression (optional): Converts and optimizes assets while updating references

Package List Generation

The --packages option allows you to extract package information from your package.json file and generate a report in the same format as resource analysis.

Package List Features

• Dependency Extraction: Extracts packages from dependencies, devDependencies, and peerDependencies
• Consistent Format: Uses the same table format as resource analysis for consistency
• Package Statistics: Shows count by dependency type
• Multiple Formats: Supports both Markdown and CSV output

Package List Output Format

The package list uses the same table structure as resource analysis:

| Name | Usage Frequency | Size | Directory | Hash | Paths | |------|----------------|------|-----------|------|-------| | package-name | 0 | 0 B | node_modules | package-name | - node_modules/package-name |

Examples

Find Unused Images

lite-asset --format csv --out unused-assets.csv

Analyze and Compress Assets

lite-asset --compress --format markdown --out optimized-report.md

Analyze Specific Directory

{
  "source": ["src/components", "src/pages"],
  "include": ["png", "jpg", "svg"],
  "except": ["node_modules/**/*"]
}

Performance

• Optimized for large projects with thousands of files
• Uses content-based hashing for efficient duplicate detection
• Memory-efficient text file filtering
• Fast regex-based usage pattern matching
• Efficient image processing with Sharp library
• Native font compression with WOFF2

License

MIT This project includes libraries licensed under the Apache License 2.0.