moonshine-frontend-v3

name: moonshine-frontend-v3 description: Use when working with MoonShine v3 as an API backend, JWT auth for API, SDUI (Server-Driven UI), Alpine.js events, JavaScript helpers, reactive fields, or async UI updates.

MoonShine v3 -- Frontend (API, SDUI, JS & Alpine.js)

Overview

MoonShine v3 provides a complete frontend interaction layer built on Alpine.js. It supports three modes of operation:

1. Standard HTML -- Server-rendered Blade views with Alpine.js reactivity (default).
2. API mode -- Add Accept: application/json to get JSON responses from CRUD routes, optionally with JWT authentication.
3. SDUI (Server-Driven UI) -- Request the component tree as a JSON structure for rendering in custom clients (mobile, SPA).

Alpine.js is bundled and initialized automatically. The global MoonShine JS class provides request helpers, UI toggles, and a callback registry for async response handling.

API Mode

Switch any MoonShine route to return JSON by including Accept: application/json in the request header.

Available CRUD Routes

GET    /admin/resource/{resourceUri}/crud                    -- Listing
POST   /admin/resource/{resourceUri}/crud                    -- Create
PUT    /admin/resource/{resourceUri}/crud/{resourceItem}     -- Edit
DELETE /admin/resource/{resourceUri}/crud/{resourceItem}     -- Delete
DELETE /admin/resource/{resourceUri}/crud                    -- Mass delete (ids[])

When using MoonShine purely as an API backend, disable session middleware in config/moonshine.php:

'middleware' => [
    // remove session-related middleware
],

See references/api-jwt.md for full API setup, JWT configuration, and OpenAPI generation.

JWT Quick Start

Install the JWT package for token-based API authentication:

composer require moonshine/jwt
php artisan vendor:publish --provider="MoonShine\JWT\Providers\JWTServiceProvider"

Add a base64-encoded secret to .env:

JWT_SECRET=YOUR_BASE64_SECRET_HERE

Configure middleware and auth pipeline in config/moonshine.php:

use MoonShine\JWT\JWTAuthPipe;
use MoonShine\JWT\Http\Middleware\AuthenticateApi;

return [
    'middleware' => [
        // empty -- no session middleware
    ],
    'auth' => [
        'middleware' => AuthenticateApi::class,
        'pipelines' => [
            JWTAuthPipe::class,
        ],
    ],
];

After successful authentication, use the returned token in subsequent requests:

Authorization: Bearer <token>

Cross-reference: moonshine-security-v3 covers JWT auth config, auth pipelines, and guard setup in detail.

Alpine.js Events

MoonShine uses custom DOM events (dispatched via Alpine.js $dispatch) to coordinate UI updates between components. Every event follows the pattern event_name:component_name.

Default Events (JsEvent enum)

Dispatching Events from PHP (Backend)

Use the AlpineJs helper class to build event strings:

use MoonShine\Support\AlpineJs;
use MoonShine\Support\Enums\JsEvent;

// Simple event
AlpineJs::event(JsEvent::TABLE_UPDATED, 'index')
// => "table_updated:index"

// Event with parameters
AlpineJs::event(JsEvent::TABLE_UPDATED, 'index', ['var' => 'foo'])
// => "table_updated:index|var=foo"

// Blade attribute format (for x-on directives)
AlpineJs::eventBlade(JsEvent::FORM_RESET, 'main-form')
// => "@form_reset:main-form.window"

Common usage pattern -- async form triggers table refresh:

FormBuilder::make('/crud/update')
    ->name('main-form')
    ->async(events: [
        AlpineJs::event(JsEvent::TABLE_UPDATED, 'crud-table'),
        AlpineJs::event(JsEvent::FORM_RESET, 'main-form'),
    ])
    ->fields([Text::make('Title')])

Dispatching Events from JavaScript (Frontend)

Native DOM:

document.addEventListener("DOMContentLoaded", () => {
    dispatchEvent(new CustomEvent("modal_toggled:my-modal"))
})

Alpine.js $dispatch:

this.$dispatch('modal_toggled:my-modal')

Dispatching Events via MoonShineJsonResponse

Return events from a controller or resource method so they fire after the response is processed:

use MoonShine\Laravel\Http\Responses\MoonShineJsonResponse;
use MoonShine\Support\AlpineJs;
use MoonShine\Support\Enums\JsEvent;

return MoonShineJsonResponse::make()
    ->toast('Saved!', ToastType::SUCCESS)
    ->events([
        AlpineJs::event(JsEvent::TABLE_UPDATED, 'index'),
    ]);

Blade Directives for Events

{{-- Declares: @table-updated-index.window="asyncRequest" --}}
<div x-data="myComponent"
    @defineEvent('table-updated', 'index', 'asyncRequest')
>
</div>

