Skip to content

README.md

Latest commit

 

History

History
206 lines (151 loc) · 6 KB

README.md

File metadata and controls

206 lines (151 loc) · 6 KB

⚡ ColdBox Vite Helpers

Version License

🚀 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

🙏 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