Getting Started

Minimal Setup

Installation:

composer require ijpatricio/mingle
npm install @vue/compiler-sfc vue@next react react-dom  # or your preferred JS framework

Add MingleJS to your resources/js/app.js (or Vite config):

import { Mingle } from 'minglejs';
window.Mingle = Mingle;

First Use Case: Create a Livewire component (php artisan make:livewire TodoList) and a Vue/React component (resources/js/components/TodoList.vue or TodoList.jsx).

Livewire Component (TodoList.php):

public function render()
{
    return view('livewire.todo-list', [
        'todos' => Todo::all(),
    ]);
}

Blade Template (todo-list.blade.php):

<div>
    @mingle('TodoList', [
        'todos' => $todos,
    ])
</div>

Vue Component (TodoList.vue):

<template>
    <ul>
        <li v-for="todo in todos" :key="todo.id">
            {{ todo.title }}
        </li>
    </ul>
</template>

<script>
export default {
    props: ['todos'],
}
</script>

Register the Component: In your JS entry file (e.g., resources/js/app.js), register the component:
```
Mingle.register('TodoList', () => import('./components/TodoList.vue'));
```
Run the App:
```
npm run dev
php artisan serve
```

Where to Look First

Official Documentation: Start with the "Getting Started" guide.
GitHub Issues: Check for common pitfalls or recent changes (e.g., Livewire 3.x compatibility).
Example Repo: Clone the demo project for a working example.

Implementation Patterns

Core Workflows

1. Data Flow Between Livewire and JS

Server-to-Client: Pass data via props in the @mingle directive:

@mingle('UserProfile', ['user' => $user, 'settings' => $settings])

Client-to-Server: Use Livewire’s $wire object inside JS components:

<script>
export default {
    methods: {
        updateProfile() {
            this.$wire.call('updateProfile', this.profileData);
        }
    }
}
</script>

Livewire Events: Emit events from Livewire to update JS components:

// Livewire component
$this->emit('profileUpdated', $user);

// Vue component
methods: {
    mounted() {
        window.Livewire.on('profileUpdated', user => {
            this.user = user;
        });
    }
}

2. Component Registration

Dynamic Imports: Use dynamic imports for code-splitting:

Mingle.register('HeavyComponent', () => import('./components/HeavyComponent.vue'));

Global vs. Local Registration: Register components globally (app-wide) or per-page:

// Global (app.js)
Mingle.register('GlobalComponent', () => import('./GlobalComponent.vue'));

// Per-page (e.g., in a specific Livewire component's JS)
Mingle.register('PageSpecificComponent', () => import('./PageSpecificComponent.vue'));

3. Styling and Assets

Scoped Styles: Use CSS modules or scoped styles in Vue/React to avoid conflicts:
```
<style scoped>
/* Scoped styles */
</style>
```

Asset Management: Load assets (e.g., images, fonts) via Laravel Mix/Vite:

// resources/js/app.js
import './assets/styles.css';
import './assets/fonts.css';

4. Error Handling

Fallback UI: Provide a static fallback in Blade if JS fails:

@mingle('TodoList', ['todos' => $todos], fallback: '<p>Loading todos...</p>')

Error Boundaries: Use Vue/React error boundaries to catch component errors:

<script>
export default {
    errorCaptured(err) {
        console.error('Component error:', err);
        return false; // Render fallback
    }
}
</script>

5. Testing

Unit Testing: Test JS components in isolation (e.g., with Jest or Vitest).

Integration Testing: Test Livewire + MingleJS interactions using Laravel’s Livewire::test():

public function test_mingle_component()
{
    $this->livewire(TodoList::class)
        ->assertSee('TodoList component');
}

E2E Testing: Use Playwright or Cypress to test hydration and interactivity.

Integration Tips

Livewire + Filament

Filament Widgets: Use MingleJS to add Vue/React widgets to Filament panels:

// Filament Resource
public static function getWidgets(): array
{
    return [
        MingleWidget::make('AnalyticsDashboard')
            ->props(['data' => $this->getAnalyticsData()]),
    ];
}

Custom Filament Forms: Replace Filament form fields with MingleJS components:
```
@mingle('CustomFormField', ['field' => $field])
```

Performance Optimization

Lazy Loading: Dynamically load MingleJS components:

Mingle.register('LazyComponent', () => import(/* webpackChunkName: "lazy" */ './LazyComponent.vue'));

Debounce Events: Throttle Livewire events to reduce server load:

// In a Vue component
import { debounce } from 'lodash';
methods: {
    search: debounce(function() {
        this.$wire.search(this.query);
    }, 300),
}

Debugging Tools

Livewire Logs: Enable Livewire logging to track server-side events:

Livewire::configureLogging(function ($log) {
    $log->debug();
});

Browser DevTools: Use the "Elements" tab to inspect mounted MingleJS components and the "Network" tab to monitor Livewire requests.

Gotchas and Tips

Pitfalls

Hydration Mismatches:
- Issue: Server-rendered HTML doesn’t match client-side Vue/React DOM, causing flickering or layout shifts.
- Fix: Use v-if or v-show in Vue to conditionally render components based on client-side state:
```
<template v-if="isMounted">
    
</template>
```
- Tip: Disable SSR for MingleJS components by setting ssr: false in your build tool (e.g., Vite).
Prop Binding:
- Issue: Livewire props aren’t properly passed to JS components due to serialization.
- Fix: Ensure props are JSON-serializable. Use json_encode() in Livewire:
```
@mingle('Component', ['data' => json_encode($complexData)])
```
- Tip: For large datasets, use Livewire::dispatch() to stream data via events.
Event Conflicts:
- Issue: Livewire and Vue/React events (e.g., click) conflict, causing unintended behavior.
- Fix: Use event modifiers in Vue/React to prevent default Livewire behavior:
```
<button @click.stop.prevent="handleClick">Click Me</button>
```
- Tip: Prefix custom events to avoid collisions (e.g., @mingle-click).
Build Tool Conflicts:
- Issue: Laravel Mix/Vite misconfigures MingleJS components, leading to 404s or blank mounts.
- Fix: Ensure your vite.config.js includes MingleJS assets:
```
export default defineConfig({
    build: {
        rollupOptions: {
            input: {
                app: './resources/js/app.js',
                mingle: './vendor/ijpatricio/mingle/dist/mingle.js',
            },
        },
    },
});
```
- Tip: Use @vite(['resources/js/app.js', 'resources/js/mingle-components.js']) in Blade.
Livewire 3.x Breaking Changes:
- Issue: MingleJS may not support newer Livewire features (e.g., wire:model.live).
- Fix: Check the GitHub issues for compatibility notes. Use feature flags to test:
```
if (app()->version() >=
```

Mingle Laravel Package