Comprehensive Troubleshooting Guide

This guide helps you resolve common issues with the Filament PWA plugin, including installation problems, configuration issues, and performance optimization.

Common Issues
Installation Problems
Configuration Issues
Performance Issues
Validation Errors
Debug Tools
Environment-Specific Issues
Browser-Specific Issues
Getting Help

Common Issues

Installation Prompt Not Showing

Problem: The PWA installation prompt doesn't appear.

Symptoms:

No installation banner visible
Browser doesn't show "Add to Home Screen" option
PWA installation criteria not met

Solutions:

Check HTTPS requirement:

# PWAs require HTTPS in production
# For development, use localhost or 127.0.0.1
php artisan serve --host=localhost

Enable debug mode:

FilamentPwaPlugin::make()
    ->enableDebugBanner()  // Always show in debug mode

Check browser console:
- Open Developer Tools → Console
- Look for PWA-related errors
- Check if service worker is registered

Validate PWA setup:

php artisan filament-pwa:setup --validate

Check installation criteria:
- Manifest file exists and is valid
- Service worker is registered
- Required icons (192x192, 512x512) exist
- HTTPS is enabled (production)
- Site is not already installed

Icons Not Loading

Problem: PWA icons are not displaying correctly.

Symptoms:

Broken image icons in browser
Default browser icons instead of custom icons
404 errors for icon files

Solutions:

Regenerate icons:

php artisan filament-pwa:setup --generate-icons --source=public/logo.svg

Check file permissions:

chmod 755 public/images/icons
chmod 644 public/images/icons/*.png

Verify icon paths:

# Check if icons exist
ls -la public/images/icons/

# Expected files:
# icon-72x72.png, icon-96x96.png, icon-128x128.png, etc.
# icon-192x192-maskable.png, icon-512x512-maskable.png

Check icon configuration:

// Verify icon path in config
'icons' => [
    'path' => 'images/icons',  // Should match actual directory
],

Clear browser cache:
- Hard refresh (Ctrl+F5 or Cmd+Shift+R)
- Clear application cache in DevTools

Service Worker Issues

Problem: Service worker not updating or caching properly.

Symptoms:

Old content still showing after updates
Offline functionality not working
Service worker registration errors

Solutions:

Update cache name:

'service_worker' => [
    'cache_name' => 'my-app-v1.0.1',  // Increment version
],

Clear service worker:
- DevTools → Application → Service Workers
- Click "Unregister" and refresh

Check service worker registration:

// In browser console
navigator.serviceWorker.getRegistrations().then(function(registrations) {
    console.log(registrations);
});

Force service worker update:

// In browser console
navigator.serviceWorker.getRegistrations().then(function(registrations) {
    registrations.forEach(function(registration) {
        registration.update();
    });
});

PWA Not Installable

Problem: Browser doesn't show install option.

Symptoms:

No "Add to Home Screen" option
Installation prompt never appears
PWA criteria not met

Solutions:

Check PWA criteria:

php artisan filament-pwa:setup --validate

Verify manifest:
- Visit /manifest.json in browser
- Check for JSON syntax errors
- Ensure all required fields are present
Check required icons:
- Ensure 192x192 and 512x512 icons exist
- Verify icon paths in manifest
- Check icon file formats (PNG recommended)
Test in different browsers:
- Chrome: DevTools → Application → Manifest
- Firefox: about:debugging → Service Workers
- Safari: Develop → Service Workers
Check engagement heuristics:
- User must interact with the site
- Site must be visited multiple times
- Some browsers require time delay

Installation Problems

Package Installation Issues

Problem: Composer installation fails.

Solutions:

Check PHP version:
```
php -v  # Ensure PHP 8.1+
```
Update Composer:
```
composer self-update
composer update
```
Clear Composer cache:
```
composer clear-cache
composer install
```

Asset Publishing Issues

Problem: Assets not publishing correctly.

Solutions:

Force publish assets:

php artisan vendor:publish --tag="filament-pwa-assets" --force
php artisan vendor:publish --tag="filament-pwa-config" --force
php artisan vendor:publish --tag="filament-pwa-views" --force
php artisan vendor:publish --tag="filament-pwa-lang" --force

Check file permissions:

chmod -R 755 public/
chmod -R 755 config/
chmod -R 755 resources/views/
chmod -R 755 resources/lang/

Verify published files:

ls -la public/manifest.json
ls -la public/sw.js
ls -la config/filament-pwa.php
ls -la resources/lang/*/pwa.php

Icon Generation Issues

Problem: Icon generation fails.

Solutions:

Check source image:

# Ensure source image exists and is readable
ls -la public/logo.svg
file public/logo.svg  # Check file type

Install image processing extensions:

# Ubuntu/Debian
sudo apt-get install php-imagick php-gd

# macOS with Homebrew
brew install imagemagick
brew install php-imagick

# Windows
# Download from https://windows.php.net/downloads/pecl/releases/imagick/

Check extension availability:

