Registering assets

Introduction

All packages in the Filament ecosystem share an asset management system. This allows both official plugins and third-party plugins to register CSS and JavaScript files that can then be consumed by Blade views.

The `FilamentAsset` facade

Use FilamentAsset to register asset files from your application or a plugin. Running php artisan filament:assets copies them into the application’s /public directory. Assets always have a unique ID chosen by you, which is used as the file name when the asset is copied into the /public directory. This ID is also used to reference the asset in Blade views. While the ID is unique, if you are registering assets for a plugin, then you do not need to worry about IDs clashing with other plugins, since the asset will be copied into a directory named after your plugin. The FilamentAsset facade should be used in the boot() method of a service provider. It can be used inside an application service provider such as AppServiceProvider, or inside a plugin service provider. The FilamentAsset facade has one main method, register(), which accepts an array of assets to register:

use Filament\Support\Facades\FilamentAsset;

public function boot(): void
{
    // ...

    FilamentAsset::register([
        // ...
    ]);

    // ...
}

Registering assets for a plugin

When registering assets for a plugin, you should pass the name of the Composer package as the second argument of the register() method:

use Filament\Support\Facades\FilamentAsset;

FilamentAsset::register([
    // ...
], package: 'danharrin/filament-blog');

Now, all the assets for this plugin will be copied into their own directory inside /public, to avoid the possibility of clashing with other plugins’ files with the same names.

Registering CSS files

To register a CSS file with the asset system, use the FilamentAsset::register() method in the boot() method of a service provider. You must pass in an array of Css objects, which each represents a CSS file that should be registered in the asset system. Each Css object has a unique ID and a path to the CSS file:

use Filament\Support\Assets\Css;
use Filament\Support\Facades\FilamentAsset;

FilamentAsset::register([
    Css::make('custom-stylesheet', __DIR__ . '/../../resources/css/custom.css'),
]);

In this example, we use __DIR__ to generate a relative path to the asset from the current file. For instance, if you were adding this code to /app/Providers/AppServiceProvider.php, then the CSS file should exist in /resources/css/custom.css. Now, when the php artisan filament:assets command is run, this CSS file is copied into the /public directory. In addition, it is now loaded into all Blade views that use Filament. If you’re interested in only loading the CSS when it is required by an element on the page, check out the Lazy loading CSS section.

Using Tailwind CSS in plugins

Typically, registering CSS files is used to register custom stylesheets for your application. If you want to process these files using Tailwind CSS, you need to consider the implications of that, especially if you are a plugin developer. Tailwind builds are unique to every application - they contain a minimal set of utility classes, only the ones that you are actually using in your application. This means that if you are a plugin developer, you probably should not be building your Tailwind CSS files into your plugin. Instead, you should provide the raw CSS files and instruct the user that they should build the Tailwind CSS file themselves. To do this, they need to add your vendor directory to their custom theme’s CSS file using the @source directive. In their custom theme CSS file (e.g., resources/css/filament/admin/theme.css), they should add:

@import "tailwindcss";

@source '../../../../app/Filament/**/*';
@source '../../../../resources/views/filament/**/*';
@source '../../../../vendor/danharrin/filament-blog/resources/views/**/*'; /* Your plugin's vendor directory */

This means that when they build their Tailwind CSS file, it will include all the utility classes that are used in your plugin’s views, as well as the utility classes that are used in their application and the Filament core. If your plugin must also work with Filament’s default stylesheet, register a compiled stylesheet containing the styles it needs. The default stylesheet does not include every Tailwind utility used by third-party plugins, and users without a custom theme are not compiling those utilities themselves.

Lazy loading CSS

Registered CSS files load on every Filament page by default. To load a file only where it is needed, register it with loadedOnRequest() and use the bundled x-load-css directive on the element that requires it:

<div
    x-data="{}"
    x-load-css="[@js(\Filament\Support\Facades\FilamentAsset::getStyleHref('custom-stylesheet'))]"
>
    <!-- ... -->
</div>

To prevent the CSS file from being loaded automatically, you can use the loadedOnRequest() method:

use Filament\Support\Assets\Css;
use Filament\Support\Facades\FilamentAsset;

