ColdBox Vite Plugin

Introduction

Vite is a modern frontend build tool that provides an extremely fast development environment and bundles your code for production.

This plugin integrates Vite with a ColdBox backend, handling:

• Dev-server URL injection so ColdBox can load hot-module-replacement assets.
• Asset manifest generation for cache-busted production builds.
• Full-page reload when ColdBox views, layouts, or routes change.
• Support for both the flat (traditional CFML/ColdBox) and BoxLang / tiered application layouts.

The CFML/BoxLang side of the integration is provided by the coldbox-vite ColdBox module, which reads the dev-server URL from the hot file and renders the appropriate <script> / <link> tags.

Requirements

| Dependency | Version | |---|---| | Node.js | ≥ 20.19 | | Vite | 3, 4, 5, 6, 7, or 8 |

Installation

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

Quick Start

Create vite.config.js in your project root:

import { defineConfig } from "vite";
import coldbox from "coldbox-vite-plugin";

export default defineConfig({
    plugins: [
        coldbox("resources/assets/js/app.js"),
    ],
});

Add these scripts to package.json:

"scripts": {
    "dev": "vite",
    "build": "vite build"
}

Then add the coldbox-vite module to your ColdBox app and call vite() from your layout to load the assets.

Layouts

ColdBox supports two directory structures. Choose the section that matches your project.

Flat Layout (Traditional ColdBox / CFML)

The web root is the project root. Handlers, views, and layouts live directly at the top level.

config/
├── ColdBox.cfc
├── Router.cfc
handlers/
views/
layouts/
includes/          ← built assets land here (web-accessible)
resources/
└── assets/
    ├── js/
    │   └── app.js
    └── css/
        └── app.css

vite.config.js:

import { defineConfig } from "vite";
import coldbox, { refreshPaths } from "coldbox-vite-plugin";

export default defineConfig({
    plugins: [
        coldbox({
            // publicDirectory defaults to "includes"
            input: [
                "resources/assets/css/app.css",
                "resources/assets/js/app.js",
            ],
            refresh: true,  // reloads on views/layouts/Router.cfc changes
        }),
    ],
});

Built assets are written to includes/build/. The hot file is at includes/hot.

Add to .gitignore:

/includes/build
/includes/hot

BoxLang / Tiered Layout

The web root is the public/ subdirectory. Application code lives under app/.

app/
├── config/
│   ├── ColdBox.bx
│   └── Router.bx
├── handlers/
├── layouts/
└── views/
public/            ← web root
└── includes/      ← built assets land here (web-accessible)
resources/
└── assets/
    ├── js/
    │   └── app.js
    └── css/
        └── app.css

vite.config.js:

import { defineConfig } from "vite";
import coldbox, { appRefreshPaths } from "coldbox-vite-plugin";

export default defineConfig({
    plugins: [
        coldbox({
            publicDirectory: "public/includes",
            input: [
                "resources/assets/css/app.css",
                "resources/assets/js/app.js",
            ],
            refresh: appRefreshPaths,  // reloads on app/views, app/layouts, app/config/Router.bx
        }),
    ],
});

Built assets are written to public/includes/build/. The hot file is at public/includes/hot.

Add to .gitignore:

/public/includes/build
/public/includes/hot

Configuration Reference

coldbox({
    input,             // required — entry point(s) to compile
    publicDirectory,   // default: "includes"
    buildDirectory,    // default: "build"
    ssr,               // SSR entry point(s); defaults to `input`
    ssrOutputDirectory,// default: "includes/build/ssr"
    refresh,           // default: false
})

| Option | Type | Default | Description | |---|---|---|---| | input | string \| string[] | — | Entry point path(s) relative to project root. Required. | | publicDirectory | string | "includes" | Directory where compiled assets are written. Use "public/includes" for the BoxLang/tiered layout. | | buildDirectory | string | "build" | Subdirectory inside publicDirectory for hashed build output. | | ssr | string \| string[] | input | Entry point(s) for the SSR bundle. | | ssrOutputDirectory | string | "includes/build/ssr" | Output directory for the SSR bundle. | | refresh | boolean \| string \| string[] \| RefreshConfig \| RefreshConfig[] | false | Trigger a full-page reload when matched files change. |

