Filament Bladewind Laravel Package

Getting Started

BladeWind 3.0.2 is a drop-in performance release: no API or config changes are called out, so upgrading is a composer update and (for a Filament panel) a page reload. Do that first, then confirm the win before touching anything else.

1. Upgrade and measure. Hit a panel page and a Livewire-driven page twice — once cold, once warm. Pre-3.0.2 you were paying ~120 ms (theme split) + ~20 ms (JS scan) on every page, and ~270 ms (rule index) on every Livewire update that rendered HTML. Warm, those should now be ~4.5 / 10 / 5 ms. If you don't see the drop, your cache store is almost certainly the reason (see Gotchas).
2. Find the cache config. Look in config/bladewind.php for the store/driver and any TTL knob. The package now writes "one key each" to your cache store — theme split, rule index, runtime-token scan — so the store is now part of your runtime dependency graph, not just a session/queue detail.
3. First real use case: point it at your Filament theme CSS and confirm the three keys appear in the store after one page load (php artisan tinker → Cache::get(...), or redis-cli --scan --pattern '*bladewind*'). Seeing those keys is the fastest proof the upgrade took effect.

If you were running this under Octane before, treat 3.0.2 as a behaviour change worth a smoke test, not just a speed-up — see Gotchas.

Implementation Patterns

Pick a real, shared cache store in production. The whole release hinges on the cache being reachable and persistent across requests. file works on a single box; multi-server or autoscaled setups need Redis/Memcached/DynamoDB, otherwise every node rebuilds independently and you keep paying the cold cost per node.

Warm on deploy, not on first visitor. After php artisan optimize / route caching, hit one representative panel page and one Livewire-heavy page as part of your deploy script (a curl against a health-ish route is enough). That turns a ~440 ms cold page into a warm one for the first real user, and it prevents a thundering herd of workers all building the same index simultaneously.

Rely on the invalidation, don't hand-roll it. The split and index key off the theme's content hash; the JS scan keys off the scripts' modification times. Editing your theme or republishing Filament assets invalidates automatically. Don't add your own Cache::forget calls around theme edits — you'll just race the hash check and cause redundant rebuilds.

Use the fast path as a design signal. An update that renders no class the page lacks now returns before touching the index. That makes the common Livewire interaction essentially free, but it also means the cost profile is dominated by pages that introduce new classes. Batch-y UI (filters, tabs, modals revealing new utility sets) is cheap; a component that mints a fresh arbitrary-value class on every keystroke is not.

Keep class names static where you can. Prefer a match/array map over string interpolation for dynamic variants (text-[{{ $size }}] style constructs defeat the index and the fast path alike). Where you genuinely need dynamic utilities, safelist them so they're known at build time rather than discovered at render time.

Disable or swap the store in tests. Because the cache is now load-bearing, tests that assert on rendered classes can become order- and store-dependent. Point the package at the array store (or its enable flag, if present) in phpunit.xml so each test starts clean rather than inheriting a warm index from a previous test or a stale one from your dev cache.

Under Octane, re-verify. Previously the memoisation was per PHP process, which under Octane meant per worker — a deploy could leave a worker serving the old split until it recycled. The content-hash keying fixes that, but it's a change in staleness semantics: confirm a theme edit is picked up without a worker restart, because your deploy runbook may have been written around the old behaviour.

Gotchas and Tips

• php artisan cache:clear is now a performance event, not a no-op. It discards the split, the index and the scan, so the next few requests pay the full cold cost. Avoid it in deploy hooks that run after traffic is shifted; if you must clear, re-warm immediately after.
• Container mtimes are the sharp edge. The JS scan invalidates on script modification times. Reproducible builds (and COPY in Dockerfiles) often produce fresh mtimes on every deploy, so you'll see one rebuild per release — fine. The bad case is inconsistent mtimes across nodes sharing one Redis: two nodes disagree, each invalidates the other's entry, and you thrash. Normalise asset mtimes in the image, or accept that the scan rebuilds once per node.
• Old keys accumulate. One key per theme content hash means every theme edit leaves the previous entry behind until it's evicted. Set a TTL on the store (or on the package's keys if it exposes one) so a long-lived Redis doesn't slowly fill with dead stylesheet splits.
• "Styles sometimes don't apply" is now a cache question first. Because the fast path returns before consulting the index, a genuinely missing class can look intermittent — it only surfaces when that class is new to the page. When debugging, introduce an obviously novel class to force the slow path, or clear the relevant key, before you go reading the splitter.
• Warm timings are not free timings. ~4.5 / 10 / 5 ms is the cost of the cache reads plus the hash/mtime checks; on a remote Redis with a cold connection pool those numbers move. If you're chasing a page-load budget on a latency-sensitive path, measure against production topology, not a local file store.
• Check the hash input if the theme is assembled dynamically. The content hash is what makes invalidation correct; if your build concatenates or post-processes the theme after the package reads it, you can end up hashing one artefact and rendering another. Keep the theme file the package sees as the final artefact.
• Extension point to watch: the cache store choice is the one knob worth wiring into per-environment config (array in tests, file locally, Redis in production) — it's the difference between this release being a 10× win and being invisible.