Appearance

Assets

Video guide

Basics

AssetManager in MoonShine provides a convenient way to manage CSS and JavaScript assets for your admin panel. It supports various types of assets, including external files, inline code, and versioning.

Asset Types

In MoonShine, there are several types of assets:

  • MoonShine\AssetManager\Js - js through <script src> tag,
  • MoonShine\AssetManager\Css - css through <link> tag,
  • MoonShine\AssetManager\InlineCss - css through <style> tag,
  • MoonShine\AssetManager\InlineJs - js through <script> tag,
  • MoonShine\AssetManager\Raw - arbitrary content in head.

JavaScript Files

 namespaces
use MoonShine\AssetManager\Js;
 
// Basic inclusion
Js::make('/js/app.js');
 
// With deferred loading
Js::make('/js/app.js')->defer();
 
// With attributes
Js::make('/js/app.js')->customAttributes([
    'data-module' => 'main'
]);
 namespaces
use MoonShine\AssetManager\Js;
 
// Basic inclusion
Js::make('/js/app.js');
 
// With deferred loading
Js::make('/js/app.js')->defer();
 
// With attributes
Js::make('/js/app.js')->customAttributes([
    'data-module' => 'main'
]);

CSS Files

 namespaces
use MoonShine\AssetManager\Css;
 
// Basic inclusion
Css::make('/css/styles.css');
 
// With deferred loading
Css::make('/css/styles.css')->defer();
 
// With attributes
Css::make('/css/styles.css')->customAttributes([
    'media' => 'print'
]);
 namespaces
use MoonShine\AssetManager\Css;
 
// Basic inclusion
Css::make('/css/styles.css');
 
// With deferred loading
Css::make('/css/styles.css')->defer();
 
// With attributes
Css::make('/css/styles.css')->customAttributes([
    'media' => 'print'
]);

Inline JavaScript

 namespaces
use MoonShine\AssetManager\InlineJs;
 
InlineJs::make(<<<'JS'
    document.addEventListener("DOMContentLoaded", function() {
        console.log("Loaded");
    });
JS);
 namespaces
use MoonShine\AssetManager\InlineJs;
 
InlineJs::make(<<<'JS'
    document.addEventListener("DOMContentLoaded", function() {
        console.log("Loaded");
    });
JS);

Inline CSS

 namespaces
use MoonShine\AssetManager\InlineCss;
 
InlineCss::make(<<<'CSS'
    .custom-class {
        color: red;
    }
CSS);
 namespaces
use MoonShine\AssetManager\InlineCss;
 
InlineCss::make(<<<'CSS'
    .custom-class {
        color: red;
    }
CSS);

Raw Content

 namespaces
use MoonShine\AssetManager\Raw;
 
Raw::make('<link rel="preconnect" href="https://fonts.googleapis.com">');
 namespaces
use MoonShine\AssetManager\Raw;
 
Raw::make('<link rel="preconnect" href="https://fonts.googleapis.com">');

Asset Collections

AssetManager allows managing the loading order of assets. We recommend using DI to start interacting with AssetManager, for the service is responsible through the interface MoonShine\Contracts\AssetManager\AssetManagerContract. Also, MoonShine provides convenient methods to interact with AssetManager in different entities such as CrudResource, Page, Layout, Component and Field.

 namespaces
use MoonShine\AssetManager\Js;
 
// Add assets to the end
$assetManager->append([
    Js::make('/js/last.js')
]);
 
// Add assets to the beginning
$assetManager->prepend([
    Js::make('/js/first.js')
]);
 
// Add assets in the order of addition
$assetManager->add([
    Js::make('/js/middle.js')
]);
 namespaces
use MoonShine\AssetManager\Js;
 
// Add assets to the end
$assetManager->append([
    Js::make('/js/last.js')
]);
 
// Add assets to the beginning
$assetManager->prepend([
    Js::make('/js/first.js')
]);
 
// Add assets in the order of addition
$assetManager->add([
    Js::make('/js/middle.js')
]);

