README

This package aims to solve improve the static asset handling of the amazing Laravel package Filament.

NOTE: This package is for Filament served assets only. If you are looking for a general Laravel asset management system that includes the same features as this, plus advanced dependency management, then the newly released Laravel Static Libraries might be of interest.

By default Filament serves all static files (js and css) via Laravel. While this method is perfectly fine for smaller projects, it can become a performance hit once your project grows. To overcome the performance hit, this package will copy all your static assets to a path in your public directory, thereby allowing your webserver to directly handle the files. If you add a package with new files and forget run the command, no sweat, things will fallback directly to Filament's default handling.

Another feature of the caching mechanism is the addition of cache buster keys added to the actual URLs. These keys are based off of the filemtime of the original asset file, so even if you republish, browser caching will remain untouched.

To cache your static files, just run this simple command:

 php artisan filament:cache-assets

And to clear the files out, going back to the original method of handling files:

 php artisan filament:flush-assets

One problem with this method is that you may easily forget to run the commands when packages are updated. Therefor it is highly recommended to add a script to your composer.json file to handle this automatically:

    "scripts": {
        "post-autoload-dump": [
            "Illuminate\\Foundation\\ComposerScripts::postAutoloadDump",
            "@php artisan package:discover --ansi"
        ],
        "post-update-cmd": [
            "@php artisan vendor:publish --tag=laravel-assets --ansi --force",
            "@php artisan filament:upgrade",
            "@php artisan filament:cache-assets" // Add this line
        ],

        "post-root-package-install": [
            "@php -r \"file_exists('.env') || copy('.env.example', '.env');\""
        ],
        "post-create-project-cmd": [
            "@php artisan key:generate --ansi"
        ]
    },

The second problem this package deals with is the loading of assets on every page. As projects grow and more static assets are added, this can be another performance hit. If you use a package like the Filament Tiptap Editor or Filament Tiny Editor, then those files load on every page, regardless of you needing them or not. To stop this, there are two events fired when rendering out scripts and stylesheets:

HollyIT\FilamentStaticAssets\Events\PreProcessStaticAssetsEvent

This event is fired before the files are processed and things like cache busting keys are added.

HollyIT\FilamentStaticAssets\Events\PostProcessStaticAssetsEvent

This event fires after all alterations are done to the files and ready to be rendered in the template.

Both methods expose the same properties:

$event->files is a collection of the actual files. So in the PreProcess event, you could remove a script file: $event->files->forget('file_to_drop');

$event->domain is the scope of the files. This can be either styles, scripts or beforeCoreScripts

Install

composer require hollyit/filament-static-assets

One Note!

To make all this possible, this package has to override the FilamentManager class provided by Filament. So If you are trying to do anything extra with that concrete class, keep in mind you'll have to echo the changes made by this class.

Testing

This package is fully tested with 100% coverage.

License

The MIT License (MIT). Please see License File for more information.

hollyit / filament-static-assets

Maintainers

Details