MingleJS

https://github.com/ijpatricio/mingle
Admin
MingleJS is a Laravel Livewire library that enables React and Vue components to be used within...
Tokens:4,847
Snippets:42
Trust Score:9.2
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install Project Dependencies and Run MingleJS Demo

Source: https://github.com/ijpatricio/mingle/blob/main/wrapper-mingle/README.md

Clone the repository and execute these commands to set up the environment, install dependencies, generate keys, migrate the database, and start the development server for both backend and frontend.

```bash
cp .env.example .env
composer install
php artisan key:generate
touch database/database.sqlite
php artisan migrate:fresh --seed
php artisan serve
# In another terminal
npm ci
npm run dev
```

--------------------------------

### Run Development Commands

Source: https://github.com/ijpatricio/mingle/blob/main/CONTRIBUTING.md

Execute these commands to prepare the repository and start the development servers for the PHP wrapper project and Vite compilation.

```bash
# Pre-requisites
./run prepare-repo
```

```bash
# PHP server (wrapper project), will run on the port defined in `wrapper-mingle/.env` file.
./run dev:server
```

```bash
# Vite compilation (wrapper project)
./run dev:npm
```

--------------------------------

### Install MingleJS via Composer

Source: https://context7.com/ijpatricio/mingle/llms.txt

Install the MingleJS package and run the installer to configure your Laravel application. The installer sets up Vite configuration and layout files.

```bash
composer require ijpatricio/mingle

php artisan mingle:install

php artisan mingle:install --with-demo
```

--------------------------------

### React Todo List Component Example

Source: https://context7.com/ijpatricio/mingle/llms.txt

A React component demonstrating state management, user input handling, and server communication using 'wire' for adding, toggling, and deleting todos.

```jsx
// resources/js/todo-list/TodoList.jsx
import React, { useState } from 'react'

function TodoList({ wire, mingleData }) {
    const [todos, setTodos] = useState(mingleData.initialTodos)
    const [newTodo, setNewTodo] = useState('')
    const [loading, setLoading] = useState(false)

    const addTodo = async () => {
        if (!newTodo.trim()) return

        setLoading(true)
        try {
            // Call PHP method via Livewire wire
            const todo = await wire.addTodo(newTodo)
            setTodos([...todos, todo])
            setNewTodo('')
        } catch (error) {
            console.error('Failed to add todo:', error)
        } finally {
            setLoading(false)
        }
    }

    const toggleTodo = async (id) => {
        const completed = await wire.toggleTodo(id)
        setTodos(todos.map(todo =>
            todo.id === id ? { ...todo, completed } : todo
        ))
    }

    const deleteTodo = async (id) => {
        await wire.deleteTodo(id)
        setTodos(todos.filter(todo => todo.id !== id))
    }

    return (
        <div className="p-6 bg-white rounded-lg shadow">
            <h2 className="text-xl font-bold mb-4">
                Welcome, {mingleData.user}!
            </h2>

            <div className="flex gap-2 mb-4">
                <input
                    type="text"
                    value={newTodo}
                    onChange={(e) => setNewTodo(e.target.value)}
                    placeholder="Add a new todo..."
                    className="flex-1 px-3 py-2 border rounded"
                />
                <button
                    onClick={addTodo}
                    disabled={loading}
                    className="px-4 py-2 bg-blue-500 text-white rounded"
                >
                    {loading ? 'Adding...' : 'Add'}
                </button>
            </div>

            <ul className="space-y-2">
                {todos.map(todo => (
                    <li key={todo.id} className="flex items-center gap-2">
                        <input
                            type="checkbox"
                            checked={todo.completed}
                            onChange={() => toggleTodo(todo.id)}
                        />
                        <span className={todo.completed ? 'line-through' : ''}>
                            {todo.title}
                        </span>
                        <button
                            onClick={() => deleteTodo(todo.id)}
                            className="text-red-500"
                        >
                            Delete
                        </button>
                    </li>
                ))}
            </ul>
        </div>
    )
}

export default TodoList
```

--------------------------------

### Vue Counter Component Example

