Blade Boost Directive Laravel Package

Getting Started

Install

composer require angus-mcritchie/blade-boost-directive

There is no service provider to register manually on Laravel 5.5+ (package discovery), no config to publish, and no migration to run — the description explicitly calls it zero-configuration. The only file worth opening on day one is the package's service provider / directive registration in vendor/angus-mcritchie/blade-boost-directive/ so you can see exactly what @boost compiles to. That single read answers the questions this package's README does not: which environments are skipped, whether blocked content is dropped entirely or merely hidden, and whether there's any config key you could override later.

Version floor

Pin ^1.2.0 if you are on or heading to Laravel 13 — v1.2.0 is the release that widens the composer constraint and adds Laravel 13 to the CI matrix. Nothing in the release notes suggests a code change, so treat it as a compatibility gate, not a feature. If you're staying on an older Laravel line, verify the widened constraint didn't drop your version before bumping.

First use case

Pick the one section of your app that makes php artisan serve feel slow — usually a dashboard widget that fans out into aggregate queries, a "recent activity" feed with nested relationships, or a third-party embed. Wrap it:

<div class="dashboard">
    @include('dashboard.kpis')

    @boost
        @include('dashboard.activity-feed')   {{-- 40 queries, 800ms --}}
        @include('dashboard.revenue-chart')
    @endboost
</div>

Load the page locally. If the section is gone and the page is snappy, the directive is doing its job. Then check the same route in a production-like environment (APP_ENV=production locally is enough) and confirm the markup is byte-identical to what you had before. That two-minute check is the whole adoption story.

Where to look first when something's off

php artisan view:clear after install — Blade caches compiled directives, and a stale compiled view is the most common reason a newly added @boost appears to do nothing. Then confirm the environment the app actually reports (app()->environment()), not what you think .env says.

Implementation Patterns

Wrap the expensive partial, not the expensive parent

@boost belongs as tight around the costly fragment as you can get it. Wrapping an entire layout or page hides your own markup bugs during development — you stop seeing the thing you're building. Wrapping a @include of one heavy widget keeps everything else visible while removing the reload tax:

@boost
    @include('reports.partials.aggregates', ['range' => $range])
@endboost

Keep the decision inside the view, not inside the partial

The value of this package is that it replaces @production ... @endproduction and @if(app()->isProduction()) scattered across templates. Standardize: environment gating lives in the calling view via @boost, and the partial itself stays environment-agnostic. That keeps the partial reusable in mailables, PDF exports, and queue-rendered views where you almost certainly want it to render regardless of APP_ENV.

Compose with authorization and conditionals outside the block

@boost doesn't know about your domain rules, so put @can, @auth, and data-dependent @if on the outside and let @boost be the innermost environment gate:

@can('view-reports')
    @boost
        @include('reports.heavy')
    @endboost
@endcan

The reverse — @boost on the outside with @can inside — is fine functionally but hides permission-gated UI from you locally, which makes authorization bugs invisible until staging.

Use it as a deliberate "known slow" marker

A pattern that pays off over time: any block that takes more than ~200ms to render gets a @boost, unconditionally, with a one-line comment saying why. The comment is the important part — six months later it's the record of which query needs an index. This turns the directive into a lightweight perf-debt registry that lives next to the code instead of in a ticket.

Combine with @cache / fragment caching in production

The two compose cleanly because they solve different halves of the problem: @boost removes the work in development, fragment caching removes it in production. Nesting them is legitimate — @boost outside, @cache inside — but confirm the ordering renders correctly in production first, since some cache directives capture output in ways that interact badly with an enclosing conditional.

Third-party embeds and scripts

Maps, chat widgets, analytics iframes, and video players are ideal candidates: they contribute nothing to iterating on layout, they cost a network round trip each, and they're frequently the reason a page "hangs" during hot reload. Wrapping them means your local DOM stays clean and your console stays quiet.

Sizing the win

Before you refactor twenty templates, measure once. Laravel Debugbar or Telescope gives you render time per view and query count; wrap your three heaviest sections, reload five times, and compare. If the improvement is marginal, stop — this package is a comfort feature, not an architecture.

Gotchas and Tips

The testing environment is the trap. If the directive skips based on APP_ENV, your PHPUnit suite typically runs in testing, not local. That's fine if testing renders normally — but confirm it. If @boost suppresses output under testing, assertions like assertSee('Revenue') silently pass-or-fail depending on a directive you added for developer convenience. Write one explicit test that renders a @boost-wrapped view and asserts the markup is present; it's three lines and it protects you from a whole class of confusing CI failures.

Browser tests and JS selectors. Dusk, Playwright, and Cypress specs that run against a local or CI server will find @boost-wrapped elements missing. Either run those suites with an environment where the block renders, or don't wrap anything an E2E test targets. This is the single most likely production-adjacent regression from adopting the package.

Content that must exist for non-humans. Anything a crawler, screen reader snapshot, PDF renderer, or email client needs should not be inside @boost — its entire purpose is to make that markup not exist locally. Keep it to interactive dashboard chrome and decorative widgets; keep SEO-bearing content, structured data, and @jsonld blocks outside.

view:clear is your first debugging step, always. Compiled Blade views are cached in storage/framework/views. After installing, after changing the package version, after editing a directive — clear it. Half the "the package doesn't work" reports for any Blade directive package are stale compiled views.

Directive syntax is whitespace-sensitive. @boost on its own line compiles cleanly; @boost($x) (if the package doesn't accept arguments) will throw a compile error rather than fail silently. If you need conditional boosting, use a surrounding @if, not a directive argument — the description makes no claim of parameter support.

Don't try to use it in attribute position. Like every custom Blade directive, @boost compiles to PHP and cannot be used inside an HTML attribute value or a @class([...]) array. If you need conditional classes, compute them in the component.

Watch nesting and @endboost balance. Custom directives that emit an opening conditional need a matching close. A missing @endboost produces a confusing PHP parse error pointing at the compiled view in storage/framework/views, not your source file. When you see a syntax error in a hashed view filename, grep your templates for unbalanced @boost pairs before anything else.

Production output should be provably unchanged. Before merging the first @boost usage, diff the rendered HTML of one representative page between main and your branch under APP_ENV=production. "Keeps production output untouched" is the package's core promise; verify it once at the markup level and you can stop worrying about it.

Have an exit ramp. The public surface is a pair of Blade directives, so the fallback is a two-line change: register your own @boost/@endboost in AppServiceProvider that compiles to @production/@endproduction. That triviality is the strongest argument for adopting the package — you get the readability and the centralized gate without a lock-in risk. Keep that snippet in a code comment near your first usage, so the day the package lags a future Laravel release, the removal is mechanical rather than a refactor.

Scope check. This is a 39-star single-purpose utility. Adopt it because the alternative is scattering env() calls through Blade, not because it will grow with you. Confirm the maintainer is responsive via the issue tracker before you use it in a client-facing critical path, and pin it in composer.lock like any other dependency.