Laravel Hotjar Laravel Package

Getting Started

• Upgrade with composer require <vendor>/<package>:^1.1 — this is a minor release, so no code changes are required to keep existing behaviour. Existing <script> output is unchanged when no nonce is configured.
• If you only want the new feature, there is nothing to configure in the package itself. The nonce is picked up from Laravel's Vite nonce registry, which is set with Vite::useCspNonce($nonce) (or the @cspNonce Blade directive when you generate the nonce in a view).
• First use case: you already have a CSP with a nonce-based script-src (typically via laravel-security-headers or your own middleware) and the package's inline/embedded <script> was being blocked or forcing you to keep 'unsafe-inline'. After the upgrade, drop 'unsafe-inline' from script-src and confirm the package's tags render with nonce="…".
• Where to look first: render the page once with the nonce middleware enabled and inspect the HTML source (not the DOM inspector — the DOM hides the attribute only if it was stripped). The package's <script> tags should carry the same nonce value as the ones emitted by @vite.
• Sanity check in a feature test before touching production policy: assert the rendered response contains nonce=" on the package's script tag, and run a curl -sI / curl -s against a staging URL with your real security headers to confirm no Refused to execute inline script in the browser console.

Implementation Patterns

• Single source of truth for the nonce. Generate the nonce once per request (middleware, or laravel-security-headers's built-in support) and register it via Vite::useCspNonce($nonce) early — before any view that includes the package renders. The package reads the registered value, so you should never pass a nonce into the package manually.
• Middleware ordering. Put your CSP/nonce middleware before anything that renders or caches responses (including response-cache and Route::middleware('web') view rendering). With laravel-security-headers, keep it in the global stack and verify it still runs when you use withoutMiddleware in tests.
• Keep the header and the markup in sync. The package emits the nonce on its <script> tags, but the Content-Security-Policy header must contain the same value. Both must come from the same per-request nonce — mismatches are the most common cause of "it works locally, breaks in staging".
• Blade-only rendering. The nonce is injected server-side at render time. Rendering the package's output inside a Livewire component, an Inertia @vite-adjacent partial, or a Blade component is fine; injecting the script client-side (e.g. building it in JS from JSON props) is not covered by this release.
• Partial/component caching. If you cache a Blade fragment with @cache, the nonce is baked into the cached HTML and will be wrong for the next request. Either exclude the package's partial from fragment caching or add the nonce to your cache key.
• Testing pattern. Write one feature test asserting the nonce attribute is present when Vite::useCspNonce('test-nonce') is set, and one asserting no nonce attribute (or no breakage) when it isn't. This pins the behaviour across future upgrades.
• Local development. With @vite in dev mode, Vite's HMR scripts also pick up the nonce, so a correct setup means all scripts on the page share the value — a quick way to eyeball whether the nonce plumbing is consistent.
• Hardening afterwards. Once the package's tags are nonced, consider script-src 'nonce-…' 'strict-dynamic' and remove 'unsafe-inline'; report-only (Content-Security-Policy-Report-Only) first is the low-risk path.

Gotchas and Tips

• Nonce set too late. If Vite::useCspNonce() runs after the view renders (e.g. in a terminating middleware or a response callback), the package's tags will be emitted without a nonce. Set it in middleware, not in a listener.
• Full-page/HTTP caching breaks nonces. Any cached HTML containing a nonce will fail CSP on subsequent requests, since the header carries a different nonce. Use per-response nonces only with uncached HTML, or switch to hash-based policies for cached pages.
• Header vs. attribute drift. A missing nonce in the header (e.g. laravel-security-headers config not published, or the CSP disabled for that route group) means correctly-nonced scripts still get blocked. Check both, not just the HTML.
• Multiple nonces. Calling Vite::useCspNonce() more than once per request overwrites the previous value; whichever is last wins for both @vite and the package. Keep exactly one call site.
• Debugging blocked scripts. In DevTools, blocked inline scripts show the expected nonce in the error message — compare it byte-for-byte with the attribute on the tag. A trailing space or quoted value in the header config is a silent failure.
• Not a licence to inline anything. This release covers scripts the package renders. Your own inline <script> blocks, onclick handlers, and style attributes still need their own nonces/hashes (or @cspNonce).
• Extension points to check before overriding. If the package exposes customisable Blade views, publish and diff them after upgrading — a locally published, older view will not include the new nonce attribute even though the PHP side supports it. This is the most likely reason the feature "doesn't work" for an existing install.
• Verify the release actually shipped the attribute on your version with composer show <vendor>/<package> and a one-line curl | grep -o 'nonce="[^"]*"'; if nothing renders, you may be on a cached view (php artisan view:clear) or an older lockfile entry.