FilamentAsset::register([
    Css::make('custom-stylesheet', __DIR__ . '/../../resources/css/custom.css')->loadedOnRequest(),
]);

If your CSS file was registered to a plugin, you must pass that in as the second argument to the FilamentAsset::getStyleHref() method:

<div
    x-data="{}"
    x-load-css="[@js(\Filament\Support\Facades\FilamentAsset::getStyleHref('custom-stylesheet', package: 'danharrin/filament-blog'))]"
>
    <!-- ... -->
</div>

Registering CSS files from a URL

If you want to register a CSS file from a URL, you may do so. These assets will be loaded on every page as normal, but not copied into the /public directory when the php artisan filament:assets command is run. This is useful for registering external stylesheets from a CDN, or stylesheets that you are already compiling directly into the /public directory:

use Filament\Support\Assets\Css;
use Filament\Support\Facades\FilamentAsset;

FilamentAsset::register([
    Css::make('example-external-stylesheet', 'https://example.com/external.css'),
    Css::make('example-local-stylesheet', asset('css/local.css')),
]);

Registering CSS variables

Sometimes, you may wish to use dynamic data from the backend in CSS files. To do this, you can use the FilamentAsset::registerCssVariables() method in the boot() method of a service provider:

use Filament\Support\Facades\FilamentAsset;

FilamentAsset::registerCssVariables([
    'background-image' => asset('images/background.jpg'),
]);

Now, you can access these variables from any CSS file:

background-image: var(--background-image);

Registering JavaScript files

To register a JavaScript file with the asset system, use the FilamentAsset::register() method in the boot() method of a service provider. You must pass in an array of Js objects, which each represents a JavaScript file that should be registered in the asset system. Each Js object has a unique ID and a path to the JavaScript file:

use Filament\Support\Assets\Js;

FilamentAsset::register([
    Js::make('custom-script', __DIR__ . '/../../resources/js/custom.js'),
]);

In this example, we use __DIR__ to generate a relative path to the asset from the current file. For instance, if you were adding this code to /app/Providers/AppServiceProvider.php, then the JavaScript file should exist in /resources/js/custom.js. Now, when the php artisan filament:assets command is run, this JavaScript file is copied into the /public directory. In addition, it is now loaded into all Blade views that use Filament. If you’re interested in only loading the JavaScript when it is required by an element on the page, check out the Lazy loading JavaScript section.

Lazy loading JavaScript

Registered JavaScript files load on every Filament page by default. To load a file only where it is needed, register it with loadedOnRequest() and use the bundled x-load-js directive on the element that requires it:

<div
    x-data="{}"
    x-load-js="[@js(\Filament\Support\Facades\FilamentAsset::getScriptSrc('custom-script'))]"
>
    <!-- ... -->
</div>

To prevent the JavaScript file from being loaded automatically, you can use the loadedOnRequest() method:

use Filament\Support\Assets\Js;
use Filament\Support\Facades\FilamentAsset;

FilamentAsset::register([
    Js::make('custom-script', __DIR__ . '/../../resources/js/custom.js')->loadedOnRequest(),
]);

If your JavaScript file was registered to a plugin, you must pass that in as the second argument to the FilamentAsset::getScriptSrc() method:

<div
    x-data="{}"
    x-load-js="[@js(\Filament\Support\Facades\FilamentAsset::getScriptSrc('custom-script', package: 'danharrin/filament-blog'))]"
>
    <!-- ... -->
</div>

Asynchronous Alpine.js components

Sometimes, you may want to load external JavaScript libraries for your Alpine.js-based components. The best way to do this is by storing the compiled JavaScript and Alpine component in a separate file, and letting us load it whenever the component is rendered. Firstly, you should install esbuild via NPM, which we will use to create a single JavaScript file containing your external library and Alpine component:

npm install esbuild --save-dev

Then, you must create a script to compile your JavaScript and Alpine component. You can put this anywhere, for example bin/build.js:

import * as esbuild from 'esbuild'

const isDev = process.argv.includes('--dev')

async function compile(options) {
    const context = await esbuild.context(options)

    if (isDev) {
        await context.watch()
    } else {
        await context.rebuild()
        await context.dispose()
    }
}

