Filament Tour Laravel Package

Technical Evaluation

Architecture Fit

• Pros:

  • Lightweight & Non-Intrusive: Leverages Shepherd.js (a battle-tested UI tour library) without requiring backend modifications beyond plugin registration. Ideal for Filament-based admin panels where UX onboarding is critical.
  • Decoupled Design: Tour logic is frontend-focused (JavaScript/Shepherd.js), reducing coupling with core Laravel/PHP business logic. Backend only handles plugin registration and optional asset publishing.
  • Filament-Native Integration: Designed specifically for Filament’s ecosystem (v3/v4), ensuring compatibility with its UI components (e.g., user menu dropdown for tour trigger).
  • Customization Hooks: Supports CSS/JS asset publishing for theming, aligning with Filament’s modular design.

• Cons:

  • Shepherd.js Dependency: Relies on an external JS library (Shepherd.js), which may introduce versioning or compatibility risks if not actively maintained.
  • Limited Backend Control: Tour steps are primarily configured via frontend logic (e.g., JavaScript or published assets), requiring frontend expertise for complex workflows.
  • No Built-in Analytics: Lacks native tracking for tour completion rates or user engagement (would need integration with tools like Laravel Mixins or third-party analytics).

Integration Feasibility

• Low Barrier to Entry: Installation is straightforward (Composer + optional asset publishing). Registration requires minimal PHP changes (1–2 lines in PanelProvider).
• Filament Version Support: Explicitly supports Filament v3/v4, reducing version-specific risks. PHP 8.2+ ensures compatibility with modern Laravel stacks.
• Asset Handling: Optional asset publishing allows for static serving or customization, but auto-registration simplifies basic use cases.

Technical Risk

• Frontend Dependency Risk: Shepherd.js updates could break tours if not tested. Mitigation: Pin Shepherd.js version in package.json or use Laravel Mix/Vite to bundle dependencies.
• Customization Complexity: Advanced theming (e.g., dynamic step logic) may require JavaScript expertise. Risk: Misconfiguration could lead to broken tours.
• Performance Impact: Minimal for basic tours, but heavy customizations (e.g., many steps with large assets) could slow page load. Test with Lighthouse.
• Filament Updates: Plugin may need updates if Filament’s user menu structure changes. Monitor Filament’s release notes.

Key Questions

1. Tour Scope:
   • Will tours be static (predefined steps) or dynamic (e.g., role-based, triggered by user actions)? Dynamic tours may require backend logic to fetch step data.
2. Asset Management:
   • Should assets be published to public/ or bundled via Laravel Mix/Vite? Bundling reduces HTTP requests but adds build complexity.
3. Localization:
   • Does the admin panel support multiple languages? Tours may need i18n support (Shepherd.js has basic localization, but Filament’s strings may need syncing).
4. Analytics:
   • Is tracking tour completion/engagement required? Would need integration with Laravel Scout, Mixpanel, or similar.
5. Fallback Mechanism:
   • How to handle users with JavaScript disabled? Shepherd.js requires JS; consider a fallback (e.g., modal with tour instructions).
6. CI/CD Impact:
   • Does publishing assets require additional CI steps (e.g., artifact deployment)? Automate asset publishing in deployment pipelines if used.

Integration Approach

Stack Fit

• Ideal For:
  • Filament v3/v4 Admin Panels: Perfect for onboarding new users or training power users (e.g., complex dashboards, custom resource workflows).
  • Laravel + Inertia/Vue/React: Works seamlessly with Filament’s frontend stack (Shepherd.js is framework-agnostic).
  • Monolithic or Modular Apps: Low risk of breaking existing backend logic; frontend-only changes.
• Less Ideal For:
  • Headless Filament: If Filament is used purely as an API backend, this plugin offers no value.
  • Highly Dynamic UIs: Tours with steps that depend on real-time data may require custom backend endpoints.

Migration Path

1. Assessment Phase:
   • Audit Filament panel pages to identify tour-worthy workflows (e.g., "Create Invoice" or "Manage Users").
   • Define tour types (static vs. dynamic) and prioritize MVP steps.
2. Installation:
   • Add to composer.json and run composer install.
   • Register plugin in PanelProvider (5–10 minutes).
3. Configuration:
   • Basic: Use default tour button and steps (Shepherd.js config in published JS).
   • Custom: Publish assets and extend filament-tour-scripts.js for dynamic logic.
4. Testing:
   • Validate tours in staging with real users or QA.
   • Test edge cases: disabled JS, slow connections, Filament updates.
5. Deployment:
   • Roll out to a subset of users (e.g., new users only) via feature flags if needed.

Compatibility

• Filament Compatibility: Explicitly tested with v3/v4. Verify no breaking changes in minor Filament updates.
• PHP/Laravel: PHP 8.2+ ensures compatibility with Laravel 10/11. No Laravel-specific risks.
• Browser Support: Shepherd.js supports modern browsers; test on target user devices (e.g., mobile if applicable).
• Third-Party Conflicts: Check for CSS/JS conflicts with other Filament plugins (e.g., if they modify the user menu).

Sequencing

1. Phase 1: Static Tours (2–4 weeks):
   • Implement 2–3 critical workflow tours (e.g., "First Login" and "Create Record").
   • Use default Shepherd.js steps with minimal customization.
2. Phase 2: Dynamic Tours (3–6 weeks):
   • Extend with role-based or data-driven steps (e.g., "Your Pending Invoices").
   • Requires backend API endpoints or frontend logic to fetch dynamic content.
3. Phase 3: Analytics & Optimization (Ongoing):
   • Integrate tracking (e.g., Laravel events + third-party tools).
   • A/B test tour triggers (e.g., button placement, timing).

Operational Impact

Maintenance

• Low Ongoing Effort:
  • Static tours require no maintenance after initial setup.
  • Dynamic tours need periodic reviews if backend data structures change.
• Dependency Updates:
  • Monitor Shepherd.js and Filament for breaking changes. Pin versions in package.json or composer.json.
• Asset Management:
  • Published assets (CSS/JS) may need updates if Shepherd.js or plugin styles change. Automate republishing in CI/CD.

Support

• Troubleshooting:
  • Common issues: broken tours due to JS errors, misconfigured steps, or Filament updates.
  • Debugging tools: Browser DevTools (check Shepherd.js console logs), Laravel logs for plugin registration errors.
• User Support:
  • Provide clear documentation for users (e.g., "Skip Tour" option, keyboard shortcuts).
  • Offer a fallback (e.g., static help modal) for users with JS disabled.
• Escalation Path:
  • For complex issues, engage with the package maintainer (GitHub issues) or Filament community.

Scaling

• Performance:
  • Static Tours: Negligible impact; Shepherd.js is lightweight (~50KB gzipped).
  • Dynamic Tours: Risk of slower load times if steps include heavy assets (e.g., large images). Optimize by lazy-loading assets or reducing step complexity.
  • Concurrent Users: No server-side scaling concerns; purely client-side.
• Tour Complexity:
  • Limit tours to 5–7 steps per workflow to avoid cognitive overload.
  • Use Shepherd.js’s cancel or complete events to manage long tours.
• Multi-Tenancy:
  • If using Filament’s multi-tenancy, ensure tours are tenant-aware (e.g., don’t show "Admin Dashboard" steps to non-admins).

Failure Modes

Ramp-Up

• Developer Onboarding:
  • Time to First Tour: ~1 hour for basic setup; ~4 hours for custom dynamic tours.
  • Skills Required: Basic PHP (plugin registration), intermediate