moonshine-setup-v4

name: moonshine-setup-v4 description: Use when working on MoonShine v4 installation, configuration, bootstrapping, routing, middleware, localization, artisan commands, project structure, IDE setup, or v3→v4 migration.

MoonShine v4 Setup

Requirements

• PHP 8.2+
• Laravel 10.48+
• Composer 2+

Installation

Step 1: Install via Composer

composer require moonshine/moonshine

Step 2: Run the installer

php artisan moonshine:install

The installer will interactively prompt you to configure:

1. Authentication -- enable/disable the middleware that checks whether the user has access to the panel.
2. Migrations -- required for built-in user and role management (moonshine_users, moonshine_user_roles tables).
3. Notifications -- enable/disable the notification system; optionally use the database driver.
4. Superuser -- if migrations are enabled, create an initial admin user.

Quick mode (non-interactive)

php artisan moonshine:install -Q

Accepts all defaults: authentication on, migrations on, notifications on, then prompts only for superuser credentials.

Installer flags

Starter kit (single command)

If you have laravel/installer globally:

laravel new example-app --using=moonshine/app

What the installer creates

The provider is automatically added to bootstrap/providers.php. A storage:link is also executed.

After installation, the admin panel is available at /admin.

Project directory structure

app/
  MoonShine/
    Layouts/
      MoonShineLayout.php    # Page template (menu, header, sidebar)
    Pages/
      Dashboard.php          # Default landing page
    Resources/               # ModelResource classes for CRUD
  Providers/
    MoonShineServiceProvider.php
config/
  moonshine.php
lang/
  vendor/
    moonshine/               # Translation files
public/
  vendor/
    moonshine/               # Published frontend assets

Configuration methods

MoonShine can be configured two ways. Provider configuration takes precedence over the config file.

Via config/moonshine.php

return [
    'title' => env('MOONSHINE_TITLE', 'MoonShine'),
    'logo' => 'vendor/moonshine/logo.svg',
    'logo_small' => 'vendor/moonshine/logo-small.svg',
    'use_migrations' => true,
    'use_notifications' => true,
    'use_database_notifications' => true,
    'use_routes' => true,
    'use_profile' => true,
    'prefix' => 'admin',
    'locale' => 'en',
    'auth' => [
        'enabled' => true,
        'guard' => 'moonshine',
    ],
    'layout' => \MoonShine\Laravel\Layouts\AppLayout::class,
    'palette' => \MoonShine\ColorManager\Palettes\PurplePalette::class,
];

You can keep only the keys that differ from defaults. See references/config-options.md and references/config-auth-localization.md for the full option reference.

Via MoonShineServiceProvider

use Illuminate\Support\ServiceProvider;
use MoonShine\Contracts\Core\DependencyInjection\CoreContract;
use MoonShine\Laravel\DependencyInjection\MoonShine;
use MoonShine\Laravel\DependencyInjection\MoonShineConfigurator;
use MoonShine\Contracts\Core\DependencyInjection\ConfiguratorContract;

class MoonShineServiceProvider extends ServiceProvider
{
    /**
     * @param  MoonShine  $core
     * @param  MoonShineConfigurator  $config
     */
    public function boot(
        CoreContract $core,
        ConfiguratorContract $config,
    ): void
    {
        $config
            ->title('My Application')
            ->logo('/assets/logo.png')
            ->logo('/assets/logo_small.png', true)
            ->useMigrations()
            ->useNotifications()
            ->useDatabaseNotifications()
            ->dir('app/MoonShine', 'App\MoonShine')
            ->locale('ru')
            ->locales(['en', 'ru'])
            ->guard('moonshine')
            ->authPipelines([])
            ->authorizationRules(
                function(ResourceContract $ctx, mixed $user, Ability $ability, mixed $data): bool {
                    return true;
                }
            )
            ->layout(\App\MoonShine\Layouts\CustomLayout::class)
            ->disk('public')
            ->cacheDriver('redis')
            ->homeRoute('moonshine.index')
            ->notFoundException(MoonShineNotFoundException::class);

        $core
            ->resources([...])
            ->pages([...]);
    }
}

