L5 Repository Laravel Package

Getting Started

Start by installing the release and letting the package place its front-end asset where Laravel can serve it:

composer require <vendor>/<package>:^3.0.1
php artisan vendor:publish --tag=<package>-assets --force

3.0.1 is a patch that copies the package's JavaScript file into the public path rather than relying on the consumer to move it by hand. That means the first thing to verify after upgrading is that the file actually landed where your views expect it:

ls -l public/js/<package>.js

Then look at, in order:

1. config/<package>.php — any asset_path, script_url, or public_path key controls where the JS is expected to live and what URL is emitted.
2. The package's service provider — check publishes() for the asset tag and whether it registers a vendor:publish group or performs the copy at boot.
3. Your layout Blade file — confirm the script tag is present and points at the published path.

First use case: an existing Blade layout that renders the package widget or mounts it on a DOM node. Drop the script in once, confirm no 404 in the network tab, and you have the baseline working.

{{-- resources/views/layouts/app.blade.php --}}
@stack('scripts')
<script src="{{ asset('js/<package>.js') }}" defer></script>

Implementation Patterns

Publish-then-commit vs publish-on-deploy. Because 3.0.1 automates the copy, teams split into two camps. If you commit public/js/<package>.js, the asset is versioned and deployments are deterministic but you must re-run the publish command on every upgrade and remember to commit the diff. If you publish during deploy, add the step to your release script before php artisan config:cache:

php artisan vendor:publish --tag=<package>-assets --force
php artisan optimize

Never rely on the copy happening implicitly at request time in production — check whether the service provider only publishes on vendor:publish or also on boot, and treat the latter as a fallback, not the mechanism.

Config-driven path. If the config exposes the script location, read from it instead of hardcoding:

<script src="{{ asset(config('<package>.asset_path', 'js/<package>.js')) }}"></script>

This keeps the Blade template correct when the package changes its default directory or when you serve assets from a CDN.

Deferred initialisation. Most packages of this shape expose a global or an init function. Wrap mounting in DOMContentLoaded or use defer, and guard against double initialisation on Livewire/Turbo navigations:

document.addEventListener('DOMContentLoaded', () => {
    if (window.<Package>) window.<Package>.init();
});

document.addEventListener('livewire:navigated', () => {
    window.<Package>?.init();
});

Cache busting. A copied static file is invisible to Vite's manifest. Either append a version query string derived from the package version, or hash the file:

<script src="{{ asset('js/<package>.js') }}?v={{ config('<package>.version', '3.0.1') }}"></script>

Multiple environments. If you use a CDN or object storage for public, the copy step must run before your asset sync. Put the publish command in the same job/step that uploads public/, not in a separate one.

Gotchas and Tips

• Upgrades need --force. vendor:publish skips existing files by default. 3.0.1 changed what is copied, so an existing public/js/<package>.js from 3.0.0 will silently stay stale. Always pass --force for this tag and diff the result.
• 404 after deploy is the classic symptom. If the widget renders but does nothing, open the network tab first. A missing public/js/<package>.js is almost always either an unpublished asset or a deploy step ordering problem.
• .gitignore traps. Many Laravel skeletons ignore public/js or ignore all of public/ except index.php. If you commit the asset, verify with git check-ignore -v public/js/<package>.js before wondering why production is broken.
• Permissions and path. Web server users need read access to the published file, and the target directory must exist. If the copy fails silently, check storage/logs/laravel.log and run the publish command manually to surface the error.
• Don't edit the published file. Treat it as build output — changes are lost on the next --force. Use the package's config or a wrapper script for customisation. If there is no extension point, that is worth raising upstream.
• Ordering with Vite/Mix. If your layout loads @vite, make sure the package script is not bundled and also loaded from public/, which duplicates globals and breaks init. Pick one path.
• CSP. A newly copied file is still subject to your script-src. If you use a nonce- or hash-based Content-Security-Policy, add the new path or update the hash; otherwise the script is blocked with no visible error beyond the console warning.
• Extension point to look for. If the service provider tags the copy, you can override the destination by publishing and then rebinding the config key. If the path is hardcoded in 3.0.1, that is a design limitation to watch in the next minor.
• Debugging checklist: file exists in public → URL resolves via php artisan route:list/direct request → script tag present in rendered HTML → no console errors → init function present on window. Work down that list before touching package internals.