The append() method will always add assets before the main list from CrudResource, Page, Layout, Component, Field, while prepend() will add them after. The add() method will depend on the lifecycle of the application. Suppose you are adding assets to ModelResource, but before the page is displayed, Layout will be called, which will also add assets, thus the assets from Layout will be added last.

You can also use the helper moonshine()->getAssetManager()

Asset Modification

You can modify the asset collection using closures:

$assetManager->modifyAssets(function($assets) {
    // Modify the asset collection
    return array_filter($assets, function($asset) {
        return !str_contains($asset->getLink(), 'remove-this');
    });
});
$assetManager->modifyAssets(function($assets) {
    // Modify the asset collection
    return array_filter($assets, function($asset) {
        return !str_contains($asset->getLink(), 'remove-this');
    });
});

Versioning

AssetManager supports versioning of assets to manage caching, by default it will use the version of MoonShine, but you can override it for a specific asset:

 namespaces
use MoonShine\AssetManager\Js;
 
// Adding a version to an individual asset
Js::make('/js/app.js')->version('1.0.0');
 
// Result: /js/app.js?v=1.0.0
 namespaces
use MoonShine\AssetManager\Js;
 
// Adding a version to an individual asset
Js::make('/js/app.js')->version('1.0.0');
 
// Result: /js/app.js?v=1.0.0

Versioning automatically adds a v parameter to the asset URL. If the URL already contains query parameters, the version will be added with &.

How to Add Assets

Global

// MoonShineServiceProvider
 namespaces
use MoonShine\AssetManager\Js;
use MoonShine\Contracts\AssetManager\AssetManagerContract;
use MoonShine\Contracts\Core\DependencyInjection\ConfiguratorContract;
use MoonShine\Contracts\Core\DependencyInjection\CoreContract;
 
public function boot(
    CoreContract $core,
    ConfiguratorContract $config,
    AssetManagerContract $assets,
): void
{
    $assets->add(Js::make('/js/app.js'));
}
// MoonShineServiceProvider
 namespaces
use MoonShine\AssetManager\Js;
use MoonShine\Contracts\AssetManager\AssetManagerContract;
use MoonShine\Contracts\Core\DependencyInjection\ConfiguratorContract;
use MoonShine\Contracts\Core\DependencyInjection\CoreContract;
 
public function boot(
    CoreContract $core,
    ConfiguratorContract $config,
    AssetManagerContract $assets,
): void
{
    $assets->add(Js::make('/js/app.js'));
}

Layout

 namespaces
use Illuminate\Support\Facades\Vite;
use MoonShine\AssetManager\Js;
 
final class MoonShineLayout extends AppLayout
{
    protected function assets(): array
    {
        return [
            Js::make(Vite::asset('resources/js/app.js'))
        ];
    }
}
 namespaces
use Illuminate\Support\Facades\Vite;
use MoonShine\AssetManager\Js;
 
final class MoonShineLayout extends AppLayout
{
    protected function assets(): array
    {
        return [
            Js::make(Vite::asset('resources/js/app.js'))
        ];
    }
}

CrudResource

 namespaces
use MoonShine\AssetManager\InlineJs;
use MoonShine\AssetManager\Js;
 
protected function onLoad(): void
{
    $this->getAssetManager()
        ->prepend(InlineJs::make('alert(1)'))
        ->append(Js::make('/js/app.js'));
}
 namespaces
use MoonShine\AssetManager\InlineJs;
use MoonShine\AssetManager\Js;
 
protected function onLoad(): void
{
    $this->getAssetManager()
        ->prepend(InlineJs::make('alert(1)'))
        ->append(Js::make('/js/app.js'));
}

Page

 namespaces
use MoonShine\AssetManager\Css;
use MoonShine\AssetManager\Js;
 
protected function onLoad(): void
{
    parent::onLoad();
 
    $this->getAssetManager()
        ->add(Css::make('/css/app.css'))
        ->append(Js::make('/js/app.js'));
}
 namespaces
