Statamic Sourcestack Laravel Package

Getting Started

This is a small, focused Blade/asset-registration package: it lets any view, component, or partial register frontend files (JS/CSS) locally, then renders them all in one place in your layout — the alternative to hand-rolling @once + @push + @stack + @vite in every component.

Minimal path:

1. composer require the package (Laravel package discovery handles the service provider; there is nothing to register manually unless the readme says otherwise).
2. Read the readme section added in v1.0.1 that explains why you'd use this instead of @once + @stack — that comparison is the fastest way to decide whether the package fits your layout at all. If you already have a working @push/@stack pipeline and don't mind the duplication, you may not need it.
3. Skim the "multiple files at once" section (also new in v1.0.1) — that's the feature you'll use on day one.
4. Put the render directive in your layout once: CSS entries before </head>, JS entries before </body>.
5. Register your first asset from inside a Blade component and confirm it lands in the rendered output.

First real use case: a Blade component that ships its own JS/CSS (resources/js/charts.js, resources/css/charts.css) and registers those files next to its markup, so the layout doesn't need to know which components exist on the page.

Implementation Patterns

Component-local registration. The core pattern is: markup and its assets live together. A <x-chart> component registers charts.js in its own template; the layout renders the aggregate. This keeps the layout free of conditional @vite([...]) arrays that grow with every new widget.

Single render point. Treat the render directive like @stack('scripts'): exactly one call per layout. If you have multiple layouts (app, auth, mail-preview), each needs its own call, and you should not nest them.

Multiple files at once. v1.0.1 lets you pass several sources in a single call, separated by | (deliberately aligned with the vite tag syntax so the two read the same way) or by comma. Because filenames are now whitespace-trimmed, 'resources/js/a.js | resources/js/b.js' is safe — you can format long asset lists across lines for readability.

Group related registrations. Rather than one call per file, register a feature's bundle in one call. It reduces duplication and makes ordering obvious in the source.

Livewire / Inertia interplay. Register from the server-rendered component, not from a JS hook. On Livewire navigations the layout is not re-rendered, so anything registered during a subsequent component render will not appear — register assets for navigated pages in the initial full page load, or guard with a persistent layout.

Conditional assets. Registering inside an @if block works naturally and is the main reason to prefer this over a static array in the layout. Keep the condition next to the markup that needs it, not in the layout.

Encapsulating third-party widgets. Wrap a JS library + its CSS in a single anonymous component that registers both and renders the mount point. Consumers then get dependency and styling in one tag.

Gotchas and Tips

• Whitespace in filenames was broken before v1.0.1. If you split asset lists on | or , yourself and didn't trim, or if you're on v1.0.0, filenames with leading/trailing spaces silently failed to resolve. Upgrade: it's a patch release with no API change.
• Two delimiters now exist. | and , both work. Pick one per codebase and stick to it — mixed delimiters in one call is the kind of thing that looks fine until someone adds a filename containing a comma.
• Duplicate registrations are your problem. If a component renders twice (loops, repeated partials), you may get the same file twice. Either render the aggregate through a dedupe step or make components idempotent. This is the one place where @once + @stack was doing real work for you.
• Ordering is registration order, not dependency order. If b.js depends on a.js being loaded first, register them in the same call in the right sequence rather than relying on component render order, which can shift with layout changes.
• This is not a replacement for @once + @stack in general. Inline <script> blocks, JSON payloads, and non-file content still belong in a normal stack. The package handles file URLs; keep raw markup in @push.
• Dev server vs. build. The output ultimately goes through Vite, so a missing HMR entry or a stale manifest will look like a package bug. If an asset 404s, check public/build/manifest.json and that npm run dev is running before debugging the directive.
• Clear compiled views after upgrading. php artisan view:clear — directive changes are compiled into cached Blade views and stale caches are the usual cause of "the fix didn't apply."
• Quoting in attributes. With pipe-separated strings inside a Blade directive, prefer single quotes around the argument so you don't fight escaping when the value comes from a variable.
• Extension points: if the package exposes config (delimiters, output ordering, tag attributes), publish it rather than editing vendor files — the two-delimiter behaviour in v1.0.1 suggests parsing rules are still evolving.