Source: https://context7.com/ijpatricio/mingle/llms.txt

A Vue component demonstrating prop usage for 'wire' and 'mingleData', state management with 'ref', and server communication via 'wire.doubleIt'. It also shows how to listen for server-dispatched events.

```vue
<!-- resources/js/counter/Counter.vue -->
<script setup>
import { ref } from 'vue'

const props = defineProps({
    wire: {},
    mingleData: {},
})

const count = ref(1)
const message = ref(props.mingleData.message)

const doubleCurrentCount = () => {
    props.wire.doubleIt(count.value).then((data) => {
        count.value = data
    })
}

// Listen to Livewire events dispatched from PHP
props.wire.on('doubleIt', (randomString) => {
    console.log('Event received from server:', randomString)
})
</script>

<template>
    <div class="p-6 bg-white rounded-lg shadow">
        <h2 class="text-lg font-bold">Vue Counter Component</h2>

        <div class="mt-4">
            Initial message: {{ message }}
        </div>

        <div class="mt-4 flex gap-4 items-center">
            <button
                @click="count = 1"
                class="px-4 py-2 bg-gray-200 rounded"
            >
                Reset
            </button>

            <span>Current Count: {{ count }}</span>

            <button
                @click="doubleCurrentCount"
                class="px-4 py-2 bg-blue-500 text-white rounded"
            >
                Double It (Server Call)
            </button>
        </div>
    </div>
</template>
```

--------------------------------

### Livewire Component Setup with MingleJS

Source: https://context7.com/ijpatricio/mingle/llms.txt

Implement the `HasMingles` interface and use the `InteractsWithMingles` trait in your Livewire component. Define the JavaScript component path using `component()` and pass initial data via `mingleData()`.

```php
<?php

namespace App\Livewire;

use Ijpatricio\Mingle\Concerns\InteractsWithMingles;
use Ijpatricio\Mingle\Contracts\HasMingles;
use Livewire\Component;

class TodoList extends Component implements HasMingles
{
    use InteractsWithMingles;

    public function component(): string
    {
        return 'resources/js/todo-list/index.js';
    }

    public function mingleData(): array
    {
        return [
            'initialTodos' => [
                ['id' => 1, 'title' => 'Learn MingleJS', 'completed' => false],
                ['id' => 2, 'title' => 'Build awesome apps', 'completed' => false],
            ],
            'user' => auth()->user()->name,
        ];
    }

    // Server-side methods callable from JavaScript via wire
    public function addTodo(string $title): array
    {
        $todo = [
            'id' => rand(1000, 9999),
            'title' => $title,
            'completed' => false,
        ];

        // Save to database here...

        return $todo;
    }

    public function toggleTodo(int $id): bool
    {
        // Toggle in database and return new state
        return true;
    }

    public function deleteTodo(int $id): void
    {
        // Delete from database
    }
}

```

--------------------------------

### Listen for Server Events in Vue Component

Source: https://context7.com/ijpatricio/mingle/llms.txt

In a Vue component, use `props.wire.on()` to listen for events dispatched from the PHP backend. This example demonstrates handling 'notification-read' and 'notifications-cleared' events.

```vue
<!-- resources/js/notifications/Notifications.vue -->
<script setup>
import { ref, onMounted } from 'vue'

const props = defineProps({
    wire: {},
    mingleData: {},
})

const notifications = ref(props.mingleData.notifications)

// Listen for server-dispatched events
props.wire.on('notification-read', ({ id, timestamp }) => {
    console.log(`Notification ${id} marked as read at ${timestamp}`)
    notifications.value = notifications.value.filter(n => n.id !== id)
})

props.wire.on('notifications-cleared', () => {
    console.log('All notifications cleared')
    notifications.value = []
})

const markAsRead = (id) => {
    props.wire.markAsRead(id)
}

const clearAll = () => {
    props.wire.clearAll()
}
</script>

<template>
    <div class="notification-center">
        <button @click="clearAll">Clear All</button>
        <div v-for="notification in notifications" :key="notification.id">
            {{ notification.message }}
            <button @click="markAsRead(notification.id)">Mark Read</button>
        </div>
    </div>
</template>
```