const defaultOptions = {
    define: {
        'process.env.NODE_ENV': isDev ? `'development'` : `'production'`,
    },
    bundle: true,
    mainFields: ['module', 'main'],
    platform: 'neutral',
    sourcemap: isDev ? 'inline' : false,
    sourcesContent: isDev,
    treeShaking: true,
    target: ['es2020'],
    minify: !isDev,
    plugins: [{
        name: 'watchPlugin',
        setup(build) {
            build.onStart(() => {
                console.log(`Build started at ${new Date(Date.now()).toLocaleTimeString()}: ${build.initialOptions.outfile}`)
            })

            build.onEnd((result) => {
                if (result.errors.length > 0) {
                    console.log(`Build failed at ${new Date(Date.now()).toLocaleTimeString()}: ${build.initialOptions.outfile}`, result.errors)
                } else {
                    console.log(`Build finished at ${new Date(Date.now()).toLocaleTimeString()}: ${build.initialOptions.outfile}`)
                }
            })
        }
    }],
}

compile({
    ...defaultOptions,
    entryPoints: ['./resources/js/components/test-component.js'],
    outfile: './resources/js/dist/components/test-component.js',
})

As you can see at the bottom of the script, we are compiling a file called resources/js/components/test-component.js into resources/js/dist/components/test-component.js. You can change these paths to suit your needs. You can compile as many components as you want. Now, create a new file called resources/js/components/test-component.js:

// Import any external JavaScript libraries from NPM here.

export default function testComponent({
    state,
}) {
    return {
        state,

        // You can define any other Alpine.js properties here.

        init() {
            // Initialise the Alpine component here, if you need to.
        },

        // You can define any other Alpine.js functions here.
    }
}

Now, you can compile this file into resources/js/dist/components/test-component.js by running the following command:

node bin/build.js

If you want to watch for changes to this file instead of compiling once, try the following command:

node bin/build.js --dev

Now, you need to tell Filament to publish this compiled JavaScript file into the /public directory of the Laravel application, so it is accessible to the browser. To do this, you can use the FilamentAsset::register() method in the boot() method of a service provider, passing in an AlpineComponent object:

use Filament\Support\Assets\AlpineComponent;
use Filament\Support\Facades\FilamentAsset;

FilamentAsset::register([
    AlpineComponent::make('test-component', __DIR__ . '/../../resources/js/dist/components/test-component.js'),
]);

When you run php artisan filament:assets, the compiled file will be copied into the /public directory. Finally, you can load this asynchronous Alpine component in your view using x-load attributes and the FilamentAsset::getAlpineComponentSrc() method:

<div
    x-load
    x-load-src="{{ \Filament\Support\Facades\FilamentAsset::getAlpineComponentSrc('test-component') }}"
    x-data="testComponent({
        state: $wire.{{ $applyStateBindingModifiers("\$entangle('{$statePath}')") }},
    })"
>
    <input x-model="state" />
</div>

This example is for a custom form field. It passes the state in as a parameter to the testComponent() function, which is entangled with a Livewire component property. You can pass in any parameters you want, and access them in the testComponent() function. If you’re not using a custom form field, you can ignore the state parameter in this example. The x-load attributes come from the Async Alpine package, and any features of that package can be used here.

Registering script data

Sometimes, you may wish to make data from the backend available to JavaScript files. To do this, you can use the FilamentAsset::registerScriptData() method in the boot() method of a service provider:

use Filament\Support\Facades\FilamentAsset;

FilamentAsset::registerScriptData([
    'user' => [
        'name' => auth()->user()?->name,
    ],
]);

Now, you can access that data from any JavaScript file at runtime, using the window.filamentData object:

window.filamentData.user.name // 'Dan Harrin'

Registering JavaScript files from a URL

If you want to register a JavaScript file from a URL, you may do so. These assets will be loaded on every page as normal, but not copied into the /public directory when the php artisan filament:assets command is run. This is useful for registering external scripts from a CDN, or scripts that you are already compiling directly into the /public directory:

use Filament\Support\Facades\FilamentAsset;
use Filament\Support\Assets\Js;

FilamentAsset::register([
    Js::make('example-external-script', 'https://example.com/external.js'),
    Js::make('example-local-script', asset('js/local.js')),
]);