use MoonShine\AssetManager\Css;
use MoonShine\AssetManager\Js;
 
protected function onLoad(): void
{
    parent::onLoad();
 
    $this->getAssetManager()
        ->add(Css::make('/css/app.css'))
        ->append(Js::make('/js/app.js'));
}

Component

On the Fly

 namespaces
use MoonShine\AssetManager\Css;
use MoonShine\AssetManager\Js;
use MoonShine\UI\Components\Layout\Box;
 
Box::make()->addAssets([
    Js::make('/js/custom.js'),
    Css::make('/css/styles.css')
]);
 namespaces
use MoonShine\AssetManager\Css;
use MoonShine\AssetManager\Js;
use MoonShine\UI\Components\Layout\Box;
 
Box::make()->addAssets([
    Js::make('/js/custom.js'),
    Css::make('/css/styles.css')
]);

When Creating a Component

 namespaces
use MoonShine\AssetManager\Css;
use MoonShine\AssetManager\Js;
use MoonShine\UI\Components\MoonShineComponent;
 
final class MyComponent extends MoonShineComponent
{
    /**
     * @return list<AssetElementContract>
     */
    protected function assets(): array
    {
        return [
            Js::make('/js/custom.js'),
            Css::make('/css/styles.css')
        ];
    }
}
 namespaces
use MoonShine\AssetManager\Css;
use MoonShine\AssetManager\Js;
use MoonShine\UI\Components\MoonShineComponent;
 
final class MyComponent extends MoonShineComponent
{
    /**
     * @return list<AssetElementContract>
     */
    protected function assets(): array
    {
        return [
            Js::make('/js/custom.js'),
            Css::make('/css/styles.css')
        ];
    }
}

When Creating a Component via AssetManager

 namespaces
use MoonShine\AssetManager\Css;
use MoonShine\AssetManager\Js;
use MoonShine\UI\Components\MoonShineComponent;
 
final class MyComponent extends MoonShineComponent
{
    protected function booted(): void
    {
        parent::booted();
 
        $this->getAssetManager()
          ->add(Css::make('/css/app.css'))
          ->append(Js::make('/js/app.js'));
    }
}
 namespaces
use MoonShine\AssetManager\Css;
use MoonShine\AssetManager\Js;
use MoonShine\UI\Components\MoonShineComponent;
 
final class MyComponent extends MoonShineComponent
{
    protected function booted(): void
    {
        parent::booted();
 
        $this->getAssetManager()
          ->add(Css::make('/css/app.css'))
          ->append(Js::make('/js/app.js'));
    }
}

Field

The same as with Component, since Field is a component.

Conclusion via Blade

<x-moonshine::layout.assets>
    @vite([
        'resources/css/main.css',
        'resources/js/app.js',
    ], 'vendor/moonshine')
</x-moonshine::layout.assets>
<x-moonshine::layout.assets>
    @vite([
        'resources/css/main.css',
        'resources/js/app.js',
    ], 'vendor/moonshine')
</x-moonshine::layout.assets>

Custom Build

When working with MoonShine, especially when using the Blade approach, you may need additional TailwindCSS CSS classes that are not included in the original MoonShine build. For this purpose, a custom build is suitable, which will include MoonShine, and you will be able to build with your own set of classes and styles + MoonShine.

Automatic Publishing

To automatically publish the custom build, run the command:

php artisan moonshine:publish
php artisan moonshine:publish

Select Assets Template.

After that, the following files will be published and replaced:

  • vite.config.js,
  • postcss.config.js,
  • resources/css/app.css.

For automatic asset publishing, TailwindCSS 4+ and Laravel 12+ are required.

You will only need to add the assets to your project.

Implementation via MoonShineLayout

You need to add MoonShine JavaScript $this->getMainThemeJs(), as well as your application assets, where Css::make(Vite::asset('resources/css/app.css')) also contains MoonShine CSS.

 namespaces
