diff --git a/.eslintrc.js b/.eslintrc.js
deleted file mode 100644
index be0ca565..00000000
--- a/.eslintrc.js
+++ /dev/null
@@ -1,9 +0,0 @@
-module.exports = {
-    root: true,
-    env: {
-        node: true,
-    },
-    parser: "@typescript-eslint/parser",
-    plugins: ["@typescript-eslint"],
-    extends: ["eslint:recommended", "plugin:@typescript-eslint/recommended"],
-};
diff --git a/.github/workflows/codeql-analysis.yml b/.github/workflows/codeql-analysis.yml
index e6cff157..9138036f 100644
--- a/.github/workflows/codeql-analysis.yml
+++ b/.github/workflows/codeql-analysis.yml
@@ -1,67 +1,35 @@
-# For most projects, this workflow file will not need changing; you simply need
-# to commit it to your repository.
-#
-# You may wish to alter this file to override the set of languages analyzed,
-# or to provide custom queries or build logic.
-#
-# ******** NOTE ********
-# We have attempted to detect the languages in your repository. Please check
-# the `language` matrix defined below to confirm you have the correct set of
-# supported CodeQL languages.
-#
 name: codeql
 
 on:
   push:
     branches: [main]
   pull_request:
-    # The branches below must be a subset of the branches above
     branches: [main]
   schedule:
     - cron: "44 23 * * 1"
 
 jobs:
   analyze:
-    name: Analyze
+    name: Analyze (javascript)
     runs-on: ubuntu-latest
-
-    strategy:
-      fail-fast: false
-      matrix:
-        language: ["javascript"]
-        # CodeQL supports [ 'cpp', 'csharp', 'go', 'java', 'javascript', 'python' ]
-        # Learn more:
-        # https://docs.github.com/en/free-pro-team@latest/github/finding-security-vulnerabilities-and-errors-in-your-code/configuring-code-scanning#changing-the-languages-that-are-analyzed
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
 
-      # Initializes the CodeQL tools for scanning.
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@v1
+        uses: github/codeql-action/init@v3
         with:
-          languages: ${{ matrix.language }}
-          # If you wish to specify custom queries, you can do so here or in a config file.
-          # By default, queries listed here will override any specified in a config file.
-          # Prefix the list here with "+" to use these queries and those in the config file.
-          # queries: ./path/to/local/query, your-org/your-repo/queries@main
+          languages: javascript
 
-      # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
-      # If this step fails, then you should remove it and run the build manually (see below)
       - name: Autobuild
-        uses: github/codeql-action/autobuild@v1
-
-      # ℹ️ Command-line programs to run using the OS shell.
-      # 📚 https://git.io/JvXDl
-
-      # ✏️ If the Autobuild fails above, remove it and uncomment the following three lines
-      #    and modify them (or add more) to build your code if your project
-      #    uses a compiled language
-
-      #- run: |
-      #   make bootstrap
-      #   make release
+        uses: github/codeql-action/autobuild@v3
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@v1
+        uses: github/codeql-action/analyze@v3
+        with:
+          category: "/language:javascript"
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
index 8844bef5..d8490b7c 100644
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@@ -12,14 +12,14 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [14.x, 16.x, 18.x]
+        node-version: [20.x, 22.x]
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Use Node.js ${{ matrix.node-version }}
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node-version }}
 
