LARC Build Process - Minified Production Files

Created: December 7, 2025 Status: ✅ Implemented and Tested

🎯 Overview

The LARC monorepo now has a comprehensive build process that creates minified versions of all .mjs files alongside their unminified sources.

Strategy

Development: Use .mjs files (unminified, with comments, easier debugging)
Production: Use .min.mjs files (minified, optimized, smaller size)

Both versions exist side-by-side, giving developers flexibility to choose based on their needs.

📦 Build Scripts Created

1. Monorepo Root: `scripts/build-minified.js`

Orchestrates builds across all submodules. Usage:

cd /home/cdr/domains/larcjs.com/www/larc
npm run build:minify

2. Core: `core/scripts/build-minified.js`

Minifies all .mjs files in @larcjs/core Input Files (6):

src/pan.mjs
pan-bus.mjs
pan-client.mjs
pan-debug.mjs
pan-routes.mjs
pan-storage.mjs

Output: .min.mjs files alongside each source Usage:

cd /home/cdr/domains/larcjs.com/www/larc/core
npm run build:minify

3. UI: `ui/scripts/build-minified.js`

Minifies all .mjs files in @larcjs/ui Input Files (57): All component files in src/components/:

pan-table.mjs
pan-form.mjs
pan-router.mjs
pan-store.mjs
... and 53 more

Output: .min.mjs files alongside each source Usage:

cd /home/cdr/domains/larcjs.com/www/larc/ui
npm run build:minify

🚀 Available Scripts

Monorepo Level

# Minify all .mjs files in core and ui
npm run build:minify

# Run standard build + minification
npm run build:all

# Just the standard build (for packages)
npm run build

Core Package Level

cd core/

# Standard build (creates dist/ with bundled files)
npm run build

# Minify source files (creates .min.mjs alongside .mjs)
npm run build:minify

# Both: standard build + minification
npm run build:all

UI Package Level

cd ui/

# Minify source files (creates .min.mjs alongside .mjs)
npm run build:minify

# Alias for build:minify (UI doesn't bundle, just minifies)
npm run build:all

📊 File Size Comparison

Core Package

| File | Original | Minified | Savings | |------|----------|----------|---------| | pan.mjs | 13 KB | 3.4 KB | 74% | | pan-bus.mjs | 23 KB | 12 KB | 48% | | pan-client.mjs | ~15 KB | ~8 KB | 47% |

Average Savings: 50-75% smaller

🔧 Build Configuration

esbuild Settings

{
  format: 'esm',           // ES modules format
  minify: true,            // Enable minification
  bundle: false,           // Don't bundle, keep separate files
  platform: 'browser',     // Browser environment
  target: 'es2022',        // Modern browsers
  sourcemap: false,        // No sourcemaps for minified
  legalComments: 'none',   // Remove all comments
  treeShaking: true,       // Remove dead code
  charset: 'utf8'          // UTF-8 encoding
}

What Gets Minified

✅ Included:

All .mjs files in src/ directory
Recursively processes subdirectories
Both components and utilities

❌ Excluded:

Files already ending in .min.mjs
Test files (tests/ directory)
node_modules/
Hidden directories (.git, etc.)

📝 Usage in HTML

Development Mode (Unminified)

<!-- Core -->
<script type="module" src="/core/pan.mjs"></script>

<!-- Individual component -->
<script type="module" src="/core/pan-bus.mjs"></script>

<!-- UI Components -->
<script type="module" src="/components/pan-table.mjs"></script>

Benefits:

Full comments and documentation
Easier debugging
Readable stack traces
Better error messages

Production Mode (Minified)

<!-- Core -->
<script type="module" src="/core/pan.min.mjs"></script>

<!-- Individual component -->
<script type="module" src="/core/pan-bus.min.mjs"></script>

<!-- UI Components -->
<script type="module" src="/components/pan-table.min.mjs"></script>

Benefits:

50-75% smaller file sizes
Faster downloads
Reduced bandwidth
Better performance

🔄 CI/CD Integration

Git Ignore

Add to .gitignore to avoid committing minified files:

# Minified files (can be regenerated)
*.min.mjs
*.min.js

Or commit them if you want to serve directly from git:

