Appearance
Building assets
The website's JavaScript and styles are compiled from resources/ into ready-to-serve files in public/. You rebuild them after installing, after every update, and after changing any MIX_* value in .env.
Two bundles
The platform builds two separate bundles:
| Bundle | Built with | Output folder | Route file | Loaded for |
|---|---|---|---|---|
| Visitor | npm run user (webpack.user.mix.js) | public/frontend/ | resources/js/ziggy.js | Everyone without the admin role |
| Admin | npm run production (webpack.mix.js) | public/alternative/ | resources/js/ziggy_alternative.js | Accounts with the admin role, on every page |
Why two? The visitor bundle doesn't contain the admin panel's pages or the list of admin addresses, so ordinary visitors never download them.
Each bundle includes a route file generated by Ziggy, which lets the front-end build links to the platform's pages. The routes the server knows depend on USER_ASSETS in .env:
USER_ASSETS | Routes loaded | Used for |
|---|---|---|
"true" | Public site only (routes/web.php) | Generating the visitor route file |
"false" | Public site and admin panel (routes/admin.php) | Generating the admin route file, and normal running |
Leave USER_ASSETS="false" after building
The server only knows the admin panel's addresses when USER_ASSETS is "false". If a build stops halfway and leaves it at "true", /exchange-control-panel returns 404. Set it back to "false" and run php artisan config:clear (and php artisan route:clear if you cache routes).
Build for production
Run in the project folder, as the user that owns the files:
bash
npm ci
# Visitor bundle
sed -i '/^USER_ASSETS=/s/=.*/="true"/' .env
php artisan config:clear
php artisan ziggy:generate
npm run user
# Admin bundle
sed -i '/^USER_ASSETS=/s/=.*/="false"/' .env
php artisan config:clear
php artisan ziggy:generate resources/js/ziggy_alternative.js
npm run production
# Tell browsers to download the new files
sed -i '/^USER_ASSETS_HASH=/s/=.*/="'$(date +%s)'"/' .env
php artisan config:clearphp artisan config:clear makes sure the changed .env value is used. You only need it if you cache the configuration (php artisan config:cache), but it does no harm otherwise.
compile.sh
The project's compile.sh runs the same steps, but it also runs composer install and php artisan migrate -q without --force. On a production server, migrate needs --force. Without it, migrate asks for confirmation, and -q hides that question. Use the commands above, or the update procedure.
Cache-busting with USER_ASSETS_HASH
Every script and stylesheet is loaded with ?v=<USER_ASSETS_HASH> at the end of its address. Browsers and CDNs keep files for a long time. Changing the hash makes them all download the new version.
- Set it to a new value after every build. The build commands above use the current time.
- If users still see the old design after a deploy, the hash wasn't changed, or the configuration is cached. Run
php artisan config:clear.
Right-to-left languages
When a visitor uses Arabic, Hebrew, Persian or Urdu, pages are shown right-to-left (dir="rtl") and load mirrored stylesheets (*.rtl.css). The build creates these automatically with rtlcss, next to the normal files:
| Bundle | Normal | Right-to-left |
|---|---|---|
| Visitor | public/frontend/css/app.css, site.css | app.rtl.css, site.rtl.css |
| Admin | public/alternative/css/app.css, protected-file-….css | app.rtl.css, protected-file-….rtl.css |
The admin panel itself always stays left-to-right.
Themes and templates
Page templates live in resources/js/Themes/. The build looks for each template in Themes/prime first and falls back to Themes/default. To change a page's markup, edit (or add) its .template file under Themes/prime, then rebuild.
Styles for the visitor site are in resources/sass/ (site.scss and the Themes/prime folder, including the colour palettes).
Regenerate routes after updates
Whenever an update adds or renames pages, the route files must be regenerated, or links to new pages fail in the browser. The build steps above always do this. If you only want to regenerate them:
bash
sed -i '/^USER_ASSETS=/s/=.*/="true"/' .env && php artisan config:clear
php artisan ziggy:generate
sed -i '/^USER_ASSETS=/s/=.*/="false"/' .env && php artisan config:clear
php artisan ziggy:generate resources/js/ziggy_alternative.jsThen rebuild both bundles, because the route files are compiled into them.
When to rebuild
| You changed | Rebuild? |
|---|---|
| Settings in the admin panel (logo, colours, texts, fees) | No |
MIX_* values in .env (WebSocket host) | Yes, both bundles |
Other .env values | No. Run php artisan config:clear. |
Files in resources/js or resources/sass | Yes |
| Updated the platform | Yes, see Updating |
Build problems
| Problem | Fix |
|---|---|
JavaScript heap out of memory | Give Node more memory: export NODE_OPTIONS=--max-old-space-size=4096, then build again |
Build fails right after npm ci | Check node -v. Use Node.js 20. |
| New pages give "route not found" in the browser console | Regenerate the route files and rebuild |
| Admin panel returns 404 after a build | USER_ASSETS was left at "true". See the warning above. |
