|
| 1 | +# Copilot Instructions for vite-helpers |
| 2 | + |
| 3 | +## Architecture Overview |
| 4 | +This ColdBox module provides seamless Vite integration through two operational modes: |
| 5 | +- **Development mode**: Assets served directly from Vite dev server when `/includes/hot` file exists |
| 6 | +- **Production mode**: Assets resolved via Vite manifest (`.vite/manifest.json`) in build directory |
| 7 | + |
| 8 | +The module automatically detects mode by checking for the "hot" file and switches behavior accordingly. |
| 9 | + |
| 10 | +## Core Components |
| 11 | +- `models/Vite.cfc`: Singleton service handling asset resolution, manifest parsing, and HTML tag generation |
| 12 | +- `includes/helpers.cfm`: Exposes global `vite()` function in views via ColdBox's applicationHelper |
| 13 | +- `ModuleConfig.cfc`: Configures default paths (`hotFilePath`, `buildDirectory`, `manifestFileName`) |
| 14 | + |
| 15 | +## Key Patterns |
| 16 | +- **Dual rendering modes**: `vite()` returns either hot server URLs or manifest-resolved paths |
| 17 | +- **Dependency injection**: Settings injected via `box:setting:*@vite-helpers` pattern |
| 18 | +- **Tag generation**: Automatic `<script>` and `<link>` tag creation with proper attributes (`type="module"`, preload links) |
| 19 | +- **Asset detection**: File extension regex determines CSS vs JS handling |
| 20 | + |
| 21 | +## Usage Examples |
| 22 | +```cfml |
| 23 | +<!-- Basic usage - outputs appropriate tags for current mode --> |
| 24 | +#vite('resources/assets/js/app.js')# |
| 25 | +
|
| 26 | +<!-- Returns array of asset paths without rendering --> |
| 27 | +#vite().getAssetPaths(['app.js', 'app.css'])# |
| 28 | +
|
| 29 | +<!-- Custom configuration --> |
| 30 | +#vite().setBuildDirectory('/custom/build').render('app.js')# |
| 31 | +``` |
| 32 | + |
| 33 | +## Testing Patterns |
| 34 | +- Tests in `tests/specs/unit/ViteHelperSpec.cfc` simulate both dev and prod modes |
| 35 | +- Use `fileWrite(hotFilePath, serverUrl)` to test dev mode |
| 36 | +- Use `fileWrite(manifestFilePath, serializeJSON(manifest))` to test prod mode |
| 37 | +- Tests verify exact HTML output including preload tags and module attributes |
| 38 | + |
| 39 | +## Development Workflow |
| 40 | +- **Format code**: `box run-script format` (uses cfformat) |
| 41 | +- **Run tests**: Navigate to `/tests/runner.cfm` or use TestBox CLI |
| 42 | +- **Debug**: Check for manifest file existence and hot file presence in asset resolution logic |
| 43 | + |
| 44 | +## Configuration Points |
| 45 | +Default settings (customizable in `ModuleConfig.cfc`): |
| 46 | +- `hotFilePath`: `/includes/hot` - signals dev mode when present |
| 47 | +- `buildDirectory`: `/includes/build` - where Vite outputs production assets |
| 48 | +- `manifestFileName`: `.vite/manifest.json` - Vite's asset manifest file |
0 commit comments