Weave Code
Laravel Blade Comments Laravel Package
spatie/laravel-blade-comments
Adds HTML debug comments around every rendered Blade view/component so you can see exactly which template produced each piece of output in browser dev tools. Also includes top-level request and view info at the top of the document.
Add debug comments to your rendered output
Frequently asked questions about Laravel Blade Comments
- How do I install and enable spatie/laravel-blade-comments in my Laravel project?
- Run `composer require spatie/laravel-blade-comments --dev` to install. Add the middleware to your `app/Http/Kernel.php` under the `$middleware` array for web requests. The package auto-detects Blade views and injects comments when `APP_DEBUG=true`. No additional configuration is needed for basic usage.
- Will this package slow down my production environment?
- No, the package is designed as a dev-only tool. It only injects comments when `APP_DEBUG=true` and has zero runtime impact in production. You can also exclude specific views or sections via the `excludedViews` config array to further optimize performance.
- Does spatie/laravel-blade-comments work with Laravel Livewire components?
- Yes, the package supports Livewire v3 and v4 components. It automatically wraps Livewire-rendered content in debug comments, making it easy to trace component output. Tested with Livewire’s latest stable versions, but pin your Livewire version in `composer.json` if using beta releases.
- Can I customize the debug comments or add extra metadata (e.g., user context, Git hash)?
- Absolutely. Implement the `BladeCommenter` or `RequestCommenter` interfaces to extend functionality. For example, you can inject custom metadata like Git commit hashes or feature flags by overriding the default commenters. The package provides clear interfaces and examples in the documentation.
- How does this package handle complex Blade layouts with nested includes/sections?
- The package recursively traces all Blade views, including nested `@include`, `@stack`, and `@component` directives. Each rendered section gets wrapped in comments, so you can inspect even deeply nested layouts. Use the `excludedViews` config to ignore non-critical partials like CSS/JS includes.
- Is there a way to disable comments for specific views or routes?
- Yes, use the `excludedViews` array in the config to blacklist Blade files or partials. For route-specific exclusions, you can conditionally disable the middleware in `Kernel.php` or use middleware groups. This is useful for performance-critical pages or staging environments.
- Will this package break when upgrading Laravel to a newer version?
- The package is tested against Laravel 9+ and follows Laravel’s release cycle. While breaking changes are rare, always test after major Laravel updates. The package uses Laravel’s Blade compiler hooks, so compatibility depends on Laravel’s internal Blade parser changes. Check the changelog for version-specific notes.
- Can I use this with Laravel Vite or Inertia.js for frontend debugging?
- This package only works with Blade templates. For Inertia.js or Vite, you’ll need to rely on browser dev tools or frontend-specific debugging tools like React DevTools. The comments are injected into the final HTML, so they won’t appear in SSR or static assets.
- How does this package affect Blade template compilation time in CI/CD?
- The package adds minimal overhead during Blade compilation (pre-runtime). In CI, this may slightly increase build times, especially for large projects. To mitigate this, exclude non-critical views or disable the package in CI by setting `APP_DEBUG=false`. Monitor compilation times and adjust exclusions as needed.
- Are there alternatives to spatie/laravel-blade-comments for debugging Blade templates?
- Alternatives include manually adding `{{-- debug comments --}}` in Blade files or using browser dev tools to inspect rendered HTML. However, those methods lack automation and traceability. Other packages like `laravel-debugbar` provide broader debugging but don’t focus on template-level tracing. This package is specialized for Blade-specific debugging.
Weaver
How can I help you explore Laravel packages today?