FOSSBilling/frontend/README.md

Frontend and Theme Builds

FOSSBilling builds shared browser assets from frontend/ and theme assets from each theme workspace.

Build Commands

• npm run build checks frontend source, builds core assets, and builds all themes.
• npm run build:production runs the same build with NODE_ENV=production.
• npm run check runs lightweight JavaScript syntax checks and validates theme icon manifests.
• npm run build-admin_default and npm run build-huraga build a single theme.

Generated assets are written to src/public/assets and src/themes/**/assets/build. These paths are ignored by Git and are copied into release artifacts by the Docker build.

Admin widget regression tests use isolated browser fixtures and require no application database or admin credentials. Build production assets first so the tests cover purged CSS:

npm run build:production
npx playwright test tests/E2E/Playwright/specs/admin/tabler-widgets.spec.ts

Theme Dependencies

Themes own the UI packages they consume. Shared tooling in frontend/tools can help compile assets, generate sprites, and post-process CSS, but it should not make a theme depend on a specific UI package.

Examples (the shipped default theme package bundles both — src/themes/default/admin and src/themes/default/client; their npm workspace package names, admin_default and huraga, are unrelated to their directory paths):

• admin_default (src/themes/default/admin) owns Tabler, Coloris, Chart.js, Vanilla Calendar Pro, Tom Select, Flag Icons, and its Tabler icon package.
• huraga (src/themes/default/client) owns Bootstrap, Tom Select, Flag Icons, and its Tabler icon package.
• svg-sprite is a root development dependency because the shared sprite helper imports it.

The admin theme uses Tabler's component bundle and data-bs-* APIs. Do not load Bootstrap's JavaScript alongside it. The tabler global exposes the bundle; bootstrap remains a compatibility alias for extensions.

When using admin components:

• Keep .datepicker, YYYY-MM-DD, and data-name-from / data-name-to for API date fields. The datepicker adapter loads Vanilla Calendar Pro and synchronizes range values within each form.
• Use the clipboard adapter to retain copy support on HTTP and when Clipboard API access is denied.
• Use partial_password_strength.html.twig for translated password feedback; server-side validation remains authoritative.
• Use data-bs-toggle="autosize" for plain-text notes, not CKEditor fields. Growth is capped at 24rem.

Icons

Theme icon sprites are generated from each theme's icon-manifest.json.

• Add static SVG icon usage to the relevant theme manifest.
• Mark icons as "dynamic": true when the icon name is resolved at runtime, such as admin navigation icons from module metadata.
• Put theme-specific SVG files in the theme's custom-icons directory.
• Reference generated symbols with inline sprite IDs, for example <use href="#home" />.

Run npm run check-icons before changing icon usage.

CSS

Theme vendor CSS belongs in src/themes/**/assets/css/vendor.css. Theme-specific styles belong in the theme Sass entrypoint. Rules that are genuinely identical across the default admin and client themes belong in frontend/styles/_shared-theme.scss instead of being duplicated.

Load Tom Select's base preset before tabler-vendors.css so Tabler's sizing, validation, focus, and theme styles take precedence. Avoid fixed input heights.

Use form-text for admin form help text, preserve visible keyboard focus indicators, and use color tokens with color-mix() instead of deprecated RGB tokens.

PurgeCSS runs only for production builds. A PurgeCSS failure fails production builds so release CSS problems are caught early. Preserve selectors generated by runtime components, including the calendar's data-vc-* states.