git add src/**/*.min.mjs
git commit -m "Add minified production files"

Build on Deploy

# In your deployment script
cd /home/cdr/domains/larcjs.com/www/larc
git pull
npm run build:minify

# Minified files now available for production use

📂 Directory Structure After Build

Core

core/
├── src/
│   ├── pan.mjs                     ✅ Original (13 KB)
│   ├── pan.min.mjs                 ✨ Minified (3.4 KB)
│   └── components/
│       ├── pan-bus.mjs             ✅ Original (23 KB)
│       ├── pan-bus.min.mjs         ✨ Minified (12 KB)
│       ├── pan-client.mjs          ✅ Original
│       ├── pan-client.min.mjs      ✨ Minified
│       └── ...
└── dist/                           (Standard bundled output)

UI

ui/
└── src/
    └── components/
        ├── pan-table.mjs           ✅ Original
        ├── pan-table.min.mjs       ✨ Minified
        ├── pan-form.mjs            ✅ Original
        ├── pan-form.min.mjs        ✨ Minified
        ├── pan-router.mjs          ✅ Original
        ├── pan-router.min.mjs      ✨ Minified
        └── ... (57 components total)

🎨 Automatic Serving Strategy

Option 1: Manual Selection (Current)

Developers manually choose which version to import:

<!-- Dev -->
<script type="module" src="/core/pan.mjs"></script>

<!-- Prod -->
<script type="module" src="/core/pan.min.mjs"></script>

Option 2: Environment-Based (Future)

Use a build-time variable or server-side logic:

<script type="module" src="/core/pan{{ ENV === 'production' ? '.min' : '' }}.mjs"></script>

Option 3: .htaccess Rewrite (Advanced)

# Serve .min.mjs if available and requested
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME}.min.mjs -f
RewriteRule ^(.*)\.mjs$ $1.min.mjs [L]

✅ Verification

Test Minified Files Work

# Start local server
cd /home/cdr/domains/larcjs.com/www
python3 -m http.server 8000

# Visit test page
# http://localhost:8000/test-minified.html

Test HTML:

<!DOCTYPE html>
<html>
<head>
    <title>Minified Test</title>
</head>
<body>
    <h1>Testing Minified Files</h1>
    <div id="output"></div>

    <!-- Test minified core -->
    <script type="module">
        import { PanClient } from '/core/pan-client.min.mjs';

        const client = new PanClient();
        document.getElementById('output').textContent =
            'Minified files loaded successfully! ✅';

        console.log('PanClient:', client);
    </script>
</body>
</html>

🔍 Troubleshooting

Build Fails

# Make sure esbuild is installed
cd core
npm install

cd ../ui
npm install

Files Not Minified

# Check script is executable
chmod +x scripts/build-minified.js

# Run manually
node scripts/build-minified.js

Import Errors

Minified files preserve ES module structure
Imports/exports work the same as unminified
Check browser console for specific errors

📈 Performance Impact

Before (Unminified Only)

Total Core Size: ~80 KB
Total UI Size: ~1.2 MB (57 components)
Total: ~1.28 MB

After (Using Minified)

Total Core Size: ~40 KB (50% savings)
Total UI Size: ~600 KB (50% savings)
Total: ~640 KB (50% reduction!)

Impact

Faster page loads
Reduced bandwidth costs
Better mobile performance
Improved lighthouse scores

🚀 Future Enhancements

Potential Additions

Gzip/Brotli compression on server

Source maps for production debugging

Cache busting with file hashes

CDN integration for minified files

Automatic .htaccess serving logic

Already Considered

✅ Bundle vs. separate files → Separate files chosen (better for tree-shaking) ✅ Minify vs. uglify → Minify chosen (modern, preserves structure) ✅ Single bundle vs. per-file → Per-file chosen (flexibility)

📝 Summary

✅ Build scripts created for core and UI ✅ Package.json updated with new scripts ✅ Tested successfully - 63 files minified (6 core + 57 UI) ✅ 50-75% size reduction achieved ✅ Side-by-side deployment - both versions available ✅ Zero breaking changes - original files untouched

The build process is ready for production use! 🎉

Developers can now choose between development-friendly .mjs files and production-optimized .min.mjs files for any LARC component.