Important: Route-related configuration (prefix, domain, page_prefix, resource_prefix) must be set in config/moonshine.php because routes are loaded before the service provider's boot method runs.

Important: use_migrations, use_notifications, and use_database_notifications must always be present in either moonshine.php or MoonShineServiceProvider.

Key configuration areas

Routing

// config/moonshine.php
'domain' => env('MOONSHINE_DOMAIN'),          // e.g., 'admin.example.com'
'prefix' => env('MOONSHINE_ROUTE_PREFIX', 'admin'),
'page_prefix' => env('MOONSHINE_PAGE_PREFIX', 'page'),
'resource_prefix' => env('MOONSHINE_RESOURCE_PREFIX', 'resource'),
'home_route' => 'moonshine.index',

Resulting URL pattern: /{prefix}/{resource_prefix}/{resourceUri}/{pageUri}

Authentication

// config/moonshine.php
'auth' => [
    'enabled' => true,               // set false to disable built-in auth
    'guard' => 'moonshine',          // Laravel auth guard name
    'model' => MoonshineUser::class, // user model (config file only)
    'middleware' => [
        Authenticate::class,
    ],
    'pipelines' => [],               // e.g., [TwoFactor::class]
],

'user_fields' => [
    'username' => 'email',
    'password' => 'password',
    'name' => 'name',
    'avatar' => 'avatar',
],

To use your own User model, set auth.model in config/moonshine.php and adjust user_fields to match your column names.

Localization

// config/moonshine.php
'locale' => 'en',
'locales' => ['en', 'ru'],
'locale_key' => '_lang',  // query parameter name for locale switching

Language files are stored in lang/vendor/moonshine/. The ChangeLocale middleware handles locale switching automatically.

Branding

// In MoonShineServiceProvider
$config
    ->logo('/images/logo.png')
    ->logo('/images/logo-mini.png', small: true);

// Colors via palette class (v4 uses palette system)
// config/moonshine.php
'palette' => \MoonShine\ColorManager\Palettes\PurplePalette::class,

// Or custom palette
'palette' => \App\MoonShine\Palettes\CorporatePalette::class,

Favicons

// config/moonshine.php
'favicons' => [
    'apple-touch' => '/vendor/moonshine/apple-touch-icon.png',
    '32' => '/vendor/moonshine/favicon-32x32.png',
    '16' => '/vendor/moonshine/favicon-16x16.png',
    'safari-pinned-tab' => '/vendor/moonshine/safari-pinned-tab.svg',
],

Artisan commands quick reference

Creating your first resource

php artisan moonshine:resource User

This generates a UserResource in app/MoonShine/Resources/ with CRUD pages (UserIndexPage, UserFormPage, UserDetailPage) and automatically registers it. The resource is then accessible at:

http://127.0.0.1:8000/admin/resource/user-resource/user-index-page

Replacing default pages and forms

// config/moonshine.php
'pages' => [
    'dashboard' => \App\MoonShine\Pages\DashboardPage::class,
    'profile' => ProfilePage::class,
    'login' => LoginPage::class,
    'error' => ErrorPage::class,
],

'forms' => [
    'login' => LoginForm::class,
    'filters' => FiltersForm::class,
],

Retrieve pages and forms programmatically:

$dashboard = moonshineConfig()->getPage('dashboard');
$loginForm = moonshineConfig()->getForm('login');

Or via dependency injection:

use MoonShine\Contracts\Core\DependencyInjection\ConfiguratorContract;
use MoonShine\Laravel\DependencyInjection\MoonShineConfigurator;

/**
 * @param  MoonShineConfigurator  $config
 */
public function index(ConfiguratorContract $config)
{
    $page = $config->getPage('dashboard');
    $form = $config->getForm('login');
}

