Orca Harpoon Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require make-dev/orca-harpoon
   

   No additional configuration is required—middleware auto-injects the tool into local development.

2. First Use Case:

   • Open a Laravel/Livewire page in your browser.
   • Locate the harpoon icon (bottom-left corner).
   • Click it to activate the visual selector.
   • Hover over any HTML element—it highlights in blue.
   • Click the target element to scaffold a new Livewire component.

3. Where to Look First:

   • Browser UI: The harpoon icon and overlay UI are self-explanatory.
   • Generated Files: After scaffolding, check:
     • app/Livewire/[ComponentName].php (PHP class)
     • resources/views/livewire/[component-name].blade.php (Blade view)
     • app/Providers/AppServiceProvider.php (auto-registered via HarpoonServiceProvider).

Implementation Patterns

Core Workflow

1. Visual Selection:

   • Use the harpoon tool to extract reusable UI fragments (e.g., a card, form section, or widget) into standalone Livewire components.
   • Ideal for breaking down monolithic Blade templates into modular, stateful Livewire components.

2. Component Naming:

   • Follow PascalCase (e.g., UserAvatar, TaskQueue) for consistency with Livewire conventions.
   • Avoid generic names like Component—use semantic names tied to functionality.

3. Post-Scaffolding Integration:

   • Replace the original HTML with @livewire('ComponentName') in your Blade template.
   • Use the AI refactor prompt (generated by OrcaHarpoon) to automate this replacement in your IDE (e.g., VS Code with Claude integration).

4. State Management:

   • Leverage Livewire’s $data properties to bind form inputs or dynamic content.
   • Example:

     // Generated Livewire class
     public $name = '';
     public $isActive = false;
     

5. Styling and Assets:

   • Generated Blade views include a <style> block for scoped CSS. Move critical styles to a separate file (e.g., resources/css/livewire/[component-name].css) for maintainability.
   • Use @vite(['resources/css/livewire/*.css']) in your main layout to bundle them.

6. Reusability:

   • Pass props to child components via @livewire('ComponentName', ['prop1' => $value]).
   • Example use case: Extract a PaginationControls component and reuse it across paginated lists.

Advanced Patterns

• Nested Components:

  • Extract complex UI hierarchies (e.g., a DashboardSidebar containing SidebarItem components).
  • Use wire:model or wire:click for parent-child interactions.

• Dynamic Components:

  • Combine with Laravel’s @component directive to render Livewire components conditionally:

    @component('livewire.task-queue', ['tasks' => $tasks])
    @endcomponent
    

• Testing:

  • Use Livewire’s Livewire::test() to assert component behavior:

    public function test_component_renders()
    {
        Livewire::test('TaskQueue')
            ->assertSee('Pending Tasks');
    }
    

Gotchas and Tips

Pitfalls

1. Middleware Scope:

   • OrcaHarpoon only works in local environments. Disable it in production by adding to app/Http/Kernel.php:

     protected $middlewareGroups = [
         'web' => [
             // ... other middleware
             \MakeDev\OrcaHarpoon\Http\Middleware\HarpoonMiddleware::class, // Remove or wrap in `if (app()->environment('local'))`
         ],
     ];
     

2. Element Selection Quirks:

   • Avoid dynamic content: If the element relies on JavaScript to render (e.g., SPAs), OrcaHarpoon may capture an empty or incomplete DOM node.
   • Shadow DOM: Components using Shadow DOM (e.g., some Web Components) may not be selectable.

3. Generated Code Overrides:

   • OrcaHarpoon auto-generates a HarpoonServiceProvider in AppServiceProvider. If you manually register Livewire components, conflicts may arise. Solution: Merge registrations or disable auto-registration via config:

     'harpoon' => [
         'auto_register' => false,
     ],
     

4. AI Refactor Dependencies:

   • The AI prompt requires Claude or a compatible IDE plugin. Without it, you’ll need to manually replace HTML with @livewire().

5. Livewire Version Mismatch:

   • OrcaHarpoon is optimized for Livewire 4. If you’re on Livewire 3, generated syntax (e.g., wire:model.live) may fail. Solution: Downgrade or manually adjust the component.

Debugging Tips

• Inspect Generated Code:

  • Check storage/logs/laravel.log for harpoon-related errors (e.g., duplicate component names).
  • Use php artisan harpoon:clear-cache to reset cached selections.

• Component Not Updating?:

  • Ensure the Blade view path matches the Livewire class name (e.g., TaskQueue → resources/views/livewire/task-queue.blade.php).
  • Verify the component is registered in AppServiceProvider:

    HarpoonServiceProvider::registerLivewireComponents();
    

• Styling Issues:

  • Scoped CSS in generated views may conflict with global styles. Use !important sparingly; prefer BEM or utility classes.

Extension Points

1. Custom Templates:

   • Override the default Blade template by publishing assets:

     php artisan vendor:publish --provider="MakeDev\OrcaHarpoon\OrcaHarpoonServiceProvider" --tag="harpoon-views"
     

   • Modify resources/views/vendor/orca-harpoon/livewire.blade.php.

2. Pre/Post-Generation Hooks:

   • Extend the scaffolding logic by binding to the harpoon.generated event in EventServiceProvider:

     public function boot()
     {
         event(new \MakeDev\OrcaHarpoon\Events\ComponentGenerated('TaskQueue'));
     }
     

3. Element Filters:

   • Restrict selectable elements by modifying the middleware’s allowedSelectors config:

     'harpoon' => [
         'allowed_selectors' => [
             'div.card',
             'form.*.form',
             'section.widget',
         ],
     ],
     

4. Livewire Props Validation:

   • Add custom validation to generated components by extending the ComponentGenerated event:

     public function handleComponentGenerated($event)
     {
         $event->component->rules([
             'name' => 'required|min:3',
         ]);
     }