Laravel Pixel Laravel Package

Getting Started

This release (3.1.0) is additive and non-breaking: the package now attaches Laravel's Vite CSP nonce to every <script> it renders, so nonce-based script-src policies work without 'unsafe-inline'. If you were previously patching around CSP failures, that workaround can go away.

Minimal path to first use:

1. composer require the package and, if it ships one, publish its config (php artisan vendor:publish --tag=...) so you can see how script output is configured.
2. Look first at the package's service provider and its Blade component/renderer — that's the code path that emits the <script> tag and, as of 3.1.0, reads the nonce.
3. Set the nonce once for the request. If you already use Vite, this is Vite::useCspNonce($nonce) (or the csp_nonce() helper) in a middleware or AppServiceProvider; the package will pick up the same value.
4. Replace one hand-written <script> tag in a layout with the package's component/helper, load the page, and view source. You should see a nonce="..." attribute matching your Content-Security-Policy response header.

The first genuinely useful use case is exactly that swap: any place you currently emit an inline bootstrap snippet, analytics loader, or third-party widget tag from Blade, route it through the package and the nonce plumbing is handled for you.

Implementation Patterns

Single source of truth for the nonce. Generate the nonce in middleware that runs before the response body is rendered, then share it with both Vite and the CSP header emitter. Practically:

// middleware, before the request reaches the controller/view
$nonce = base64_encode(random_bytes(16));
Vite::useCspNonce($nonce);
$response = $next($request);
$response->headers->set('Content-Security-Policy', "script-src 'nonce-{$nonce}' 'strict-dynamic'");

Anything that reads Vite::cspNonce() — Vite's own tags and now this package — will agree.

Replace, don't wrap. The value comes from the package owning the tag. If you wrap it in your own <script> or manually append a nonce, you'll end up with mismatched or duplicated attributes. Swap the raw tag for the package's renderer in layouts and partials, one slot at a time.

Composition with laravel-security-headers or spatie/laravel-csp. Those packages typically supply the nonce themselves. Let them own generation, set the Vite nonce from their value, and don't introduce a second generator — two nonces is the single most common cause of "it works on one page and not another."

Inline vs. external. The nonce matters for inline scripts and for 'strict-dynamic' setups. For a plain <script src="https://cdn..."> under script-src 'self' https://cdn..., the nonce is inert but harmless. Don't restructure a working allowlist policy just because the attribute is now present.

Feature tests. Assert the attribute exists on a real response rather than unit-testing the renderer:

$this->get('/')->assertSee('nonce=', false);

Then assert the header nonce and the body nonce are the same string — that's the property that actually breaks in production.

Caching boundary. Any full-page/response cache in front of these pages must key or vary on the nonce, or simply be disabled for nonce-bearing HTML. This is the integration detail most likely to bite you, and it's the one the release notes don't mention.

Gotchas and Tips

• Middleware ordering is the failure mode. If the nonce is set after the view renders (e.g. in a terminating callback or a response-stage middleware), the header will carry a nonce the scripts don't have, and the browser blocks everything while the source looks correct. Set it early.
• Publish-and-override drops the attribute. If you've published the package's views to customize markup, check the 3.1.0 diff and re-add nonce="{{ Vite::cspNonce() }}" to your overridden template. Stale published views are the most likely reason the feature "doesn't work" after upgrading.
• Livewire / Inertia / Filament. These inject their own scripts through separate paths. Confirm empirically that their tags carry the nonce; don't assume package coverage extends to them.
• Debug with Report-Only first. Deploy the tightened policy as Content-Security-Policy-Report-Only, watch the violation reports, then enforce. DevTools console messages name the exact blocked inline script, which is faster than diffing HTML.
• 'unsafe-inline' alongside a nonce is ignored by browsers that support nonces, so leaving it in won't break you — but it also means your policy isn't actually testing anything. Remove it once the nonce path is verified, otherwise a regression in nonce propagation goes unnoticed until you tighten the header.
• Config caching is fine; nonce caching is not. config:cache won't affect this, but never store a nonce in config, a singleton resolved at boot, or an Octane-warmed property without resetting it per request. Under Octane, a boot-time nonce silently becomes a build-time constant.
• Upgrade risk is low. 3.1.0 adds an attribute rather than changing the API. The realistic breakage is not the package but your own policy: once scripts carry a valid nonce, any inline script you weren't routing through the package is now the odd one out and will be the one blocked. Audit remaining hand-written <script> tags in the same pass.