Filament Screenshot Catalogue Laravel Package

Technical Evaluation

Architecture Fit

• Strengths:

  • Tight Filament v5 Integration: Built specifically for Filament panels, leveraging its routing, resources, and authentication systems. The PanelDescriptor registration pattern aligns with Filament’s plugin ecosystem, making it a natural fit for Filament-based applications.
  • Modular Pipeline: The 4-step pipeline (sitemap → capture → upload → index) is cleanly separated, allowing for targeted optimizations (e.g., parallelizing capture jobs or caching sitemaps).
  • S3-Centric Storage: Uses Laravel’s filesystem abstraction for S3 uploads, reducing vendor lock-in and integrating seamlessly with existing cloud storage setups.
  • Visual Regression Ready: Output format (PNGs + index.html) is compatible with tools like Percy, Applitools, or custom AI-driven diffing (e.g., via Claude integration).

• Gaps:

  • No Dynamic Content Handling: Relies on static sitemaps and representative records (e.g., first User for users.index). Dynamic content (e.g., real-time data) requires pre-seeding or mocking.
  • Limited Customization for Non-Filament Pages: While it supports custom pages, complex SPAs or non-Filament routes may need manual sitemap augmentation.
  • Playwright Dependency: Tight coupling to Playwright for rendering limits flexibility if headless browsers need replacement (e.g., for non-Chromium environments).

Integration Feasibility

• Laravel Ecosystem Alignment:
  • Uses Artisan commands, Laravel queues, and filesystem disks—minimal friction for Laravel teams.
  • PanelDescriptor registration fits Laravel’s service provider pattern.
  • S3 integration assumes aws/aws-sdk-php is already in use (common for Laravel apps).
• Filament-Specific:
  • Requires Filament v5 (no backward compatibility).
  • Tenant support is explicitly handled but may need adjustments for complex multi-tenancy setups.
• Node.js Dependencies:
  • Playwright and Node 18+ are prerequisites, which may require CI/CD or dev environment coordination.

Technical Risk

• High:
  • Playwright Stability: Node.js/Playwright interactions could introduce flakiness (e.g., browser crashes, timing issues). Requires robust error handling and retries.
  • S3 Permissions: Misconfigured s3_public disk could expose sensitive screenshots. Needs strict IAM policies.
  • CI/CD Complexity: Running captures in CI (e.g., GitHub Actions) requires mocking auth, seeding test data, and managing Node.js environments.
• Medium:
  • Performance at Scale: Capturing hundreds of pages with multiple viewports could strain CI resources or local dev machines.
  • Theme/Animation Quirks: capture_time_css may not suffice for complex animations (e.g., CSS transitions, WebSockets).
• Low:
  • Laravel Compatibility: Minimal risk given the package’s Laravel-centric design.

Key Questions

1. Use Case Prioritization:
   • Is this for visual regression testing, design reviews, or marketing assets? This dictates whether you need immutable tags (e.g., v1.0.0) or mutable latest.
   • Do you need AI-driven diffing (e.g., Claude integration)? If so, assess the claude-skills publishable asset’s utility.
2. Authentication Complexity:
   • How will you handle test users for auth screens (e.g., login, 2FA)? Will you seed them in CI or use a shared service account?
   • For tenanted panels, is the authenticator closure in PanelDescriptor sufficient, or do you need tenant-aware seeding?
3. CI/CD Integration:
   • Where will captures run? Local dev (fast iteration) vs. CI (production-like) vs. dedicated capture server (scalability)?
   • How will you trigger rebuilds? Manual (screenshot:dispatch) or automated (e.g., post-deploy hook)?
4. Storage and Cost:
   • How will you manage S3 costs? PNGs can be large; consider compression or lifecycle policies for old tags.
   • Do you need versioned S3 buckets for immutable tags? This adds complexity but enables rollback.
5. Failure Modes:
   • What’s the recovery process if a capture job fails mid-run? Will you retry or manually resume?
   • How will you handle missing screenshots in the index.html? The package omits failed captures by default—is this acceptable?
6. Customization Needs:
   • Will you override the Playwright runner (via vendor:publish) for custom scripts (e.g., waiting for AJAX)?
   • Do you need additional viewports or custom CSS overrides beyond capture_time_css?

Integration Approach

Stack Fit

• Core Stack:
  • Laravel: Native support for Artisan, queues, and filesystem disks. Assumes Laravel 10+ (Filament v5 compatibility).
  • Filament v5: Required for panel discovery, routing, and auth. No support for Filament v2/3.
  • S3: Uses Laravel’s filesystem abstraction (s3_public disk). Requires AWS SDK and proper IAM roles.
  • Node.js 18+: For Playwright. Must be installed globally or via project-specific nvm/nvm-windows.
  • Playwright: Headless browser for rendering. Chromium is default; can extend to Firefox/WebKit.
• Optional Add-ons:
  • Claude AI: Published skill for command-line interaction (requires Claude installation).
  • Custom Playwright Runner: Publishable asset for overriding capture logic (e.g., custom waits, interactions).

Migration Path

1. Assessment Phase:
   • Audit Filament panels to identify capture scope (e.g., admin, customer).
   • Define authentication strategy (test users, tenants, magic links).
   • Plan S3 storage (bucket, disk config, lifecycle policies).
2. Setup:
   • Install as require-dev:

     composer require --dev visualbuilder/filament-screenshot-catalogue
     

   • Publish config if needed:

     php artisan vendor:publish --tag=filament-screenshot-catalogue-config
     

   • Register PanelDescriptor in a service provider (wrap in class_exists if require-dev).
3. Initial Capture:
   • Generate sitemap:

     php artisan panel:sitemap --panel=admin
     

   • Test single-page capture:

     php artisan screenshot:capture --panel=admin --page=dashboard --tag=test
     

   • Verify S3 output and index.html.
4. Automation:
   • Integrate into CI/CD (e.g., GitHub Actions) for post-deploy captures:

     - name: Capture screenshots
       run: php artisan screenshot:dispatch --panel=admin --tag=${{ github.sha }}
     

   • Set up queue workers for screenshot:dispatch (e.g., Redis queue).
5. Productionization:
   • Configure immutable tags (e.g., v1.0.0) for critical panels.
   • Set up S3 lifecycle rules to archive old tags.
   • Document rollback procedure (e.g., restore from S3 versioning).

Compatibility

• Laravel:
  • ✅ Works with Laravel 10+ (Filament v5 requirement).
  • ⚠️ May need adjustments for custom Filament panel structures (e.g., non-standard routing).
• Filament:
  • ✅ Supports resources, pages, and auth screens.
  • ⚠️ Tenant support requires manual Filament::setTenant() in authenticator.
  • ❌ No support for Filament v2/3 or non-Filament Laravel apps.
• S3:
  • ✅ Uses Laravel’s filesystem abstraction (flexible disk config).
  • ⚠️ Requires aws/aws-sdk-php (transitive dependency).
• Node.js/Playwright:
  • ✅ Playwright Chromium is default; can extend to other browsers.
  • ⚠️ Node.js version must be ≥18.0.0.
  • ❌ No native support for non-Chromium environments (e.g., serverless Lambda).

Sequencing

1. Pre-requisites:
   • Install Node.js 18+ and Playwright (npm install playwright && npx playwright install chromium).
   • Configure S3 disk in config/filesystems.php.
   • Seed test users for each panel.
2. Development:
   • Register PanelDescriptor and publish config as needed.
   • Test sitemap generation and single-page captures locally.
3. CI/CD:
   • Set up CI job for automated captures (e.g., post-merge to main).
   • Configure queue workers for parallel processing.
4. Production:
   • Run initial full capture