--------------------------------

### Initialize Starlight Tailwind Project

Source: https://github.com/ijpatricio/mingle/blob/main/docs/README.md

Use this command to scaffold a new Astro project pre-configured with Starlight and Tailwind CSS.

```bash
npm create astro@latest -- --template starlight/tailwind
```

--------------------------------

### View Project Structure

Source: https://github.com/ijpatricio/mingle/blob/main/docs/README.md

Displays the standard file and folder layout for an Astro + Starlight project.

```text
.
├── public/
├── src/
│   ├── assets/
│   ├── content/
│   │   ├── docs/
│   └── content.config.ts
├── astro.config.mjs
├── package.json
├── tailwind.config.mjs
└── tsconfig.json
```

--------------------------------

### Create Mingle Components with Artisan

Source: https://context7.com/ijpatricio/mingle/llms.txt

Use the `make:mingle` Artisan command to scaffold Livewire PHP components and their corresponding JavaScript files for React or Vue. You can specify custom file paths or force overwrites.

```bash
php artisan make:mingle react TodoList

php artisan make:mingle vue UserProfile

php artisan make:mingle react Dashboard --jsfile=resources/js/dashboard/Dashboard.js

php artisan make:mingle vue Settings --force
```

--------------------------------

### Configure MingleJS Defaults

Source: https://context7.com/ijpatricio/mingle/llms.txt

Publish and customize the MingleJS configuration file to set the default JavaScript base path and enable React preamble for hot module replacement.

```php
<?php

// config/mingle.php
return [

    /*
    |--------------------------------------------------------------------------
    | JavaScript Base Path
    |--------------------------------------------------------------------------
    |
    | The default directory where Mingle JavaScript components are stored.
    | This path is relative to your Laravel application root.
    |
    */
    'js-basepath' => 'resources/js',

    /*
    |--------------------------------------------------------------------------
    | React Preamble
    |--------------------------------------------------------------------------
    |
    | Enable the React refresh preamble for hot module replacement during
    | development. This should be enabled when using React components.
    |
    */
    'react_preamble_enabled' => true,

];
```

--------------------------------

### Configure Custom Vue App with createMingle

Source: https://context7.com/ijpatricio/mingle/llms.txt

Use createMingle to initialize a Vue app with custom plugins, global properties, or state management like Pinia.

```javascript
// resources/js/advanced-app/index.js
import { createMingle } from '@mingle/mingleVue'
import App from './App.vue'
import { createPinia } from 'pinia'

// Custom notification plugin
const notificationPlugin = {
    install: (app, options) => {
        app.config.globalProperties.$notify = (message, type = 'info') => {
            console.log(`[${type.toUpperCase()}] ${message}`)
            // Your notification logic here
        }
    }
}

createMingle('resources/js/advanced-app/index.js', ({
    createApp,
    props,
    el,
    wire,
    mingleId,
    wireId,
    mingleData
}) => {
    const app = createApp(App, props)

    // Add Pinia for state management
    app.use(createPinia())

    // Add custom plugins
    app.use(notificationPlugin)

    // Add global properties
    app.config.globalProperties.$api = {
        baseUrl: '/api/v1',
    }

    // Mount the app
    app.mount(el)

    return true
})
```

--------------------------------

### Implement Lazy Loading for Mingle Components

Source: https://context7.com/ijpatricio/mingle/llms.txt

Defer component loading using the #[Lazy] attribute and provide a placeholder method for loading states.

