# Solution Design ## Goals - Enable npm-based third-party JavaScript libraries (e.g., Syncfusion) in BuyerKiosk. - Keep all existing legacy scripts working unchanged (hybrid loading). - Provide a clean path for new features to ship as bundled ES modules. - Avoid FOUC by ensuring Vite-produced CSS loads in ``. - Support local development with optional HMR (dev-server mode). ## Non-Goals - Migrating legacy scripts into the bundler in this phase. - Replacing the existing CSS pipeline (`conductor`) in this phase. - Requiring Node.js/npm on production servers (build artifacts are committed). --- ## Directories - **Module source directory:** `resources/js/` (not web-accessible). - **Production output directory:** `public_html/js/dist/` (committed artifacts). --- ## Deployment Model: Committed Artifacts ### Rationale Because there is no concrete CI build pipeline today, the simplest reliable approach is to commit build outputs: - Production deploys do not need Node.js/npm. - Rollbacks are deterministic (assets roll back with code). - Fewer moving parts during deploy. ### Rules - `package.json` and `package-lock.json` are committed. - `public_html/js/dist/` build artifacts are committed. - `node_modules/` is never committed (gitignored). - Vite caches (e.g., `.vite/`) are never committed (gitignored). - Builds must remove stale files from `public_html/js/dist/` before writing new output (prevents orphaned bundles referenced nowhere but lingering in git/deploys). ### Failure Modes + Mitigations - “Forgot to rebuild”: mitigation is a deploy-time or pre-merge check that `manifest.json` exists and referenced files exist. - Repo growth over time: mitigate by keeping the number of entry points small and periodically pruning obsolete dist files. --- ## Asset Injection Strategy (Avoid FOUC) ### Conventions - **CSS:** Include Vite-generated CSS in `` to prevent FOUC. - **JS:** Include Vite entry scripts near the end of `` (workspace footer pattern) to preserve expected ordering with legacy scripts and avoid surprising early execution. ### Twig Helper Surface Use two helpers to match the HTML loading norms: - `vite_styles(entry)` for `` (emits `` tags) - `vite_scripts(entry)` for end-of-body (emits `