Frontend
Capell Frontend resolves public requests and renders published pages. It owns site/page loading, layout/theme context, frontend settings, cache-aware rendering, public HTML safety, and package-facing frontend hooks.
Status: Available · Package: capell-app/frontend
Request Flow
Section titled “Request Flow”- Resolve the current site from the request host and configured fallback rules.
- Resolve the language and page URL for that site.
- Load the page, layout, theme, page type, translations, and render variables before Blade receives the view.
- Render the public page through frontend components, render hooks, media helpers, and registered assets.
- Apply cache headers, ETags, static cache integration, and minification when configured.
Public Blade views should receive hydrated render data. Do not query models, lazy-load relationships, or fetch package state from public views.
Public HTML Safety
Section titled “Public HTML Safety”Anonymous users, signed-in non-admin users, crawlers, cached HTML, and static exports must never receive authoring markers, model IDs, field paths, permissions, package names, selectors, signed editor URLs, or editor scripts.
In-page editing belongs to capell-app/frontend-authoring. It decorates the page only after an authenticated admin beacon response.
Use the public HTML safety contract when changing rendering, themes, cache output, render hooks, or frontend package views.
Main Extension Points
Section titled “Main Extension Points”| Need | Use |
|---|---|
| Inject public HTML | RenderHookRegistry::register(RenderHookLocation::..., ...). |
| Register frontend widgets | WidgetRegistry::register($name, WidgetTarget::FrontendBlade, $component). |
| Register Livewire frontend widgets | WidgetRegistry::register($name, WidgetTarget::FrontendLivewire, $component). |
| Add CSS/JS source paths | TailwindAssetsRegistry::registerSource(...) and registerImport(...). |
| Invalidate pages for model changes | CacheInvalidationRegistry::registerDependency(...). |
| Render media safely | Use the Capell media helpers/components and pass localized alt text from prepared data. |
Render hooks are for small, safe additions. If a package needs a major page region, add an explicit frontend component or package view instead of hiding large behavior in a hook.
Server Setup
Section titled “Server Setup”Capell works through Laravel routes without web-server rewrites. For static HTML cache performance, configure Nginx or Apache to check generated cache files before PHP and to fall back to Laravel when no cache file exists.
Keep these rules in deploy docs, not inside themes:
- static cache directory is served as ordinary public HTML
- PHP fallback still works when cache files are missing or stale
- lockdown/maintenance responses must bypass stale static pages
- cache files must stay safe for anonymous visitors
Frontend Assets
Section titled “Frontend Assets”Packages should register Tailwind sources and imports in PHP registration code. Do not ask app developers to manually copy package paths into every project unless the package genuinely cannot register itself.
For local package development, unresolved vendor CSS imports usually mean Vite cannot resolve a symlinked dependency. Run the package-owned asset report command when available, then install missing npm dependencies or add a narrow Vite alias.
Testing
Section titled “Testing”Use focused tests around frontend behavior:
- route resolves the expected site/page/language
- public responses contain expected content
- anonymous/non-admin HTML does not contain authoring controls or internal identifiers
- cache headers and ETags match the configured behavior
- render hooks add only the intended HTML
- public Blade does not rely on lazy-loaded relationships
For public-output safety, assert absence as well as presence.
Use sinnbeck/laravel-dom-assertions when the element, region, attribute, or repeated component count matters. App/theme tests can request seeded public pages directly; package tests can use factories when they need to own the fixture. The frontend package guide has copy-pasteable examples.
Read Next
Section titled “Read Next”| Need | Read |
|---|---|
| Understand the render pipeline | Frontend guide |
| Resolve site/page/language loading | Page and site loading |
| Configure server fallback and static cache rules | Server config |
| Register render hooks | Render hooks |
| Register package Tailwind assets | Tailwind assets |
| Render media safely | Media rendering |
| Add frontend widgets | Widgets |
| Build interactive widget and fragment targets | Capell Interactions |
| Support Blaze templates | Blaze support |
| Test public output | Frontend testing |
| Debug public output or cache bypasses | Debugging public output |
Optional Frontend Features
Section titled “Optional Frontend Features”| Feature | Package |
|---|---|
| Default frontend theme | capell-app/foundation-theme |
| In-page authoring | capell-app/frontend-authoring |
| XML sitemaps and discovery pages | capell-app/site-discovery |
| SEO metadata and audits | capell-app/seo-suite |
| Static HTML cache | capell-app/html-cache |
| Site search | capell-app/search |
Use Operations for production cache and stale-output troubleshooting.