Laravel Ui Adminlte Laravel Package

Getting Started

v5.2.0 is an additive release (Laravel 10 support) bundled with a build-tooling migration (Webpack → Vite). Nothing in the public PHP API is signalled as removed, so the practical starting point is confirming your app runs on Laravel 10 / PHP 8.1+ and that your asset pipeline has moved off Mix.

Minimal steps:

1. composer require <vendor>/<package>:^5.2 (or composer update <vendor>/<package>). Check composer why-not laravel/framework 10 first if you are mid-upgrade — the package is no longer the blocker, but your other dependencies may be.
2. Publish config and assets: php artisan vendor:publish --provider="<Vendor>\<Package>\<PackageServiceProvider>". Read config/<package>.php first; it is the fastest way to see which paths, disks, and asset locations the package assumes.
3. Build frontend assets with the new toolchain: npm install && npm run build (Vite), not npm run production (Mix). Confirm a manifest.json appears in the package's build directory.
4. Clear caches: php artisan optimize:clear.
5. First use case: render the package's Blade component/directive on a single page and verify the hashed assets resolve. If the page loads but styling/JS is missing, you are almost certainly looking at a manifest path problem, not a package bug.

Where to look first, in order: the service provider (boot()/publishes() tells you exactly which files land in your app and under which tags), config/<package>.php, then the shipped vite.config.js.

Implementation Patterns

Upgrade order matters. Treat the two changes as separate workstreams: do the Laravel 10 bump, get the app green, then swap the asset pipeline. Doing both at once makes failures ambiguous.

• Laravel 10 step: update composer.json constraints, run the full test suite, and check for framework-level deprecations (PHP 8.1 minimum, native return types, removal of legacy date casting). If your app is on Laravel 9 and staying there, this release should still install — verify the illuminate/* constraint allows it.
• Vite step: remove webpack.mix.js, package-lock.json (regenerate), and any stale mix-manifest.json or public/vendor/<package> build output before the first Vite build. Mixed artifacts are the top source of confusing 404s.

Asset resolution in a package context. Published package assets normally live under public/vendor/<package>, not the app root, so the Vite base/build directory must be set accordingly (e.g. Vite::useBuildDirectory() / a base in the published vite.config.js). If you maintain your own layout, confirm the generated manifest keys match the paths the Blade views request — Vite hashes filenames, so any hardcoded vendor/<package>/app.js reference will break.

Deployment pipeline. Build at deploy time, not on the developer machine: npm ci && npm run build as a release step, with the manifest included in the artifact. Do not commit node_modules. Pin Node (.nvmrc, or an engines field) — Vite requires modern Node and will fail loudly on old CI images.

Local development. npm run dev starts the Vite dev server and writes a public/hot file; @vite then points at localhost:5173 with HMR. This is a behavioural change from Mix's npm run watch and is worth documenting in your team README, because it means the dev server must actually be running for styles to appear.

Testing. Manifests rarely exist in CI test jobs that skip the asset build. Call $this->withoutVite() in setUp() (or the base TestCase) to stub asset tags, and only assert on asset markup in dedicated tests.

Republishing after upgrade. Publish to a scratch location and diff against your current overrides rather than using --force blindly:

php artisan vendor:publish --provider="..." --tag=config --force
git diff config/<package>.php

Keep any local customisations in a separate config layer or a thin wrapper so future releases are cheap to absorb.

Gotchas and Tips

• Vite manifest not found at: .../manifest.json — the build step is missing, the build directory is wrong, or the manifest landed outside public/. Check the path in the error against the actual output directory.
• Stale public/hot — if a hot file is committed or left behind by a local dev run, production will emit http://localhost:5173/... URLs. Delete it in your deploy script; it is the single most common Vite-in-production incident.
• Leftover Mix artifacts served instead of Vite output — an old mix-manifest.json or an un-purged public/vendor/<package> directory can be picked up by cached views. Run php artisan view:clear and confirm the old hashed bundles are gone.
• Republishing overwrites customisations. Config and view tags overwrite without warning on --force. Always diff; never force-publish in a deploy script.
• Dev server from Docker/Sail/WSL — HMR fails unless you configure server.hmr.host and expose port 5173. Symptoms are a page that loads but never hot-reloads, or a browser console full of failed WebSocket connections.
• composer update blocked on Laravel 10 — the package is fine; the conflict is elsewhere. composer why-not laravel/framework "^10.0" names the culprit in one command.
• Cache clearing after upgrade — config:clear, view:clear, and route:clear (or optimize:clear) before you debug anything. A cached config from the previous major version can make a correct install look broken.
• Rollback plan — pin ^5.1 if the Vite migration bites during a release window. The Laravel 10 support is the part you probably want; the toolchain swap can wait a sprint.
• Extension points — the service provider and published config are the intended customisation surface. If you find yourself patching published views or hand-editing the built manifest, you are outside the supported path and will pay for it on every release.