# Implementation Plan This plan assumes the “committed artifact” deployment model described in `solution-design.md`. ## Phase 1: Scaffolding - Add `package.json` and update/regenerate `package-lock.json` (a lockfile currently exists without a `package.json`). - Add `vite.config.js` with: - Output to `public_html/js/dist/` - Manifest generation enabled - Multiple entry support (as needed) - Use `resources/js/` as the module source directory and define initial entry naming conventions (one entry per feature/page). - Update `.gitignore` to ignore `node_modules/` (and any local Vite cache directories), but not the committed dist output. ## Phase 2: Asset Helper + Template Convention - Implement a PHP manifest reader + Twig extension. - Add two Twig helpers: - `vite_styles(entry)` to be used in `` - `vite_scripts(entry)` to be used in footer/end-of-body - Ensure helper supports: - Production: manifest-based hashed assets - Dev: optional dev-server URLs when explicitly enabled - Clear errors when manifest/entry is missing - Decide and document the exact template insertion points for `vite_styles(...)` (head) and `vite_scripts(...)` (footer) to guarantee “CSS first, JS later” and avoid FOUC. - Workspace pages: `userfrosting/templates/themes/default/workspace/layouts/workspace-head.html` and `userfrosting/templates/themes/default/workspace/layouts/workspace-foot.html` - Other themes/layouts as needed (mirror the same “styles in head, scripts at end-of-body” pattern) ## Phase 3: Committed Artifact Workflow - Ensure `npm run build` clears `public_html/js/dist/` before writing (prevents stale committed artifacts). - Document “when to rebuild” rules and what files must be committed. - Add a deploy-time “dist present” check to fail fast if artifacts are missing. ## Phase 4: First Real Entry - Add a small “hello bundle” entry and wire it into a safe template location to validate: - Module execution ordering with legacy scripts - CSS extraction + head injection (no FOUC) - Manifest helper correctness - Add a second entry for a realistic target (e.g., Syncfusion bootstrap) once the “hello bundle” proves the plumbing.