⚡ ColdBox Vite Helpers

🚀 Seamless Vite integration for ColdBox applications with automatic development/production mode switching.

📖 Introduction

This ColdBox module provides a powerful vite() helper function for loading assets generated by Vite and the coldbox-vite-plugin. It intelligently handles both development (hot reload) and production (manifest-based) modes automatically.

✨ Features

• 🔥 Hot Module Replacement - Automatic development mode detection
• 📦 Production Optimization - Manifest-based asset resolution with preloading
• 🎯 Smart Tag Generation - Automatic <script> and <link> tag creation
• ⚙️ Zero Configuration - Works out of the box with sensible defaults
• 🔧 Highly Configurable - Customize paths and behavior as needed
• 🚀 Performance Optimized - Preload tags and module loading support

📥 Installation

Install via CommandBox:

box install vite-helpers

🛠️ Usage

Basic Usage

In your ColdBox views, use the vite() helper to load your assets:

<!--- Load a single JavaScript entry point --->
#vite('resources/assets/js/app.js')#

<!--- Load a CSS file --->
#vite('resources/assets/css/app.css')#

<!--- Load multiple assets --->
#vite(['resources/assets/js/app.js', 'resources/assets/css/app.css'])#

Advanced Usage

<!--- Get asset paths without rendering tags --->
<cfset assetPaths = vite().getAssetPaths(['app.js', 'app.css']) />

<!--- Custom configuration --->
#vite()
    .setBuildDirectory('/custom/build')
    .setManifestFileName('custom-manifest.json')
    .render('app.js')#

🔄 How It Works

The module operates in two distinct modes:

🔥 Development Mode

• Trigger: When /includes/hot file exists
• Behavior: Assets served directly from Vite dev server
• Features: Hot module replacement, instant updates
• Example Output:

  <script type="module" src="http://127.0.0.1:5173/@vite/client"></script>
  <script type="module" src="http://127.0.0.1:5173/resources/assets/js/app.js"></script>

📦 Production Mode

• Trigger: When /includes/hot file doesn't exist
• Behavior: Assets resolved via Vite manifest
• Features: Preload tags, optimized loading, cache-busted filenames
• Example Output:

  <link rel="modulepreload" href="/includes/build/assets/app-5b5efed9.js" />
  <script type="module" src="/includes/build/assets/app-5b5efed9.js"></script>

⚙️ Configuration

Configure the module in your ModuleConfig.cfc or override in your main config/ColdBox.cfc:

// In your ModuleConfig.cfc or ColdBox.cfc
moduleSettings = {
    "vite-helpers" = {
        "hotFilePath"      : "/includes/hot",           // Hot reload detection file
        "buildDirectory"   : "/includes/build",         // Production build output
        "manifestFileName" : ".vite/manifest.json"     // Vite manifest file
    }
};

Configuration Options

Setting	Default	Description
hotFilePath	/includes/hot	🔥 Path to hot file that signals development mode
buildDirectory	/includes/build	📁 Directory where Vite outputs production assets
manifestFileName	.vite/manifest.json	📋 Vite's asset manifest file name

🏗️ Integration with coldbox-vite-plugin

This module is designed to work seamlessly with the coldbox-vite-plugin:

1. Install the Vite plugin in your frontend project:

   npm install coldbox-vite-plugin --save-dev

2. Configure your vite.config.js:

   import { defineConfig } from 'vite'
   import coldbox from 'coldbox-vite-plugin'
   
   export default defineConfig({
     plugins: [
       coldbox({
         input: ['resources/assets/js/app.js', 'resources/assets/css/app.css']
       })
     ]
   })

🧪 Development Workflow

🔥 Development Mode

1. Start your Vite dev server: npm run dev
2. The plugin creates the hot file automatically
3. Assets are served from http://127.0.0.1:5173
4. Enjoy hot module replacement! ⚡

📦 Production Mode

1. Build your assets: npm run build
2. Vite generates the manifest and assets
3. Remove or delete the hot file
4. Assets are served from your build directory

🧪 Testing

Run the test suite:

# Navigate to the test runner
box server start
# Then visit: http://localhost:{port}/tests/runner.cfm

# Or use TestBox CLI
box testbox run

📚 API Reference

Public Methods

getAssetPaths( entrypoints )

• Parameters: entrypoints (string|array) - Asset entry points to resolve
• Returns: Array of resolved asset paths
• Example:

  <cfset paths = vite().getAssetPaths(['app.js', 'app.css']) />

render( entrypoints )

• Parameters: entrypoints (string|array) - Asset entry points to render
• Returns: void (outputs HTML directly)
• Example:

  #vite().render('app.js')#

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development Setup

1. Fork and clone the repository
2. Install dependencies: box install
3. Make your changes
4. Run tests: box testbox run
5. Format code: box run-script format
6. Submit a pull request

📝 Changelog

See CHANGELOG.md for release history and updates.

👥 Authors

• Eric Peterson - Author - @elpete
• Luis Majano - Maintainer - @lmajano

🙏 Acknowledgments

• The Vite team for creating an amazing build tool
• The ColdBox community for continuous support and feedback
• All contributors who help improve this module

---

Made with ❤️ by the ColdBox Team