npm package: @leadmetrics-ai/landing-build-tool
Description: Universal static site optimizer for HTML, CSS (Tailwind, Bootstrap, SCSS, CSS), JS, images, and fonts.
Author: Leadmetrics.ai
Latest version: 1.2.5

# @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:

```bash
npm install --save-dev @leadmetrics-ai/landing-build-tool
```

---

## ⚡ Usage

### 1. Add a `build.config.json` to your project root

Example:

```json
{
  "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:

```css
@import "tailwindcss";
@tailwind base;
@tailwind components;
@tailwind utilities;
/* Your custom CSS... */
```

### 3. Add a build script to your `package.json`

```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.

```bash
npm install --save-dev tailwindcss
```

### 5. Run the build

```bash
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

```text
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