{{-- With condition --}}
<div x-data="myComponent"
    @defineEventWhen($isAsync, 'table-updated', 'index', 'asyncRequest')
>
</div>

Reactive Fields

MoonShine supports reactive form fields that send their values to the server on change and receive updated field HTML in return. This is handled by the FormBuilder Alpine.js component, which watches the reactive data object.

When a reactive field value changes:

1. A POST request is sent to reactiveUrl with { _component_name, values }.
2. The server returns { fields: { column: html }, values: { column: value } }.
3. The field wrapper HTML is replaced and focus is preserved on text inputs.

Cross-reference: moonshine-fields-v3 covers how to declare fields as reactive. moonshine-components-v3 covers FormBuilder's async() and reactive configuration.

Global MoonShine JS Class

The window.MoonShine object is available after the moonshine:init event fires.

Request Helper

MoonShine.request(ctx, '/url', method = 'get', body = {}, headers = {}, data = {})

UI Helpers

MoonShine.ui.toast('Hello world', 'success')
MoonShine.ui.toggleModal('modal-name')
MoonShine.ui.toggleOffCanvas('canvas-name')

Iterable Helpers

// Drag-and-drop reordering
MoonShine.iterable.sortable(container, url, group, events, attributes, callback)

// Reindex form element names after reorder
MoonShine.iterable.reindex(container, itemSelector)

Config

MoonShine.config().setToastDuration(5000)
MoonShine.config().forceRelativeUrls(true)

Async Response Callbacks

Components with async behavior (ActionButton, FormBuilder, TableBuilder, fields implementing HasAsyncContract) support the AsyncCallback DTO for hooking into the request lifecycle.

AsyncCallback Parameters

use MoonShine\Support\DTOs\AsyncCallback;

ActionButton::make('Do Something')
    ->method('myMethod', callback: AsyncCallback::with(
        beforeRequest: 'myBeforeRequest',    // JS function name
        responseHandler: 'myResponseHandler', // overrides default handling
        afterResponse: 'myAfterResponse',    // called after success (if no responseHandler)
    ))

Registering JS Callbacks

document.addEventListener("moonshine:init", () => {
    // Before the request is sent
    MoonShine.onCallback('myBeforeRequest', function(element, component) {
        console.log('Before request', element, component)
    })

    // Full response handler (replaces default behavior)
    MoonShine.onCallback('myResponseHandler', function(response, element, events, component) {
        console.log('Custom handler', response)
    })

    // After successful default processing
    MoonShine.onCallback('myAfterResponse', function(data, messageType, component) {
        console.log('After response', data, messageType)
    })
})

Fragment-Based Partial Updates

Wrap components in a Fragment to enable partial page updates without full reload:

Fragment::make([
    TableBuilder::make()->fields($fields)->items($items)->name('data-table')
])->name('data-fragment'),

ActionButton::make('Reload')
    ->dispatchEvent(AlpineJs::event(JsEvent::FRAGMENT_UPDATED, 'data-fragment'))

When the fragment_updated:data-fragment event fires, the Fragment component makes a GET request to its asyncUpdateRoute, replaces its own outerHTML with the response, and preserves Alpine.js state.

SDUI (Server-Driven UI)

Request any MoonShine page as a JSON component tree by adding the X-MS-Structure: true header. The response describes component types, states, attributes, and nested children -- suitable for rendering in mobile apps or custom SPA clients.

GET /admin/dashboard HTTP/1.1
X-MS-Structure: true

Additional control headers:

See references/sdui.md for full SDUI response structure and references/js-events-alpine.md for JS events and Alpine.js details.

Creating Custom Alpine.js Components

php artisan moonshine:component MyComponent

In the Blade view:

<div x-data="myComponent"></div>

Register the Alpine.js component (in a separate JS file loaded via AssetManager):

document.addEventListener("alpine:init", () => {
    Alpine.data("myComponent", () => ({
        init() {
            // component initialization
        },
    }))
})

Alpine.js is already installed and running (window.Alpine). Do not re-initialize it.

Cross-references

• moonshine-security-v3 -- JWT auth configuration, auth pipelines, guard setup, and the AuthenticateApi middleware.
• moonshine-components-v3 -- Async components (FormBuilder, TableBuilder, Fragment), event wiring, and the full component API.
• moonshine-resources-v3 -- API endpoints for resources, CRUD routes, MoonShineJsonResponse modifiers, and resource method handlers.
• moonshine-appearance-v3 -- Asset management for custom JS/CSS files.

Reference Files

• references/api-jwt.md -- Full API mode setup, JWT package configuration, and OpenAPI Generator.
• references/sdui.md -- SDUI concept, response structure, headers, component types, and state management.
• references/js-events-alpine.md -- JavaScript events reference, event parameters, fragment updates, Alpine.js integration, and async request flow.