@leadmetrics-ai/landing-build-tool

Universal static site optimizer for HTML, CSS (Tailwind, Bootstrap, SCSS, CSS), JS, images, and fonts with Lighthouse performance optimizations.

✨ Features

🎨 CSS Processing

• Auto-detects and builds Tailwind CSS (requires tailwind.config.js and tailwindcss package)
• Bootstrap support - Detects and minifies existing Bootstrap CSS files
• SCSS compilation - Compiles SCSS files to compressed CSS
• CSS minification - Level 2 optimization with CleanCSS
• Size reporting - Shows original vs minified sizes with percentage savings

⚡ JavaScript Optimization

• Advanced minification with Terser
• Dead code elimination - Removes console.log and debugger statements
• Variable mangling for smaller file sizes
• Comment removal for production builds
• Detailed compression stats with before/after file sizes

🖼️ Image Optimization

• Responsive Image Generation - Creates mobile, tablet, laptop, and desktop versions automatically
• Smart srcset replacement - Replaces src with responsive srcset and sizes attributes
• Device-optimized breakpoints:
  • Mobile: 480px width, 80% quality
  • Tablet: 768px width, 85% quality
  • Laptop: 1024px width, 85% quality
  • Desktop: 1920px width, 90% quality
• JPEG optimization - MozJPEG with progressive encoding for responsive versions
• PNG optimization - Smart compression maintaining quality across devices
• WebP preservation - Responsive WebP generation with optimized quality
• SVG/ICO/GIF support - Copies other formats as-is
• Comprehensive reporting - Shows optimization results per device and totals
• Graceful fallback - Falls back to standard optimization if responsive generation fails

📄 HTML Optimization & Lighthouse Performance

• HTML minification - Removes comments, whitespace, and redundant attributes
• Image lazy loading - Adds loading="lazy" to images (except first 2 for LCP)
• Hero image priority - Adds fetchpriority="high" to first image
• Preconnect hints - Auto-detects and adds preconnect for:
  • Google Fonts (fonts.googleapis.com, fonts.gstatic.com)
  • Analytics (google-analytics.com, googletagmanager.com)
  • Social (facebook.com, connect.facebook.net)
  • CDNs (cdnjs.cloudflare.com, cdn.jsdelivr.net)
• Mobile optimization - Ensures viewport meta tag exists
• CSS preloading - Adds preload hints for critical stylesheets
• Accessibility - Adds missing alt attributes to images
• Layout shift prevention - Adds width/height attributes to images

🔤 Font Management

• Font copying - Preserves all font formats (OTF, TTF, WOFF, WOFF2, EOT)
• Directory structure - Maintains original folder organization

🎥 Video Handling

• Video copying - Copies all video files without optimization
• Format support - Handles MP4, WebM, OGG, AVI, MOV, WMV, FLV, MKV, M4V
• Directory preservation - Maintains original folder structure
• Size reporting - Shows file sizes and total video assets processed

🛠️ Build System

• Configurable via build.config.json
• Cross-platform (Windows, macOS, Linux)
• Clean builds - Removes output directory before building
• Sequential processing - CSS → JS → Images → HTML → Fonts → Videos
• Comprehensive logging - Color-coded status messages and statistics

🚀 Installation

Add as a dev dependency to your project:

npm install --save-dev @leadmetrics-ai/landing-build-tool

⚡ Usage

1. Add a build.config.json to your project root

Example:

{
  "outputDir": "dist",
  "folders": {
    "images": "images",
    "fonts": "fonts",
    "videos": "videos",
    "js": "js",
    "css": "css",
    "scss": "scss"
  },
  "css": {
    "input": "src/input.css",
    "output": "css/styles.css"
  },
  "images": {
    "responsive": true
  }
}

2. Prepare your CSS entry file

For Tailwind, your src/input.css should start with:

@import "tailwindcss";
@tailwind base;
@tailwind components;
@tailwind utilities;
/* Your custom CSS... */

3. Add a build script to your package.json

"scripts": {
  "build": "landing-build-tool"
}

4. Install Tailwind CSS in your project

Note:
The Tailwind CLI is included with this tool, but you must install tailwindcss in your project for Tailwind builds to work.

npm install --save-dev tailwindcss

5. Run the build

npm run build

All optimized files will be output to your configured dist/ folder.

📝 Notes

• Tailwind:
  • Requires tailwind.config.js in your project root.
  • Requires tailwindcss installed in your project (npm install --save-dev tailwindcss).
  • The CLI (@tailwindcss/cli) is bundled with this tool.
  • The generated Tailwind CSS file will be automatically linked in all your HTML files (if not already present).
• Bootstrap: If you use Bootstrap via CDN or downloaded CSS, just place the file in your css folder.
• SCSS: Place your .scss files in the configured scss folder.
• Images/Fonts/Videos: Place assets in the folders specified in your config.

📁 Example Output

dist/
├── images/           # Responsive images organized by device
│   ├── mobile/       # 480px width optimized images
│   ├── tablet/       # 768px width optimized images  
│   ├── laptop/       # 1024px width optimized images
│   ├── desktop/      # 1920px width optimized images
│   └── *.svg         # SVG/ICO/GIF files copied as-is
├── fonts/            # Copied fonts
├── js/               # Minified JS with compression stats
├── css/              # Minified CSS (Tailwind, Bootstrap, SCSS, etc.)
├── *.html            # Minified HTML with responsive srcset

🚀 Lighthouse Performance Features

This tool automatically applies the following performance optimizations to improve your mobile Lighthouse scores:

Image Performance

• Responsive Images: Automatically converts src to srcset with device-optimized breakpoints
• Smart Lazy Loading: Adds loading="lazy" to images except the first 2 (for better LCP)
• Priority Hints: Adds fetchpriority="high" to the first image for faster loading
• Layout Stability: Adds proper sizes attributes to prevent layout shift
• Accessibility: Ensures all images have alt attributes (empty for decorative images)
• Fallback Support: Provides src fallback for browsers without srcset support

Network Optimization

• Preconnect Hints: Automatically detects and adds <link rel="preconnect"> for:
  • Google Fonts: fonts.googleapis.com, fonts.gstatic.com
  • Analytics: google-analytics.com, googletagmanager.com
  • Social Media: facebook.com, connect.facebook.net
  • CDNs: cdnjs.cloudflare.com, cdn.jsdelivr.net

CSS Performance

• Critical CSS Preloading: Adds rel="preload" for the first stylesheet to improve render times

Mobile Optimization

• Responsive Design: Ensures proper viewport meta tag exists for mobile compatibility

Expected Impact

These optimizations target key Lighthouse metrics:

• Performance: Faster loading through preconnect hints and lazy loading
• Best Practices: Proper image attributes and responsive design
• Accessibility: Alt attributes for screen readers
• SEO: Mobile-friendly viewport and semantic HTML

Result: Can help improve Lighthouse mobile scores from 60-75 to 85+

🛠️ Advanced

• Customize optimization by editing build.config.json.
• Supports additional options for minification, image quality, etc.

📣 License

MIT © Leadmetrics.ai