Full-Page Reload (refresh)

The refresh option wraps vite-plugin-full-reload. It accepts several forms:

// Disable (default)
refresh: false

// Use the built-in paths for your layout:
refresh: true          // flat layout — equivalent to refreshPaths
refresh: appRefreshPaths   // BoxLang/tiered layout

// Custom glob pattern
refresh: "app/views/**"

// Multiple patterns
refresh: ["app/views/**", "app/layouts/**"]

// Full control
refresh: {
    paths: ["app/views/**"],
    config: { delay: 300 },
}

// Multiple configurations
refresh: [
    { paths: ["app/views/**"], config: { delay: 300 } },
    { paths: ["app/config/**"] },
]

Exported path constants

import coldbox, { refreshPaths, appRefreshPaths } from "coldbox-vite-plugin";

// refreshPaths — for flat layout:
// ["layouts/**", "views/**", "config/Router.cfc"]

// appRefreshPaths — for BoxLang / tiered layout:
// ["app/layouts/**", "app/views/**", "app/config/Router.bx"]

Path Aliases

The plugin automatically registers an @ alias pointing to /resources/assets/js:

import MyComponent from "@/components/MyComponent.js";

Override it in vite.config.js if needed:

export default defineConfig({
    plugins: [coldbox("resources/assets/js/app.js")],
    resolve: {
        alias: {
            "@": "/resources/assets/ts",
        },
    },
});

SSR Configuration

import { defineConfig } from "vite";
import coldbox from "coldbox-vite-plugin";

export default defineConfig({
    plugins: [
        coldbox({
            input: "resources/assets/js/app.js",
            ssr: "resources/assets/js/ssr.js",
            ssrOutputDirectory: "includes/build/ssr",
        }),
    ],
});

Add separate build scripts to package.json:

"scripts": {
    "dev": "vite",
    "build": "vite build && vite build --ssr"
}

Inertia Integration

Use resolvePageComponent from the bundled helper to replace the legacy require() pattern:

import { createInertiaApp } from "@inertiajs/vue3";
import { resolvePageComponent } from "coldbox-vite-plugin/inertia-helpers";

createInertiaApp({
    resolve: (name) =>
        resolvePageComponent(
            `./Pages/${name}.vue`,
            import.meta.glob("./Pages/**/*.vue")
        ),
    setup({ el, app, props, plugin }) {
        createApp({ render: () => h(app, props) })
            .use(plugin)
            .mount(el);
    },
});

Environment Variables

| Variable | Description | |---|---| | ASSET_URL | CDN or absolute URL prefix prepended to asset paths in production. E.g. https://cdn.example.com. |

Set it in your .env file:

ASSET_URL=https://cdn.example.com

Built assets will be referenced as https://cdn.example.com/build/<hashed-file>.

Framework Integrations

Vue

import vue from "@vitejs/plugin-vue";

export default defineConfig({
    plugins: [
        coldbox("resources/assets/js/app.js"),
        vue(),
    ],
});

React

import react from "@vitejs/plugin-react";

export default defineConfig({
    plugins: [
        coldbox("resources/assets/js/app.jsx"),
        react(),
    ],
});

Note JavaScript files that contain JSX must use the .jsx extension.

Tailwind CSS

Install and configure PostCSS:

npx tailwindcss init -p

Import Tailwind in your CSS entry point:

@tailwind base;
@tailwind components;
@tailwind utilities;

Upgrading

See UPGRADE.md for migration instructions from ColdBox Elixir.

Contributing

Thank you for considering contributing to the ColdBox Vite plugin! Please open issues and pull requests on GitHub.

License

The ColdBox Vite plugin is open-sourced software licensed under the MIT license.