use Illuminate\Support\Facades\Vite;
use MoonShine\AssetManager\Css;
use MoonShine\AssetManager\Js;
 
final class MoonShineLayout extends AppLayout
{
    protected function assets(): array
    {
        return [
            $this->getMainThemeJs(),
            Css::make(Vite::asset('resources/css/app.css')),
            Js::make(Vite::asset('resources/js/app.js')),
        ];
    }
}
 namespaces
use Illuminate\Support\Facades\Vite;
use MoonShine\AssetManager\Css;
use MoonShine\AssetManager\Js;
 
final class MoonShineLayout extends AppLayout
{
    protected function assets(): array
    {
        return [
            $this->getMainThemeJs(),
            Css::make(Vite::asset('resources/css/app.css')),
            Js::make(Vite::asset('resources/js/app.js')),
        ];
    }
}

Implementation via Blade

You need to add MoonShine JavaScript @vite(['resources/js/app.js'], 'vendor/moonshine'), as well as your application assets, where resources/css/app.css also contains MoonShine CSS.

<x-moonshine::layout.head>
    <x-moonshine::layout.assets>
        @vite(['resources/js/app.js'], 'vendor/moonshine')
        @vite(['resources/css/app.css', 'resources/js/app.js'])
    </x-moonshine::layout.assets>
</x-moonshine::layout.head>
<x-moonshine::layout.head>
    <x-moonshine::layout.assets>
        @vite(['resources/js/app.js'], 'vendor/moonshine')
        @vite(['resources/css/app.css', 'resources/js/app.js'])
    </x-moonshine::layout.assets>
</x-moonshine::layout.head>

Manual Implementation of Custom Build

vite.config.js

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
 
export default defineConfig({
    plugins: [
        laravel({
            input: ['resources/css/app.css', 'resources/js/app.js'],
            refresh: true,
        }),
    ],
    resolve: {
        alias: {
            '@moonshine-resources': '/vendor/moonshine/moonshine/src/UI/resources',
        }
    },
});
import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
 
export default defineConfig({
    plugins: [
        laravel({
            input: ['resources/css/app.css', 'resources/js/app.js'],
            refresh: true,
        }),
    ],
    resolve: {
        alias: {
            '@moonshine-resources': '/vendor/moonshine/moonshine/src/UI/resources',
        }
    },
});

The tailwindcss() plugin has been removed:

 plugins: [
     laravel({
         input: ['resources/css/app.css', 'resources/js/app.js'],
         refresh: true,
     }),
-    tailwindcss() 
 ]
 plugins: [
     laravel({
         input: ['resources/css/app.css', 'resources/js/app.js'],
         refresh: true,
     }),
-    tailwindcss() 
 ]

An alias has been added for the paths where MoonShine resources are located:

resolve: {
    alias: {
        '@moonshine-resources': '/vendor/moonshine/moonshine/src/UI/resources',
    }
}
resolve: {
    alias: {
        '@moonshine-resources': '/vendor/moonshine/moonshine/src/UI/resources',
    }
}

postcss.config.js

You need to install @tailwindcss/postcss and publish postcss.config.js with the following content:

export default {
  plugins: {
    '@tailwindcss/postcss': {},
  },
};
export default {
  plugins: {
    '@tailwindcss/postcss': {},
  },
};

resources/css/app.css

Add the MoonShine CSS import:

@import '../../vendor/moonshine/moonshine/src/UI/resources/css/main.css';
 
@source '../../vendor/laravel/framework/src/Illuminate/Pagination/resources/views/*.blade.php';
@source '../../storage/framework/views/*.php';
@source '../**/*.blade.php';
@source '../**/*.js';
@import '../../vendor/moonshine/moonshine/src/UI/resources/css/main.css';
 
@source '../../vendor/laravel/framework/src/Illuminate/Pagination/resources/views/*.blade.php';
@source '../../storage/framework/views/*.php';
@source '../**/*.blade.php';
@source '../**/*.js';