IDE support

• PhpStorm: Install the MoonShine plugin for autocompletion and navigation.
• PhpStorm alternative: Install the MetaStorm plugin for improved MoonShine autocompletion.

MoonShine AI

For productive work with AI assistants, use the FortyFive package which provides additional context and tooling.

v3 to v4 migration summary

Auto upgrade tool

Use the warete/moonshine-upgrade package to automatically apply most migration changes.

Namespace changes

// Old (v3)                                              // New (v4)
use MoonShine\Laravel\Forms\FiltersForm;              // use MoonShine\Crud\Forms\FiltersForm;
use MoonShine\Laravel\Forms\LoginForm;                // use MoonShine\Crud\Forms\LoginForm;
use MoonShine\Laravel\Http\Responses\MoonShineJsonResponse; // use MoonShine\Crud\JsonResponse;
use MoonShine\Laravel\MoonShineRequest;               // use MoonShine\Contracts\Core\DependencyInjection\CrudRequestContract;
use MoonShine\Laravel\Enums\Action;                   // use MoonShine\Support\Enums\Action;
use MoonShine\Laravel\Enums\Ability;                  // use MoonShine\Support\Enums\Ability;
use MoonShine\Laravel\Traits\WithComponentsPusher;    // use MoonShine\Crud\Traits\WithComponentsPusher;

Resource restructuring (methods moved to pages)

Many resource methods moved to their corresponding CRUD pages in v4:

• rules(), modifyFormComponent() -- moved to form page class
• metrics(), queryTags(), filters(), modifyListComponent() -- moved to index page class
• modifyDetailComponent() -- moved to detail page class
• indexButtons() -- replaced by buttons() in index page class
• topButtons() -- replaced by topLeftButtons() and topRightButtons() in index page class
• formButtons() -- replaced by buttons() in form page class
• formBuilderButtons() -- replaced by formButtons() in form page class
• Properties $clickAction, $stickyTable, $stickyButtons, $columnSelection -- override modifyListComponent() in index page instead

Field changes

StackFields removed. Use Fieldset instead:

// v3
StackFields::make('Title', [Text::make('Field 1'), Text::make('Field 2')])

// v4
Fieldset::make('Title', [Text::make('Field 1'), Text::make('Field 2')])

Layout changes

• CompactLayout removed -- extend AppLayout instead.
• New palette system: PurplePalette is the default.

MenuItem parameter swap

MenuItem::make() now takes $filler first, then $label (optional, defaults to getLabel()):

// v3
MenuItem::make('Settings', SettingResource::class)

// v4
MenuItem::make(SettingResource::class)

Async methods require attribute

All async methods must have the #[AsyncMethod] attribute and now support DI:

use MoonShine\Crud\JsonResponse;
use MoonShine\Support\Attributes\AsyncMethod;

class MyPage extends Page
{
    #[AsyncMethod]
    public function someAsyncMethod(JsonResponse $response): JsonResponse
    {
        return $response->toast('Loaded successfully');
    }
}

Deprecated classes (removed in 5.0)

Cross-references

• moonshine-resources-v4 -- Creating and configuring ModelResource classes, CRUD operations, pages, filters, and actions.
• moonshine-fields-v4 -- Field types, validation, and field configuration.
• moonshine-components-v4 -- UI components (Grid, Column, Box, LineBreak, FormBuilder, TableBuilder, etc.).
• moonshine-appearance-v4 -- Layouts, menu configuration, color palettes, icons, and dark mode.
• moonshine-frontend-v4 -- API mode, SDUI, Alpine.js events, and async UI updates.
• moonshine-security-v4 -- Authentication, authorization, guards, pipelines, and user management.
• moonshine-advanced-v4 -- Controllers, handlers, testing, package development, and recipe patterns.
• references/config-options.md -- Full configuration option reference with both config file and ServiceProvider examples.
• references/config-auth-localization.md -- Artisan command signatures, localization details, and troubleshooting.