```php
<?php

namespace App\Livewire;

use Ijpatricio\Mingle\Concerns\InteractsWithMingles;
use Ijpatricio\Mingle\Contracts\HasMingles;
use Livewire\Attributes\Lazy;
use Livewire\Component;

#[Lazy]
class HeavyChart extends Component implements HasMingles
{
    use InteractsWithMingles;

    public function component(): string
    {
        return 'resources/js/chart/index.js';
    }

    public function mount()
    {
        // Simulate heavy database query
        sleep(2);
    }

    public function placeholder()
    {
        return <<<'HTML'
        <div class="flex items-center justify-center w-full h-64 bg-gray-100 rounded-lg animate-pulse">
            <div class="text-center">
                <svg class="w-12 h-12 mx-auto text-gray-400 animate-spin" fill="none" viewBox="0 0 24 24">
                    <circle class="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" stroke-width="4"></circle>
                    <path class="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4z"></path>
                </svg>
                <p class="mt-2 text-gray-500">Loading chart data...</p>
            </div>
        </div>
        HTML;
    }

    public function mingleData(): array
    {
        return [
            'chartData' => $this->fetchChartData(),
            'options' => ['responsive' => true],
        ];
    }

    private function fetchChartData(): array
    {
        // Heavy database queries here
        return [
            'labels' => ['Jan', 'Feb', 'Mar', 'Apr', 'May'],
            'datasets' => [
                ['label' => 'Sales', 'data' => [12, 19, 3, 5, 2]],
            ],
        ];
    }
}
```

--------------------------------

### Register React Component with MingleJS

Source: https://context7.com/ijpatricio/mingle/llms.txt

Create a JavaScript entry file to register your React component. The component will receive 'wire' for server communication and 'mingleData' for initial data.

```javascript
// resources/js/todo-list/index.js
import mingle from '@mingle/mingleReact.jsx'
import TodoList from './TodoList.jsx'

mingle('resources/js/todo-list/index.js', TodoList)
```

--------------------------------

### Dispatch Server Events to JavaScript

Source: https://context7.com/ijpatricio/mingle/llms.txt

Use Livewire's dispatch mechanism in a PHP component to send events to JavaScript. Ensure the Livewire component implements `HasMingles` and uses `InteractsWithMingles`.

```php
<?php

namespace App\Livewire;

use Ijpatricio\Mingle\Concerns\InteractsWithMingles;
use Ijpatricio\Mingle\Contracts\HasMingles;
use Livewire\Component;

class NotificationCenter extends Component implements HasMingles
{
    use InteractsWithMingles;

    public function component(): string
    {
        return 'resources/js/notifications/index.js';
    }

    public function mingleData(): array
    {
        return [
            'notifications' => [],
        ];
    }

    public function markAsRead(int $notificationId): void
    {
        // Update database...

        // Dispatch event to JavaScript component
        $this->dispatch('notification-read',
            id: $notificationId,
            timestamp: now()->toISOString()
        );
    }

    public function clearAll(): void
    {
        // Clear all notifications in database...

        $this->dispatch('notifications-cleared');
    }
}
```

--------------------------------

### Register Vue Component with MingleJS

Source: https://context7.com/ijpatricio/mingle/llms.txt

Register Vue components using MingleJS similarly to React. Components receive 'wire' and 'mingleData' as props. Livewire events can be listened to using 'wire.on()'.

```javascript
// resources/js/counter/index.js
import mingle from '@mingle/mingleVue'
import Counter from './Counter.vue'

mingle('resources/js/counter/index.js', Counter)
```

--------------------------------

### Integrate Mingle Components in Blade

Source: https://context7.com/ijpatricio/mingle/llms.txt

Register Mingle assets using the @mingles directive and render components within Blade views.

```blade
<!-- resources/views/layouts/app.blade.php -->
<!DOCTYPE html>
<html lang="{{ str_replace('_', '-', app()->getLocale()) }}">
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>{{ config('app.name') }}</title>

    @vite(['resources/css/app.css', 'resources/js/app.js'])
    @mingles
    @livewireStyles
</head>
<body>
    {{ $slot }}

    @livewireScripts
</body>
</html>
```

```blade
<!-- resources/views/dashboard.blade.php -->
<x-app-layout>
    <div class="py-12">
        <div class="max-w-7xl mx-auto sm:px-6 lg:px-8">
            <h1 class="text-2xl font-bold mb-6">Dashboard</h1>

            <!-- Use Mingle components like any Livewire component -->
            <div class="grid grid-cols-2 gap-6">
                <livewire:todo-list />
                <livewire:vue-counter />
            </div>
        </div>
    </div>
</x-app-layout>
```
Tokens:
Raw