diff --git a/README.md b/README.md
index ba33dac0..5d77b225 100644
--- a/README.md
+++ b/README.md
@@ -9,15 +9,389 @@
 
 [Vite](https://vitejs.dev) is a modern frontend build tool that provides an extremely fast development environment and bundles your code for production.
 
-This plugin configures Vite for use with a [ColdBox](https://www.coldbox.org/) backend server.
+This plugin integrates Vite with a [ColdBox](https://www.coldbox.org/) backend, handling:
 
-## Official Documentation
+- 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.
 
-TODO: Write gitbook and link it here.
+The CFML/BoxLang side of the integration is provided by the [**coldbox-vite** ColdBox module](https://www.forgebox.io/view/coldbox-vite), 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
+
+```bash
+npm install --save-dev vite coldbox-vite-plugin
+```
+
+---
+
+## Quick Start
+
+Create `vite.config.js` in your project root:
+
+```js
+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`:
+
+```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`**:
+
+```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`:
+
+```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`**:
+
+```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`:
+
+```gitignore
+/public/includes/build
+/public/includes/hot
+```
+
+---
+
+## Configuration Reference
+
+```js
+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](https://github.com/ElMassimo/vite-plugin-full-reload). It accepts several forms:
+
+```js
+// 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
+
+```js
+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`:
+
+```js
+import MyComponent from "@/components/MyComponent.js";
+```
+
+Override it in `vite.config.js` if needed:
+
+```js
+export default defineConfig({
+    plugins: [coldbox("resources/assets/js/app.js")],
+    resolve: {
+        alias: {
+            "@": "/resources/assets/ts",
+        },
+    },
+});
+```
+
+---
+
+## SSR Configuration
+
+```js
+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`:
+
+```json
+"scripts": {
+    "dev": "vite",
+    "build": "vite build && vite build --ssr"
+}
+```
+
+---
+
+## Inertia Integration
+
+Use `resolvePageComponent` from the bundled helper to replace the legacy `require()` pattern:
+
+```js
+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:
+
+```env
+ASSET_URL=https://cdn.example.com
+```
+
+Built assets will be referenced as `https://cdn.example.com/build/<hashed-file>`.
+
+---
+
+## Framework Integrations
+
+### Vue
+
+```js
+import vue from "@vitejs/plugin-vue";
+
+export default defineConfig({
+    plugins: [
+        coldbox("resources/assets/js/app.js"),
+        vue(),
+    ],
+});
+```
+
+### React
+
+```js
+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:
+
+```bash
+npx tailwindcss init -p
+```
+
+Import Tailwind in your CSS entry point:
+
+```css
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+```
+
+---
+
+## Upgrading
+
+See [UPGRADE.md](UPGRADE.md) for migration instructions from ColdBox Elixir.
+
+---
 
 ## Contributing
 
-Thank you for considering contributing to the ColdBox Vite plugin!
+Thank you for considering contributing to the ColdBox Vite plugin! Please open issues and pull requests on [GitHub](https://github.com/ColdBox/coldbox-vite-plugin).
+
+---
 
 ## License
 
diff --git a/eslint.config.js b/eslint.config.js
new file mode 100644
index 00000000..0079ded2
--- /dev/null
+++ b/eslint.config.js
@@ -0,0 +1,26 @@
+import tseslint from "@typescript-eslint/eslint-plugin";
+import tsparser from "@typescript-eslint/parser";
+
+export default [
+    {
+        files: ["src/**/*.ts", "tests/**/*.ts"],
+        languageOptions: {
+            parser: tsparser,
+            parserOptions: {
+                ecmaVersion: 2020,
+                sourceType: "module",
+            },
+            globals: {
+                process: "readonly",
+                __dirname: "readonly",
+                __filename: "readonly",
+            },
+        },
+        plugins: {
+            "@typescript-eslint": tseslint,
+        },
+        rules: {
+            ...tseslint.configs.recommended.rules,
+        },
+    },
+];
diff --git a/package.json b/package.json
index 8ac7f7ed..6a62c93a 100644
--- a/package.json
+++ b/package.json
@@ -1,7 +1,8 @@
 {
     "name": "coldbox-vite-plugin",
-    "version": "3.0.2",
+    "version": "4.0.0",
     "description": "ColdBox plugin for Vite.",
+    "type": "module",
     "keywords": [
         "coldbox",
         "vite",
@@ -38,24 +39,24 @@
         "build-plugin-cjs": "esbuild src/index.ts --platform=node --format=cjs --outfile=dist/index.cjs --define:import.meta.url=import_meta_url --inject:./import.meta.url-polyfill.js",
         "build-plugin-esm": "esbuild src/index.ts --platform=node --format=esm --outfile=dist/index.mjs",
         "build-inertia-helpers": "rm -rf inertia-helpers && tsc --project tsconfig.inertia-helpers.json",
-        "lint": "eslint --ext .ts ./src ./tests",
+        "lint": "eslint src tests",
         "test": "vitest run"
     },
     "devDependencies": {
         "@types/node": "^22.13.10",
         "@typescript-eslint/eslint-plugin": "^8.27.0",
         "@typescript-eslint/parser": "^8.27.0",
-        "esbuild": "0.25.1",
+        "esbuild": "^0.28.0",
         "eslint": "^9.22.0",
         "typescript": "^5.8.2",
-        "vite": "^6.2.2",
+        "vite": "^8.0.0",
         "vitest": "^3.0.9"
     },
     "peerDependencies": {
-        "vite": "^3.0.0 || ^4.0.0 || ^5.0.0 || ^6.0.0"
+        "vite": "^3.0.0 || ^4.0.0 || ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0"
     },
     "engines": {
-        "node": ">=18"
+        "node": ">=20.19.0"
     },
     "dependencies": {
         "picocolors": "^1.1.1",
diff --git a/src/index.ts b/src/index.ts
index 1620a17a..05f93e95 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -8,12 +8,31 @@ import {
     loadEnv,
     UserConfig,
     ConfigEnv,
-    Manifest,
     ResolvedConfig,
     SSROptions,
     normalizePath,
     PluginOption,
 } from "vite";
+
+type ManifestEntry = {
+    file: string;
+    src?: string;
+    isEntry?: boolean;
+    imports?: string[];
+    css?: string[];
+};
+type Manifest = Record<string, ManifestEntry>;
+
+/** Vite augments Rollup's OutputChunk with importedCss metadata. */
+interface ViteChunk {
+    isEntry: boolean;
+    facadeModuleId: string | null;
+    fileName: string;
+    viteMetadata?: {
+        importedCss: Set<string>;
+    };
+}
+
 import fullReload, {
     Config as FullReloadConfig,
 } from "vite-plugin-full-reload";
@@ -75,8 +94,16 @@ type DevServerUrl = `${"http" | "https"}://${string}:${number}`;
 
 let exitHandlersBound = false;
 
+/** Refresh paths for the flat ColdBox layout (web root = project root). */
 export const refreshPaths = ["layouts/**", "views/**", "config/Router.cfc"];
 
+/** Refresh paths for the BoxLang / tiered ColdBox layout (app/ sub-directory). */
+export const appRefreshPaths = [
+    "app/layouts/**",
+    "app/views/**",
+    "app/config/Router.bx",
+];
+
 /**
  * ColdBox plugin for Vite.
  *
@@ -247,7 +274,7 @@ function resolveColdBoxPlugin(
 
         // The following two hooks are a workaround to help solve a "flash of unstyled content".
         // They add any CSS entry points into the manifest because Vite does not currently do this.
-        renderChunk(_, chunk : any) {
+        renderChunk(_, chunk: ViteChunk) {
             const cssLangs = `\\.(css|less|sass|scss|styl|stylus|pcss|postcss)($|\\?)`;
             const cssLangRE = new RegExp(cssLangs);
 
@@ -267,7 +294,7 @@ function resolveColdBoxPlugin(
                 /* eslint-disable-next-line @typescript-eslint/ban-ts-comment */
                 /* @ts-ignore */
                 file:
-                    Array.from(chunk.viteMetadata.importedCss)[0] ??
+                    Array.from(chunk.viteMetadata?.importedCss ?? [])[0] ??
                     chunk.fileName,
                 src: relativeChunkPath,
                 isEntry: true,
@@ -431,7 +458,12 @@ function resolveOutDir(
 }
 
 /**
- * Resolve the Vite manifest config from the configuration.
+ * Resolve the Vite manifest path from the resolved config.
+ *
+ * Vite 5+ writes the manifest to `.vite/manifest.json` when `manifest: true`,
+ * but Vite resolves the boolean to the actual filename before storing it in
+ * `resolvedConfig`. Reading from `resolvedConfig` gives us the correct path
+ * across all supported Vite versions.
  */
 function resolveManifestConfig(config: ResolvedConfig): string | false {
     const manifestConfig = config.build.ssr
@@ -442,8 +474,10 @@ function resolveManifestConfig(config: ResolvedConfig): string | false {
         return false;
     }
 
+    // Vite resolves `true` to the actual filename in resolvedConfig.
+    // Fall back to sensible defaults only when it is still a boolean (older Vite).
     if (manifestConfig === true) {
-        return config.build.ssr ? "ssr-manifest.json" : "manifest.json";
+        return config.build.ssr ? ".vite/ssr-manifest.json" : ".vite/manifest.json";
     }
 
     return manifestConfig;
diff --git a/tests/index.test.ts b/tests/index.test.ts
index d2d440d8..48b2de7e 100644
--- a/tests/index.test.ts
+++ b/tests/index.test.ts
@@ -1,5 +1,5 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
-import coldbox from "../src";
+import coldbox, { refreshPaths, appRefreshPaths } from "../src";
 import { resolvePageComponent } from "../src/inertia-helpers";
 
 describe("coldbox-vite-plugin", () => {
@@ -403,6 +403,53 @@ describe("coldbox-vite-plugin", () => {
             config: { delay: 123 },
         });
     });
+
+    it("exports refreshPaths for flat layout", () => {
+        expect(refreshPaths).toEqual([
+            "layouts/**",
+            "views/**",
+            "config/Router.cfc",
+        ]);
+    });
+
+    it("exports appRefreshPaths for BoxLang / tiered layout", () => {
+        expect(appRefreshPaths).toEqual([
+            "app/layouts/**",
+            "app/views/**",
+            "app/config/Router.bx",
+        ]);
+    });
+
+    it("configures full reload with appRefreshPaths for BoxLang layout", () => {
+        const plugins = coldbox({
+            input: "resources/assets/js/app.js",
+            refresh: appRefreshPaths,
+        });
+
+        expect(plugins.length).toBe(2);
+        /** @ts-ignore */
+        expect(plugins[1].__coldbox_plugin_config).toEqual({
+            paths: appRefreshPaths,
+        });
+    });
+
+    it("supports BoxLang / tiered layout with public/includes publicDirectory", () => {
+        const plugin = coldbox({
+            input: "resources/assets/js/app.js",
+            publicDirectory: "public/includes",
+        })[0];
+
+        const config = plugin.config(
+            {},
+            { command: "build", mode: "production" }
+        );
+        expect(config.base).toBe("/build/");
+        expect(config.build.manifest).toBe(true);
+        expect(config.build.outDir).toBe("public/includes/build");
+        expect(config.build.rollupOptions.input).toBe(
+            "resources/assets/js/app.js"
+        );
+    });
 });
 
 describe("inertia-helpers", () => {