Bug Widget Shield

Bug reporting widget for Laravel Filament with Filament Shield role-based visibility. Embeds the widget in the Filament admin panel for users with allowed roles, pre-populates the form with the authenticated user's name and email, and sends submissions to a configurable external endpoint (e.g. Productive sync backend) without storing data locally.

Requirements

• PHP 8.2+
• Laravel 11 or 12
• Filament 4
• bezhansalleh/filament-shield ^4.0

Installation

composer require studio-republic/bug-widget-shield

Install Filament Shield if not already installed:

php artisan shield:install

Publish the configuration:

php artisan vendor:publish --tag=bug-widget-shield-config

Fetch and cache the widget JS and CSS from your productive_mk3 backend:

php artisan bug-widget:fetch-assets

This downloads bug-widget.js and bug-widget.css from productive_mk3 and stores them in public/vendor/bug-widget-shield/. Run after install and whenever productive_mk3 updates the widget. Use --force to re-fetch when assets are already cached.

Configuration

Add these variables to your .env:

Variable	Description	Example
BUG_WIDGET_ENDPOINT_URL	Base URL of the API that receives bug reports	https://sync.example.com/api
BUG_WIDGET_TOKEN	Token from the Productive sync backend's BugWidgetConfiguration	Obtain from backend admin
BUG_WIDGET_ALLOWED_ROLES	Comma-separated Filament Shield roles that can see the widget	super_admin,filament_user,client
BUG_WIDGET_ASSETS_PATH	vendor (default) or url. Use url when self-hosting productive_mk3 (assets served from build routes). Use vendor for client sites (run bug-widget:fetch-assets).	url or vendor
BUG_WIDGET_ASSETS_URL	(Optional) Base URL for fetching assets when running fetch-assets. Defaults to endpoint URL with /api stripped	https://sync.example.com

Example .env:

BUG_WIDGET_ENDPOINT_URL=https://your-productive-sync.example.com/api
BUG_WIDGET_TOKEN=your-token-from-backend-admin
BUG_WIDGET_ALLOWED_ROLES=super_admin,filament_user,client

Setup

1. User model: Ensure your User model uses the HasRoles trait from spatie/laravel-permission (Filament Shield adds this automatically).

2. Token: Obtain the widget token from your Productive sync backend's admin panel (Bug Widget Configuration view page).

3. Domain whitelist: Add your site's domain to the BugWidgetConfiguration's allowed_domains in the backend admin so submissions are accepted.

4. Roles: Assign one or more of the allowed roles to users who should see the widget via Filament Shield's role management.

Where the Widget Appears

The widget is available in two places:

1. Filament Admin Panel (automatic)

The widget is automatically injected into the Filament panel layout for users with allowed roles. No additional setup required.

2. Frontend (include in your layout)

Add the widget to your frontend layout (e.g. resources/views/layouts/app.blade.php) by including the partial before </body>:

@bugWidgetShield

Or using the include syntax:

@include('bug-widget-shield::bug-widget')

Place it near the end of your layout, before the closing </body> tag.

How It Works

• Only users with one of the configured roles see the widget (in both Filament and frontend).
• The form is pre-filled with the authenticated user's name and email.
• No bug reports are stored locally; all submissions are sent to the configured endpoint.
• The widget fetches configuration (position, colors, triage questions) from the endpoint and submits reports with screenshot support.

Customising the Theme

Theme settings are controlled in two ways:

1. Backend configuration (recommended)

If your API backend (e.g. productive_mk3) supports it, configure these in the Bug Widget Configuration admin:

Setting	Description	Values
theme	Light/dark mode	light, dark, or auto (follows system preference)
button_color	Launcher button and primary accent	Hex colour (e.g. #E11873)
button_text_color	Launcher button text	Hex colour (e.g. #FFFFFF)
font_family	Typography	CSS font stack (e.g. Inter, system-ui, sans-serif)

2. CSS variable overrides

Override the widget’s appearance with your own CSS. Add a stylesheet that loads after the widget and targets .sr-bug-widget-root:

/* Override widget theme to match your brand */
.sr-bug-widget-root {
  --srb-primary: #2563eb;        /* Button and accent colour */
  --srb-text: #ffffff;          /* Button text */
  --srb-font: 'Inter', system-ui, sans-serif;
  --srb-radius: 12px;           /* Border radius */
  --srb-dialog-padding: 24px;   /* Modal padding */
  --srb-spacing: 16px;          /* Form spacing */
}

/* Dark mode overrides */
.sr-bug-widget-root.sr-bug-widget-dark {
  --srb-bg: #1e293b;
  --srb-text-primary: #f8fafc;
  --srb-border: #334155;
}

Available CSS variables:

Variable	Purpose	Default
--srb-primary	Primary/button colour	#e11973
--srb-text	Button text colour	#FFFFFF
--srb-bg	Modal background	#FFFFFF
--srb-text-primary	Main text	#111827
--srb-text-secondary	Secondary text	#374151
--srb-text-tertiary	Muted text	#6B7280
--srb-border	Borders	#D1D5DB
--srb-hover-bg	Hover backgrounds	#F3F4F6
--srb-input-bg	Input background	#FFFFFF
--srb-input-readonly	Read-only input bg	#F9FAFB
--srb-font	Font family	system-ui, sans-serif
--srb-radius	Border radius	8px
--srb-shadow	Box shadow	(default shadow)
--srb-focus-ring	Focus outline	(default ring)
--srb-dialog-padding	Modal padding	24px
--srb-spacing	Form spacing	16px
--srb-error	Error colour	#DC2626
--srb-success	Success colour	#059669
--srb-z-index	Widget z-index	2147483648

In a Laravel app, add your overrides in resources/css/app.css (or a dedicated partial) and ensure it loads after the widget CSS.

3. Custom stylesheet (advanced)

For full control, publish the assets and replace public/vendor/bug-widget-shield/bug-widget.css with your own stylesheet. Alternatively, load additional CSS after the widget to override any default styles.

Building Assets (Developers)

If you modify the widget source in resources/js/ or resources/css/:

cd packages/studio-republic/bug-widget-shield
npm install
npm run build

Built assets are output to resources/dist/ and are published when clients run php artisan vendor:publish --tag=bug-widget-shield-assets.

License

MIT