// Check in PHP
var_dump(extension_loaded('imagick'));
var_dump(extension_loaded('gd'));

Use different source format:

# Try PNG instead of SVG
php artisan filament-pwa:setup --generate-icons --source=public/logo.png

Check memory limits:

// php.ini
memory_limit = 512M
max_execution_time = 300

Configuration Issues

Theme Color Not Detected

Problem: PWA doesn't use Filament's theme color.

Symptoms:

Default blue color instead of custom theme
Browser UI doesn't match Filament colors

Solutions:

Debug color detection:

use Alareqi\FilamentPwa\Services\PwaService;

$debug = PwaService::debugColorDetection();
dd($debug);

Manual configuration:

FilamentPwaPlugin::make()
    ->themeColor('#3B82F6')

Check Filament panel configuration:

// Ensure Filament colors are properly configured
$panel->colors([
    'primary' => Color::Indigo,
])

Use environment variable:
```
PWA_THEME_COLOR="#3B82F6"
```

Language Not Detected

Problem: PWA doesn't use correct language.

Symptoms:

English text instead of expected language
Wrong text direction for RTL languages

Solutions:

Check Laravel locale:
```
dd(app()->getLocale());
```
Set locale in config:
```
// config/app.php
'locale' => 'ar',
```

Manual PWA configuration:

FilamentPwaPlugin::make()
    ->language('ar')
    ->rtl()

Publish language files:

php artisan vendor:publish --tag="filament-pwa-lang"

Check translation files exist:
```
ls -la resources/lang/ar/pwa.php
```

Installation Prompts in Wrong Language

Problem: Installation prompts show in wrong language.

Solutions:

Check translation files:
```
ls -la resources/lang/*/pwa.php
```

Verify locale setting:

// Check current locale
dd(app()->getLocale());

Clear translation cache:

php artisan config:clear
php artisan cache:clear

Test with specific locale:

// Temporarily set locale for testing
app()->setLocale('ar');

Check translation key structure:

// Ensure translation files have correct structure
return [
    'install_title' => 'Your translation',
    'validation' => [
        'manifest_missing' => 'Your translation',
    ],
];

Performance Issues

Slow Loading

Problem: PWA loads slowly.

Symptoms:

Long loading times
Poor user experience
High bandwidth usage

Solutions:

Optimize cache strategy:

'service_worker' => [
    'cache_urls' => [
        '/admin',           // Only cache essential pages
        '/admin/login',
    ],
],

Reduce icon sizes:

'icons' => [
    'sizes' => [192, 512],  // Only generate essential sizes
],

Optimize images:

# Use optimized source images
# Compress PNG files
# Use SVG for logos when possible

Enable compression:

# .htaccess
<IfModule mod_deflate.c>
    AddOutputFilterByType DEFLATE application/json
    AddOutputFilterByType DEFLATE image/svg+xml
</IfModule>

Large Cache Size

Problem: Service worker cache is too large.

Solutions:

Limit cached URLs:

'service_worker' => [
    'cache_urls' => [
        '/admin',
        '/admin/login',
        // Remove unnecessary URLs
    ],
],

Optimize cache patterns:

'cache_patterns' => [
    'images' => '/\.(png|jpg|jpeg|webp)$/',  // Only cache images
    // Remove font caching if not needed
],

Implement cache expiration:

// Custom service worker modifications
// Add cache expiration logic

Memory Issues

Problem: High memory usage during icon generation.

Solutions:

Increase PHP memory limit:
```
// php.ini
memory_limit = 512M
```

Use smaller source images:

# Resize source image before generation
# Recommended: 1024x1024 maximum

Generate icons in batches:

# Generate specific sizes only
php artisan filament-pwa:setup --generate-icons --source=logo.svg

Validation Errors

Manifest Missing

Error: Web app manifest not found

Solutions:

Publish PWA assets:

php artisan vendor:publish --tag="filament-pwa-assets" --force

Check manifest file:

ls -la public/manifest.json
curl -I http://localhost/manifest.json

Verify web server configuration:

# .htaccess - ensure JSON files are served correctly
<Files "manifest.json">
    Header set Content-Type "application/manifest+json"
</Files>

Service Worker Missing

Error: Service worker not found

Solutions:

Publish service worker:

php artisan vendor:publish --tag="filament-pwa-assets" --force

Check service worker file:

ls -la public/sw.js
curl -I http://localhost/sw.js

Verify service worker registration:

// Check in browser console
navigator.serviceWorker.getRegistrations()

Icons Missing

Error: Required PWA icons not found

Solutions:

Generate icons:

php artisan filament-pwa:setup --generate-icons --source=public/logo.svg

Check required icon sizes:

ls -la public/images/icons/icon-192x192.png
ls -la public/images/icons/icon-512x512.png

Verify icon paths in manifest:

{
  "icons": [
    {
      "src": "/images/icons/icon-192x192.png",
      "sizes": "192x192",
      "type": "image/png"
    }
  ]
}

