Frontend Guide
This guide explains the practical shape of Capell Frontend: how requests resolve, how cache behaviour works, how Tailwind inputs are aggregated, and which configuration points matter most in day-to-day site operations.
Request Flow
Section titled “Request Flow”A frontend request moves through site resolution, page resolution, layout selection, theme selection, and context building before Capell returns a response. The frontend package owns that request pipeline and the middleware around it.
If you need the step-by-step kernel view, use Page and site loading.
HTML Cache Behaviour
Section titled “HTML Cache Behaviour”When cache support is enabled, Capell can write rendered page output to public/page-cache. Later requests can then be served from cached HTML instead of re-rendering the whole page through PHP.
Use Server configuration to configure Apache or Nginx correctly. Without those rules, Capell still works, but you lose the direct static-file benefit.
Keep cached HTML boring. It should contain the same public page markup for anonymous users, signed-in non-admin users, and admins. Do not add in-page authoring attributes, hidden model IDs, field paths, labels, selectors, editor URLs, or package hints to Blade or theme output.
When capell-app/frontend-authoring is installed, the browser calls the beacon after the page has loaded. Only an authenticated admin beacon response may add edit controls or signed Filament editor URLs. This keeps unique/static HTML caching safe: the cache can serve the same file to everyone, and the editor appears only after the admin-only beacon says it should.
Core public components include stable styling hooks such as capell-component and a file-oriented modifier like capell-widgets-content, capell-page-results, or capell-media-index. These identify the public component family for theme CSS without exposing absolute template paths, model IDs, field paths, package locations, or admin authoring state.
Interactions follow the same rule. Public triggers may contain labels, generic runtime attributes, and encrypted target URLs, but they must not contain target widget data, widget keys, component names, package names, model IDs, block keys, field paths, or signed editor URLs. Lazy widget targets load through /_capell/widgets/{reference}. Layout Builder lazy fragments load through /_capell/fragments/{reference}.
Common operations when capell-app/html-cache is installed:
- regenerate all cached pages with
php artisan capell:static-site - regenerate one site with
php artisan capell:static-site --site=1 - clear cached HTML with
php artisan capell:html-cache:clear
Tailwind Asset Setup
Section titled “Tailwind Asset Setup”Capell aggregates Tailwind imports, plugins, and source globs across installed packages. That keeps the frontend build aligned with package views and components instead of forcing each package to manage CSS discovery on its own.
The detailed generator and registry rules live in Tailwind assets. The vendor CSS edge cases for local package work live in Tailwind vendor CSS.
Multi-Site Settings
Section titled “Multi-Site Settings”Two settings matter often during frontend setup:
capell-frontend.redirect_default_sitecapell-frontend.use_site_domain_for_urls
redirect_default_site controls whether unknown domains are redirected to the default enabled site domain. use_site_domain_for_urls switches URL generation to site-aware domains instead of the base app URL.
Site Checks
Section titled “Site Checks”Use the admin Site Health page when you need to verify that site, domain, and language resolution are behaving correctly. This is a useful first check after installation, a domain change, or a multi-site configuration update.