# Asset Minification Guide


**Last Updated:** 2025-11-20

## Overview

All CSS and JavaScript files in `v2/css/` and `v2/js/` must be minified before deployment. This ensures optimal performance and resolves SEO audit warnings about unminified assets.

## Quick Start

After editing any CSS or JavaScript file:

```bash
npm run minify
```

This automatically minifies all configured files and creates `.min.css` and `.min.js` versions.

## Files Requiring Minification

### CSS Files
- `v2/css/comparison-pages.css` → `comparison-pages.min.css`
- `v2/css/tools-pages.css` → `tools-pages.min.css`
- `v2/css/templates-pages.css` → `templates-pages.min.css`
- `v2/css/product-pages.css` → `product-pages.min.css`

### JavaScript Files
- `v2/js/utm-tracking.js` → `utm-tracking.min.js`
- `v2/js/shiftops-pdf-generator.js` → `shiftops-pdf-generator.min.js`
- `v2/js/lead-capture-triggers.js` → `lead-capture-triggers.min.js`
- `v2/js/comparison-pages.js` → `comparison-pages.min.js`
- `v2/js/branchen-components.js` → `branchen-components.min.js`

## When to Run Minification

**ALWAYS run minification:**
1. After editing any CSS file in `v2/css/` (except `.min.css` files)
2. After editing any JavaScript file in `v2/js/` (except `.min.js` files)
3. Before committing changes to CSS/JS files
4. Before deploying to production

## Workflow

1. **Edit source files** (`*.css` or `*.js` in `v2/css/` or `v2/js/`)
2. **Run minification**: `npm run minify`
3. **Verify minified files** were created/updated
4. **Commit both** source and minified files

## File References

**CRITICAL**: Always reference minified versions in PHP files:

```php
<!-- CSS -->
<link rel="stylesheet" href="/v2/css/comparison-pages.min.css?v=<?php echo filemtime(__DIR__ . '/../css/comparison-pages.min.css'); ?>" media="print" onload="this.media='all'">
<noscript><link rel="stylesheet" href="/v2/css/comparison-pages.min.css"></noscript>

<!-- JavaScript -->
<script src="/v2/js/utm-tracking.min.js?v=<?php echo filemtime(__DIR__ . '/../js/utm-tracking.min.js'); ?>"></script>
```

**Key points:**
- Use `.min.css`/`.min.js` extensions
- Use dynamic versioning with `filemtime()` for cache busting
- Never reference non-minified versions in production code

## Adding New Files to Minification

When adding new CSS/JS files that should be minified:

1. **Add to minification script**: Edit `minify-assets.js`
   ```javascript
   const cssFiles = [
     // ... existing files ...
     'v2/css/your-new-file.css',  // Add here
   ];
   
   const jsFiles = [
     // ... existing files ...
     'v2/js/your-new-file.js',  // Add here
   ];
   ```

2. **Update all references**: Change from `.css`/`.js` to `.min.css`/`.min.js`
   - Search for all references: `grep -r "your-new-file\.css" v2/`
   - Update to use `.min.css` version with dynamic versioning

3. **Run minification**: `npm run minify`

4. **Verify**: Check that `.min.css`/`.min.js` files are created

## Minification Script

**Location**: `minify-assets.js`

**What it does:**
- Minifies CSS using `cssnano` (via PostCSS)
- Minifies JavaScript using `terser`
- Creates `.min.css` and `.min.js` files
- Reports size reductions for each file

**Expected savings:**
- CSS: 30-50% size reduction
- JavaScript: 20-75% size reduction (varies by file)

**Example output:**
```
✓ v2/js/utm-tracking.js → v2/js/utm-tracking.min.js (103.7 KB → 39.1 KB, 62.3% smaller)
✓ v2/css/comparison-pages.css → v2/css/comparison-pages.min.css (15.5 KB → 9.8 KB, 36.8% smaller)
```

## Verification

After running minification, verify:

1. **Files exist**: Check that `.min.css`/`.min.js` files are created
   ```bash
   ls -lh v2/css/*.min.css v2/js/*.min.js
   ```

2. **File sizes**: Verify minified files are smaller than originals
   ```bash
   ls -lh v2/css/comparison-pages*.css
   ```

3. **References**: Verify all PHP files reference minified versions
   ```bash
   grep -r "comparison-pages\.css[^.]" v2/pages/
   # Should return no results (all should use .min.css)
   ```

4. **Browser test**: Check Network tab in DevTools to verify minified files are loading

## Troubleshooting

### Minification fails

- **Check file paths**: Verify files exist in `minify-assets.js` paths
- **Check dependencies**: Run `npm install` to ensure cssnano and terser are installed
- **Check syntax**: Ensure source files have valid CSS/JS syntax

### Minified files not updating

- **Clear cache**: Delete `.min.css`/`.min.js` files and re-run `npm run minify`
- **Check timestamps**: Verify minified files have newer timestamps than source files

### References still pointing to non-minified files

- **Search for references**: `grep -r "file\.css[^.]" v2/` (without `.min`)
- **Update references**: Change to `.min.css`/`.min.js` with dynamic versioning
- **Verify**: Re-run grep to confirm no unminified references remain

## Performance Impact

**Current savings:**
- Total JS reduction: ~214 KB → ~105 KB (51% smaller)
- Total CSS reduction: ~16 KB → ~10 KB (38% smaller)
- **Total savings: ~115 KB (50% reduction)**

**Largest individual savings:**
- `utm-tracking.js`: 62.3% reduction (103.7 KB → 39.1 KB)
- `lead-capture-triggers.js`: 61.8% reduction (30.8 KB → 11.8 KB)
- `branchen-components.js`: 75% reduction (3.4 KB → 875 B)

## Related Documentation

- Performance rules: `.cursor/rules/performance.mdc`
- Caching strategy: `docs/performance/caching-strategy.md`
- External scripts guide: `docs/guides/EXTERNAL_SCRIPTS_CACHING.md`

## Best Practices

1. **Never edit `.min.css`/`.min.js` files directly** - Always edit source files
2. **Always run minification** after editing source files
3. **Commit both** source and minified files to git
4. **Use dynamic versioning** (`filemtime()`) for cache busting
5. **Verify minified files** are loading in browser DevTools before deploying