moonshine-setup-v3

name: moonshine-setup-v3 description: Use when installing, configuring, or bootstrapping a MoonShine v3 admin panel. Covers installation, configuration, routing, middleware, localization, and artisan commands.

MoonShine v3 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 panel access.
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. Template theme -- standard or compact layout.
5. Superuser -- create an initial admin user (only if migrations are enabled).

Quick mode (non-interactive)

php artisan moonshine:install -Q

Accepts all defaults: authentication on, migrations on, notifications on, standard theme, 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,
];

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\Laravel\DependencyInjection\ConfiguratorContract;

class MoonShineServiceProvider extends ServiceProvider
{
    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')
            ->layout(\App\MoonShine\Layouts\CustomLayout::class)
            ->disk('public')
            ->cacheDriver('redis')
            ->homeRoute('moonshine.index');

        $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 ColorManager
$colors
    ->primary('#2563EB')
    ->secondary('#93C5FD');

Common artisan commands

Creating your first resource

php artisan moonshine:resource User

This generates a UserResource in app/MoonShine/Resources/ and automatically registers it. The resource is then accessible at:

http://127.0.0.1:8000/admin/resource/user-resource/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');

IDE support

For PhpStorm users, install the MetaStorm plugin for improved MoonShine autocompletion and navigation.

Cross-references

• moonshine-resources-v3 -- Creating and configuring ModelResource classes, CRUD operations, fields, filters, and actions.
• moonshine-fields-v3 -- Field types, validation, and field configuration.
• moonshine-components-v3 -- UI components (Grid, Column, Box, LineBreak, etc.).
• moonshine-appearance-v3 -- Layouts, menus, custom pages, and navigation structure.
• moonshine-security-v3 -- Authentication customization, guards, pipelines, and user management.