Upgrading
Two steps: update the package, then re-run the installer, which recognises an existing install and only adds what is new.
composer update shipbytes/laravel-ui-kit
php artisan ui-kit:install
Read the changelog first. Before 1.0 a minor version can contain breaking changes, and the entry says what to do.
Update mode
The preflight check reads routes/auth.php. When the file carries the kit's ui-kit:managed header, the run is treated as an update rather than a collision: the installer prints Existing UI Kit install detected — updating in place, skips the Breeze and Jetstream warnings, and stays non-interactive. Existing files are kept. New files, new config keys, new routes between the markers and new migrations are added.
Pass --force to overwrite published files with the package's current stubs. Do that on a clean working tree, then review the diff and restore your edits.
The managed header
// ui-kit:managed — auto-loaded by UiKitServiceProvider. Delete this line to
// opt out of auto-loading and wire this file up yourself.
The service provider loads routes/auth.php, routes/admin.php and routes/ui-kit-user.php only when they carry this header. It is how the kit avoids double-registering a route file you wrote yourself, and how ui-kit:doctor knows which files it owns. Delete the line to take over a file; from then on you load it from bootstrap/app.php or your own provider, and the installer leaves it alone.
The markers
| File | Markers | Who writes between them |
|---|---|---|
config/admin.php | /* ui-kit:nav-start */ … /* ui-kit:nav-end */ | Modules add navigation entries |
routes/admin.php | /* ui-kit:admin-routes-start */ … /* ui-kit:admin-routes-end */ | Modules add admin routes |
routes/ui-kit-user.php | /* ui-kit:user-routes-start */ … /* ui-kit:user-routes-end */ | Modules add user routes such as /profile |
config/ui-kit.php | /* ui-kit:modules-start */ … /* ui-kit:modules-end */ | The installer records installed modules |
Patching is idempotent and keyed by route name or nav route, so re-running an install never duplicates an entry and never removes another module's. Keep the markers even when you reorder the lines around them; without them the installer warns and skips the patch.
Picking up changed stubs
A release note that says a published file changed means your copy did not. To see what changed, publish the tag into a scratch branch and diff:
git switch -c kit-upgrade
php artisan vendor:publish --tag=ui-kit-views --force
git diff
Keep the hunks you want, drop the rest, and run php artisan ui-kit:doctor before merging. Migrations are never re-published once they exist in database/migrations.
Versioning
Published versions are immutable; every publishable state gets a fresh tag. Before 1.0, breaking changes bump the minor version and are called out at the top of the entry.