Frontend Optimizer

Frontend Optimizer

Profile-based CSS and JavaScript delivery for public Capell pages.

At A Glance

• Package: capell-app/frontend-optimizer
• Namespace: Capell\FrontendOptimizer\
• Surfaces: frontend Blade directive, queue, database
• Service providers: packages/frontend-optimizer/src/Providers/FrontendOptimizerServiceProvider.php
• Capell dependencies: capell-app/core, capell-app/frontend
• Third-party dependencies: lorisleiva/laravel-actions, spatie/laravel-data, spatie/laravel-package-tools, symfony/process

Why It Helps Your Capell Workflow

• Provides profile-based CSS and JavaScript delivery so Capell frontend performance can improve without rewriting themes.
• Helps owners keep pages lean as optional packages add assets, widgets, and render profiles.
• Gives developers manifest, critical CSS, and render-profile surfaces for package-aware asset loading.

Best Used With

• Foundation Theme
• HTML Cache
• Frontend Authoring

What It Adds

• Profile-based CSS and JavaScript delivery for public Capell pages.
• @frontendOptimizerAssets(...) Blade directive for rendering resolved profile assets.
• Render profile storage and critical CSS generation support.
• No direct Filament admin surface or public route.

Code Map

Runtime Surface

• Blade directive: @frontendOptimizerAssets(...).
• Jobs: GenerateCriticalCssJob.
• Critical CSS generation uses the configured process runner; keep failures visible in optimization run records rather than hiding them in Blade output.

Data And Persistence

• Models: FrontendOptimizationRun, FrontendRenderProfile.
• Migrations: 2026_05_10_190851_01_create_frontend_optimizer_tables.php.
• Config: packages/frontend-optimizer/config/capell-frontend-optimizer.php.
• Data objects live in src/Data/; use them for payloads, form state, and view models.

Extension Points

• Contracts: CriticalCssGenerator.
• Register Capell extension points, routes, migrations, settings, render hooks, and resources from service providers.

Install And Setup

• Install with composer require capell-app/frontend-optimizer in the host Capell application.
• Run migrations through the host application package install flow.
• In this repository, verify package changes with vendor/bin/pest; do not use php artisan.

Docs

• docs index
• overview.md
• assets-and-render-profiles.md
• critical-css.md
• screenshots.json

Testing

Run package tests from the repository root:

vendor/bin/pest packages/frontend-optimizer/tests --configuration=phpunit.xml

Maintenance Notes

• Put behaviour changes in src/Actions/; UI classes, commands, and controllers should call actions instead of owning domain logic.
• Use package Data classes at boundaries instead of passing anonymous arrays between layers.
• Use backed enums for persisted values and enum labels for Filament options.

Frontend Optimizer Overview

Frontend Optimizer records render profiles for public Capell pages and renders profile-aware CSS and JavaScript assets through the @frontendOptimizerAssets(...) Blade directive.

Use it when a site needs deterministic asset delivery per layout, widget set, site, locale, or theme context without hard-coding frontend bundles into theme views.

What It Adds

• @frontendOptimizerAssets(...) for rendering the resolved asset profile.
• Critical CSS generation through CriticalCssGenerator, backed by Playwright by default.
• Extension settings for viewports, fold depth, generation behavior, and inline-size limits.
• A page type opt-out for pages that should not run above-the-fold CSS generation.
• Render profile actions for resolving, preparing, persisting, and storing profile manifests.
• frontend_render_profiles and frontend_optimization_runs tables.

Install Impact

• Requires capell-app/core and capell-app/frontend.
• Adds one migration file that creates render profile and optimization run storage.
• Registers extension settings and a page type configurator for critical CSS controls.
• Frontend output is visible only where a theme or frontend view calls the Blade directive.

Admin Surfaces

• Extension settings are registered through FrontendOptimizerSettings and FrontendOptimizerSettingsSchema.
• Page type critical CSS opt-out is registered through FrontendOptimizerPageTypeConfigurator.

Frontend Surfaces

Demo Setup

Install the core baseline plus capell-app/frontend-optimizer, run migrations through the host app, seed or render at least one public page, then capture the public page HTML around the @frontendOptimizerAssets(...) output. A useful screenshot requires a theme fixture that actually calls the directive.

Screenshot Coverage

The package needs screenshot coverage for asset output, not for admin navigation. Captures should include the public page and enough response/source inspection to prove the expected profile assets were emitted.

The screenshot runner contract is defined in screenshots.json. The two required captures and their dark-mode variants are committed under docs/screenshots/, but they are not promoted in capell.json marketplace media until they show optimizer-specific profile asset and critical CSS output.

Known Risks

• Empty screenshots are likely unless the demo theme calls the directive.
• Playwright-backed critical CSS generation depends on the host runtime and browser availability.
• Asset profile keys vary by render context; demo data should state the site, locale, layout, and theme used for capture.
• Critical CSS generation should use a representative public URL for the profile; using an unusual page for a shared layout can produce a less useful above-the-fold subset.
• Critical CSS generation completion invalidates through the frontend cache registry without importing HTML Cache internals. The invalidation is intentionally broad today because render profiles do not record exact cached URL coverage.

Related Guides

• Critical CSS
• Assets And Render Profiles

Verification

Run package tests from the repository root:

vendor/bin/pest packages/frontend-optimizer/tests --configuration=phpunit.xml