Minios Laravel Package

Getting Started

MiniOS v0.1.0 is a first release, so treat everything below as a starting point to verify against the package's own README rather than settled convention.

1. Install and publish.

   composer require <vendor>/mini-os:0.1.0
   php artisan vendor:publish --provider="MiniOS\ServiceProvider"
   

   Pin the exact version — 0.1.x is pre-1.0 and the public surface is effectively unstable.

2. Look here first, in order:

   • config/minios.php — the package's real API is usually its config: registered "apps", window defaults, layout options, asset driver.
   • routes/minios.php (or routes registered by the provider) — find the URI prefix and middleware stack before you write any of your own routes.
   • resources/views/vendor/minios/ after publishing — the shell layout is the thing you will most often need to override.
   • README + CHANGELOG — at v0.1.0 the changelog is the only reliable signal of what changed between patches.

3. First use case: an authenticated internal desktop at /desktop. Wrap the MiniOS route group in your existing auth/verified middleware and mount it behind a feature flag so it can't leak to production users before you've reviewed it. The lowest-risk first win is a single read-only "app" (e.g. a report viewer or queue monitor) rendered inside a window, rather than migrating an existing admin panel wholesale.

Implementation Patterns

Mount behind your own middleware, not the package's. Define the route group yourself and point it at the MiniOS controller, so auth, tenancy scoping, and rate limits stay under your control:

Route::middleware(['auth', 'verified', 'can:access-desktop'])
    ->prefix('desktop')
    ->group(function () {
        Route::get('/', DesktopController::class)->name('desktop');
    });

Register functionality as discrete apps. The desktop metaphor encourages one class/component per "application" declared in config. Keep each app's routes, views, and authorization in its own namespace so you can enable or disable it per environment or per tenant without touching the shell.

Compose, don't fork. Override the shell layout via resources/views/vendor/minios/, and keep the package's own views untouched. Prefer Blade component slots and named view namespaces over copying files, so a composer update doesn't leave you with a silently diverging UI.

Persist window/desktop state deliberately. If the package stores window positions or open apps, decide early whether that's session-scoped, per-user (DB column), or ephemeral. Retrofitting persistence after users have built habits is painful.

Authorize at the app boundary. Do not assume the desktop shell's own gating covers what individual apps expose. Each app should re-check a Gate or Policy — assume the shell is presentation, not a security boundary.

Test the integration seam, not the shell. Feature-test that unauthenticated users are redirected, that authorized users see the expected app list, and that each app's data endpoints enforce policy. Snapshot-testing the desktop chrome itself is low value at 0.1.0.

Build assets through your own pipeline. If the package ships prebuilt CSS/JS, load it from public/vendor/minios and layer your overrides via Vite. Don't edit compiled package assets.

Gotchas and Tips

• Pre-1.0 churn is the headline risk. Pin 0.1.0 exactly, read the changelog on every bump, and re-publish to a temp directory to diff config before overwriting. Config keys are the most likely thing to move in a 0.1.x patch.
• vendor:publish --force will eat your overrides. Publish once, then diff rather than force. Keep customisations in your app's views and reference them from config.
• Asset conflicts. Two asset pipelines (package-published files plus your Vite build) is the most common cause of "styles work locally, not in production." Confirm php artisan storage:link, run npm run build in CI, and check the published-asset path is gitignored-but-deployed.
• Route collisions. A catch-all desktop route can shadow your app routes. Register app routes before the shell route, or namespace the shell under a distinct prefix.
• Silent authorization gaps. If app visibility is driven by config rather than Gates, a misconfigured enabled => true in production is an exposure, not a UI bug. Default to deny and gate the config list per environment.
• Livewire/Inertia version skew. If the desktop is reactive, a Livewire major mismatch with your app will fail in ways that look like MiniOS bugs. Check composer why before filing anything.
• Debugging checklist: route list (php artisan route:list --path=desktop) → middleware actually applied → config cache cleared (config:clear, view:clear) → published view presence → browser console for 404s on vendor assets.
• Extension points to prefer: the config app registry, view namespaces, and any package events. Avoid subclassing internal shell classes; those are the least stable part of a 0.1.0 release.
• Budget for replacement. At 0.1.0 with no migration guide, keep the shell thin enough that reverting to a plain Blade admin layout is a day's work, not a rewrite.