Using Vite-compiled JavaScript files

The php artisan filament:assets command copies files as-is into the /public directory without bundling or resolving dependencies. This means that if your JavaScript file uses import statements to pull in npm packages, the browser will not be able to resolve them. To use JavaScript files that require bundling, you should compile them with Vite first, and then register the compiled output as a URL-based asset. First, add your JavaScript file as an entry point in your vite.config.js:

import { defineConfig } from 'vite'

import laravel from 'laravel-vite-plugin'


<Warning>
You are currently viewing the documentation for Filament 4.x, which is a previous version of Filament.

Looking for the current stable version? Visit the [5.x documentation](/5.x/advanced/assets).
</Warning>

export default defineConfig({
    plugins: [
        laravel({
            input: [
                'resources/css/app.css',
                'resources/js/app.js',
                'resources/js/timezone.js', // Your custom script
            ],
        }),
    ],
})

Then, compile the assets using Vite:

npm run build

Finally, register the compiled asset using Vite::asset() to resolve the versioned URL:

use Filament\Support\Assets\Js;
use Filament\Support\Facades\FilamentAsset;
use Illuminate\Support\Facades\Vite;

FilamentAsset::register([
    Js::make('timezone', Vite::asset('resources/js/timezone.js')),
]);

This approach also works for TypeScript files or any other JavaScript that needs a build step. Since Vite::asset() returns a URL, the asset will not be copied by php artisan filament:assets — it is served directly from Vite’s build output.

If you need to bundle JavaScript for an asynchronous Alpine.js component, consider using esbuild instead, as documented in that section.

Ignoring published assets in version control

The files that the php artisan filament:assets command copies into the /public directory for Filament’s own packages are generated, so there is no need to commit them to version control. When you run php artisan filament:install, Filament adds the following rules to your app’s .gitignore file, if they are not already there:

/public/css/filament
/public/fonts/filament
/public/js/filament

If you have customized the assets_path in the config/filament.php file, the rules use that path instead, for example /public/filament/css/filament. Assets registered by your app or third-party plugins may be published outside these filament directories. You should add their generated paths to .gitignore separately if needed. The /public/css/filament rule also ignores any custom themes that you compile directly into that directory instead of through Vite. You should compile those themes as part of your deployment process, since the filament:assets command does not build them. Since Filament’s published package assets are not committed, you should run php artisan filament:assets when you deploy your app. The php artisan filament:install command adds @php artisan filament:upgrade to the post-autoload-dump scripts in your app’s composer.json file, which runs the filament:assets command for you each time Composer dumps the autoloader.

Introduction

Guides

Resources

Tables

Schemas

Forms

Infolists

Actions

Notifications

Widgets

Configuration

Navigation

Users

Styling

Advanced

Testing

Plugins

Components

Deployment

Upgrading

Registering assets

Introduction

The `FilamentAsset` facade

Registering assets for a plugin

Registering CSS files

Using Tailwind CSS in plugins

Lazy loading CSS

Registering CSS files from a URL

Registering CSS variables

Registering JavaScript files

Lazy loading JavaScript

Asynchronous Alpine.js components

Registering script data

Registering JavaScript files from a URL

Using Vite-compiled JavaScript files

Ignoring published assets in version control

​Introduction

​The FilamentAsset facade

​Registering assets for a plugin

​Registering CSS files

​Using Tailwind CSS in plugins

​Lazy loading CSS

​Registering CSS files from a URL

​Registering CSS variables

​Registering JavaScript files

​Lazy loading JavaScript

​Asynchronous Alpine.js components

​Registering script data

​Registering JavaScript files from a URL

​Using Vite-compiled JavaScript files

​Ignoring published assets in version control

Introduction

The `FilamentAsset` facade

Registering assets for a plugin

Registering CSS files

Using Tailwind CSS in plugins

Lazy loading CSS

Registering CSS files from a URL

Registering CSS variables

Registering JavaScript files

Lazy loading JavaScript

Asynchronous Alpine.js components

Registering script data

Registering JavaScript files from a URL

Using Vite-compiled JavaScript files

Ignoring published assets in version control