HTTPS Required

Error: HTTPS is required for PWA in production

Solutions:

Enable HTTPS in production:

# Use SSL certificate
# Configure web server for HTTPS

For development:

# Use localhost (exempt from HTTPS requirement)
php artisan serve --host=localhost

# Or use Laravel Valet for automatic HTTPS
valet secure your-site

Check environment detection:

// Ensure APP_ENV is set correctly
APP_ENV=production  // Requires HTTPS
APP_ENV=local       // HTTPS not required

Debug Tools

PWA Validation Command

php artisan filament-pwa:setup --validate

This command checks:

Manifest file existence and validity
Service worker registration
Required icon files
HTTPS requirements
Basic PWA compliance

Color Detection Debug

use Alareqi\FilamentPwa\Services\PwaService;

$debug = PwaService::debugColorDetection();
dd($debug);

This provides information about:

Detected theme color
Filament panel availability
Color configuration sources
Final merged configuration

Browser Developer Tools

Chrome DevTools:
- Application → Manifest (check manifest)
- Application → Service Workers (check SW status)
- Application → Storage (check cached resources)
- Lighthouse → PWA audit
Firefox DevTools:
- about:debugging → Service Workers
- Network → check for 404 errors
- Application → Manifest
Safari DevTools:
- Develop → Service Workers
- Web Inspector → Storage
- Console → check for errors

Manual Testing

Test installation flow:

// Check if PWA is installable
window.addEventListener('beforeinstallprompt', (e) => {
    console.log('PWA is installable');
});

Test offline functionality:
- Disconnect network
- Navigate to cached pages
- Check offline page

Test service worker:

// Check service worker status
navigator.serviceWorker.ready.then((registration) => {
    console.log('Service Worker ready:', registration);
});

Environment-Specific Issues

Development Environment

Common issues:

HTTPS requirement (use localhost)
Installation prompts not showing (enable debug mode)
Service worker caching issues (disable cache in DevTools)

Solutions:

FilamentPwaPlugin::make()
    ->enableDebugBanner()  // Always show installation prompts

# Use localhost for development
php artisan serve --host=localhost

Production Environment

Common issues:

HTTPS certificate issues
Cache not updating
Icons not loading (CDN issues)

Solutions:

Ensure valid HTTPS certificate
Update cache names for new deployments
Verify asset URLs are correct
Check CDN configuration

Staging Environment

Common issues:

Mixed content warnings
Different domain configurations
Authentication issues

Solutions:

Use HTTPS for staging
Update start_url and scope for staging domain
Configure proper authentication

Browser-Specific Issues

Chrome/Chromium

Common issues:

Installation criteria too strict
Service worker update delays

Solutions:

Check DevTools → Application → Manifest for errors
Use "Update on reload" in Service Workers tab
Clear site data if needed

Firefox

Common issues:

Limited PWA support
Different installation behavior

Solutions:

Check about:config for PWA settings
Use about:debugging for service worker inspection

Safari (iOS/macOS)

Common issues:

Limited PWA features
Manual installation required on iOS

Solutions:

Provide iOS-specific installation instructions
Ensure apple-touch-icon is present
Test on actual iOS devices

Edge

Common issues:

Similar to Chrome but with slight differences

Solutions:

Test specifically in Edge
Check Microsoft Store integration

Getting Help

If you're still experiencing issues:

Check the GitHub issues: GitHub Issues
Create a detailed bug report with:
- Laravel version
- Filament version
- Plugin version
- Browser and version
- Operating system
- Steps to reproduce
- Error messages
- Configuration used

Include debug information:

php artisan filament-pwa:setup --validate
php artisan about

Test in multiple browsers to isolate browser-specific issues
Provide minimal reproduction case when possible
Check documentation for recent updates and changes

Useful Commands for Bug Reports

# System information
php artisan about

# PWA validation
php artisan filament-pwa:setup --validate

# Check published assets
ls -la public/manifest.json public/sw.js public/images/icons/

# Check configuration
php artisan config:show filament-pwa

# Check routes
php artisan route:list | grep manifest

Filament Pwa Laravel Package

Comprehensive Troubleshooting Guide

Table of Contents

Common Issues

Installation Prompt Not Showing

Icons Not Loading

Service Worker Issues

PWA Not Installable

Installation Problems

Package Installation Issues

Asset Publishing Issues

Icon Generation Issues

Configuration Issues

Theme Color Not Detected

Language Not Detected

Installation Prompts in Wrong Language

Performance Issues

Slow Loading

Large Cache Size

Memory Issues

Validation Errors

Manifest Missing

Service Worker Missing

Icons Missing

HTTPS Required

Debug Tools

PWA Validation Command

Color Detection Debug

Browser Developer Tools

Manual Testing

Environment-Specific Issues

Development Environment

Production Environment

Staging Environment

Browser-Specific Issues

Chrome/Chromium

Firefox

Safari (iOS/macOS)

Edge

Getting Help

Useful Commands for Bug Reports