Skip to content
manifest / 1

Registering assets

Last updated:

On this page

A package registers its assets in its service provider. Use the RegistersAssets trait and give it the package's name and its resources folder:

<?php

namespace Javaabu\Filters;

use Illuminate\Support\ServiceProvider;
use Javaabu\Manifest\Concerns\RegistersAssets;
use Javaabu\Manifest\Package;

class FiltersServiceProvider extends ServiceProvider
{
    use RegistersAssets;

    public function boot(): void
    {
        $this->registerAssets('filters', __DIR__ . '/../resources', function (Package $package) {
            $package
                ->style('filters', 'css/filters.css')
                ->script('filter-bar', 'js/filter-bar.ts', depends_on: ['filters', 'forms::select'])
                ->react('date-range', 'js/date-range.tsx', depends_on: ['filter-bar'])
                ->js()
                ->pages()
                ->npm(['@javaabu/onu' => '^1.0'], peer_dependencies: ['react' => '^19.0']);
        });
    }
}

registerAssets() works from register() or boot(), in whatever order the providers load. The callback runs when the manifest is first used. Add javaabu/manifest to the package's require in composer.json.

Without the trait, use the facade from boot():

use Javaabu\Manifest\Facades\Manifest;

Manifest::package('filters', __DIR__ . '/../resources')
    ->style('filters', 'css/filters.css');

Calling Manifest::package('filters') again, without the path, returns the same package, so you can add more assets later, such as optional ones behind a feature check.

Names

Assets are namespaced by package: filters::filter-bar is the filter-bar asset of the filters package. Package names are lowercase letters, numbers and dashes. Asset names may also contain dots and slashes (forms::inputs/select). Names are unique within a package, so a style and a script can't share one.

Asset types

The type comes from the entry's extension:

Method Extensions Printed as
style($name, $entry) .css, .scss, .sass <link rel="stylesheet"> in <head>
script($name, $entry) .js, .mjs, .ts, .mts, .jsx, .tsx, .vue <script type="module"> before </body>
react($name, $entry) any script extension a script, marked as needing React
vue($name, $entry) any script extension a script, marked as needing Vue

react() and vue() render the same tag as script(). They tell manifest:check that the app needs react, react-dom and @vitejs/plugin-react, or vue and @vitejs/plugin-vue. A Sass style tells it the app needs sass.

Entries are paths relative to the folder you passed to registerAssets(). Registering a script as a style, or the other way round, throws.

A script's own CSS

A script can import its CSS:

// resources/js/select.ts
import "./select.css"
import TomSelect from "tom-select"

document.querySelectorAll<HTMLSelectElement>("[data-select]").forEach((element) => new TomSelect(element))

Vite prints the <link> for an imported stylesheet next to the script. For CSS that must be in <head> before the page paints, register it as its own style and make the script depend on it.

Dependencies

depends_on lists assets that must load first. Bare names are in the same package, and package::name can be in any package:

$package
    ->style('base', 'css/base.css')
    ->script('filter-bar', 'js/filter-bar.ts', depends_on: ['base', 'forms::select']);

Requiring filters::filter-bar loads filters::base, then forms::select (and whatever it depends on), then filters::filter-bar, each once. A dependency on an asset nobody registered, or a cycle, throws a clear error while the page renders.

Dependencies decide the order of tags. A script that imports another package's code (import { select } from '@javaabu/forms-blade') doesn't need a dependency for that: Vite bundles the import. Add one when the order of the tags matters, as with stylesheets or scripts that set up globals.

Several at once

$package
    ->styles([
        'base' => 'css/base.css',
        'print' => 'css/print.css',
    ])
    ->scripts([
        'filter-bar' => 'js/filter-bar.ts',
        'date-range' => ['js/date-range.ts', ['filter-bar']],
    ]);

HTML attributes

Extra attributes for an asset's tag:

$package->script('editor', 'js/editor.ts', attributes: ['data-turbo-track' => 'reload']);

App-wide attributes from Vite::useScriptTagAttributes() and Vite::useStyleTagAttributes() apply too.

JS for apps to import

js() makes the package's JS folder importable in the app's code, as @javaabu/{name}:

$package->js();                          // resources/js as @javaabu/filters
$package->js('ts');                      // resources/ts as @javaabu/filters
$package->js('js', '@acme/filters');     // a different alias
$package->alias('@javaabu/forms-blade'); // only change the alias
import { FilterBar } from "@javaabu/filters"
import { useFilters } from "@javaabu/filters/hooks/use-filters"

Pick another alias when @javaabu/{name} is also an npm package the app might install. The Vite plugin warns when an alias shadows an installed npm package, and the alias wins. For example, javaabu/forms (Blade) shouldn't use @javaabu/forms, which is the React library's npm name.

Inertia pages

pages() registers the folder of the package's Inertia pages (resources/js/Pages by default). resources/js/Pages/Reports/Show.tsx renders as filters::Reports/Show:

$package->pages();
$package->pages('js/Inertia/Pages');

See Inertia pages.

npm dependencies

Package code is built by the app's Vite, so the npm packages it imports must be installed in the app. Declare them:

$package->npm(
    ['tom-select' => '^2.4', '@javaabu/onu' => '^1.0'],
    peer_dependencies: ['react' => '^19.0'],
);

Both kinds must be installed by the app. Peer dependencies are the ones that must have a single copy shared with the app (React, Vue). php artisan manifest:check tells the app developer what's missing. See Building a package.

Declare what only your Inertia pages (and code apps import through your alias) need with for: 'pages', so Blade apps aren't asked for it. See Pages-only dependencies.

Prebuilt assets

dist() points at a folder of prebuilt assets, for apps that don't build with Vite:

$package->dist();            // ../dist, next to resources/
$package->dist('../build');

See Prebuilt assets.

Checking what's registered

php artisan manifest:list
php artisan manifest:list filters   # one package, with its dependencies
php artisan manifest:list --json
+---------------------+-------+-----------------------------------------------+---------------------------------+
| Asset               | Type  | Entry                                         | Depends on                      |
+---------------------+-------+-----------------------------------------------+---------------------------------+
| widgets::theme      | sass  | vendor/acme/widgets/resources/css/theme.scss  |                                 |
| widgets::core       | js    | vendor/acme/widgets/resources/js/core.js      | widgets::theme                  |
| filters::styles     | css   | vendor/acme/filters/resources/css/filters.css | widgets::theme                  |
| filters::filter-bar | ts    | vendor/acme/filters/resources/js/filter-bar.ts| widgets::core, filters::styles  |
+---------------------+-------+-----------------------------------------------+---------------------------------+

Assets are listed in dependency order, and the entry is the file that will be used: an app's override is marked (override).

Documentation
All packages

javaabu/manifest

Source on GitHub