DOCSEARCHbyAlgolia
Submit Docs

MingleJS Documentation

repository·main·Indexed 19 days ago

https://github.com/ijpatricio/mingle

A bridge for Laravel Livewire applications that allows developers to integrate React or Vue components as 'islands of interactivity'. MingleJS enables seamless communication between client-side JS components and the server via Livewire's $wire proxy, supporting data passing and direct server actions.

Tokens
4.6K
Snippets
18
Records
28
Agent score
66%

What's inside MingleJS

  1. Overview of MingleJS

    main
    MingleJS is a bridge for Laravel Livewire applications that allows you to integrate React or Vue components directly into your Livewire ecosystem. It enables 'islands of interactivity' where a server-side rendered div is mounted as a client-side JS component. This allows developers to combine the server-side simplicity of Livewire with the rich client-side capabilities of modern JS frameworks.

  2. How MingleJS works

    main

    MingleJS operates by rendering a placeholder div on the server via a Livewire component. Once the page reaches the client, the specified React or Vue component is mounted onto that div.

    Key features include:

    • Data Passing: You can pass data from the backend Livewire component directly to the frontend JS component.
    • Server Actions: Instead of using standard Ajax clients (like Axios or Fetch), you can leverage Livewire's $wire object to make server requests directly from your JS component (e.g., $wire.methodName(params)).

  3. Understand the Starlight project structure

    main

    A standard Starlight project follows this directory structure:

    • src/content/docs/: The primary location for documentation. Starlight automatically exposes .md or .mdx files in this directory as routes based on their filenames.
    • src/assets/: Place images here to embed them in Markdown using relative links.
    • public/: Store static assets like favicons here.
    • astro.config.mjs: Configuration for the Astro project.
    • tailwind.config.mjs: Configuration for Tailwind CSS.
    • package.json: Project dependencies and scripts.
    .
├── public/
├── src/
│   ├── assets/
│   ├── content/
│   │   ├── docs/
│   └── content.config.ts
├── astro.config.mjs
├── package.json
├── tailwind.config.mjs
└── tsconfig.json

  5. Initialize a Starlight Starter Kit with Tailwind

    main

    You can scaffold a new Astro project using the Starlight template with Tailwind CSS pre-configured by running the following command via npm:

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

  9. Set up the MingleJS Demo application

    main

    To run the MingleJS demo locally, you need to set up both the PHP (Laravel) backend and the Node.js frontend. Follow these steps in order:

    1. Clone the repository.
    2. Configure Environment: Copy the example environment file to .env.
    3. Install PHP Dependencies: Use composer install to install required packages.
    4. Generate Application Key: Run the Laravel key generation command.
    5. Initialize Database: Create an empty SQLite database file and run migrations with seeds to populate initial data.
    6. Start Backend Server: Run the Laravel development server.
    7. Start Frontend Assets: In a separate terminal, install Node dependencies and start the development build process.
    # Backend setup
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 (Frontend setup)
npm ci
npm run dev

  10. Configure the MingleJS development environment with Docker Compose

    main

    The docker-compose.yml file defines a webapp service for running the MingleJS wrapper in a containerized environment. It uses a PHP runtime and maps specific ports for the web application and the Vite development server.

    Key configuration details:

    • Build Context: Uses the Dockerfile located at docker/dev/runtimes/php/Dockerfile.
    • Build Arguments: Supports USER_ID and GROUP_ID to align container permissions with the host user.
    • Port Mapping:
      • The application port defaults to 8080 (configurable via APP_PORT).
      • The Vite port defaults to 5173 (configurable via VITE_PORT).
    • Volumes:
      • ./wrapper-mingle is mounted to /var/www/html (the web root).
      • The project root . is mounted to /var/www/html/packages/mingle so the wrapper can access the core package via composer.json configuration.
    • Networking:
      • Uses the web network.
      • Includes host.docker.internal:host-gateway in extra_hosts to allow the container to communicate with the host machine.
    services:
  webapp:
    build:
      context: .
      dockerfile: docker/dev/runtimes/php/Dockerfile
      args:
        USER_ID: $USER_ID
        GROUP_ID: $GROUP_ID
    image: minglejs-wrapper
    extra_hosts:
        - 'host.docker.internal:host-gateway'
    ports:
        - '${APP_PORT:-8080}:8080'
        - '${VITE_PORT:-5173}:${VITE_PORT:-5173}'
    volumes:
        - './wrapper-mingle:/var/www/html'
        - '.:/var/www/html/packages/mingle'
    networks:
        - web

networks:
    web:

  11. Install the Mingle boilerplate via the CLI

    main

    Use the mingle:install Artisan command to set up the Mingle boilerplate in your Laravel application. This command automates the modification of your layout files and Vite configuration to support MingleJS.

    By default, it attempts to update:

    • resources/views/layouts/guest.blade.php
    • resources/views/layouts/app.blade.php
    • Your Vite configuration

    If the command cannot find or modify these files, it will warn that 'Some files were not changed. Nothing to do.'

    php artisan mingle:install

  12. Configure React Preamble for Vite Hot Module Replacement

    main

    When using Vite's Hot Module Replacement (HMR), Mingle can automatically include the React Refresh preamble to ensure React components update correctly without full page reloads. This behavior is controlled by the mingle.react_preamble_enabled configuration key.

    To enable this, ensure your configuration file has:

    'react_preamble_enabled' => true,

    Note: The preamble is only injected if app(Vite::class)->isRunningHot() returns true.