Ui Laravel Package

Getting Started

streams/ui is the control-panel theme and component layer for the Streams platform — not a standalone Laravel UI kit. Before you touch it, confirm the host application already boots streams/core (laravel-streams/core). If you are not building on Streams, stop here and compare against Filament, Nova, or a Blade UI kit; adopting this package in a conventional Laravel app layers a second architecture beside standard MVC for UI components you can get elsewhere.

Minimal install path:

composer require laravel-streams/ui
php artisan vendor:publish --tag=streams.ui   # publishes config and views

Verify the UiServiceProvider is registered (usually auto-discovered) and that the Streams install command has already run for core. Pin exact versions in composer.json — no floating constraints — because streams/ui ships as part of the platform release train and will hard-align with streams/core.

Where to look first, in this order:

1. config/streams/ui.php (or config/ui.php) — theme, control-panel route prefix, asset paths, layout bindings. This is the file that answers "why does the CP render like that?".
2. resources/views/ — the published layout, partials, and Blade components. This is your override surface, not your boilerplate source.
3. src/Streams/Ui/ — service providers plus Http/ and Support/ helpers. Read the source; documentation on a three-star package will not cover the extension points you need.
4. The core cp route group — this is the /admin surface the package themes.

First use case: boot the control panel. Register the provider, hit /admin (or your configured prefix), and confirm the login screen renders. That single page exercises routing, assets, layouts, and the auth guard, so it is the fastest smoke test you have.

Second use case: wire one addon end to end. Give an addon a section, a couple of fields, and a list view, then confirm it appears in the CP navigation. That closes the core ↔ ui loop and is the real go/no-go on whether the abstraction saves you time or fights you.

Implementation Patterns

Compose pages from the shipped Blade components. The package's day-to-day value is that addon views do not hand-roll markup. Use the provided cards, buttons, tables, alerts, modals, and form wrappers so styling stays consistent with the rest of the CP:

<x-ui::card>
    <x-slot name="header">{{ $title }}</x-slot>
    {{-- fields, tables, actions --}}
</x-ui::card>

Reach for the wrappers and slot conventions first; copy markup out of published views only when you have decided to override, not as a starting point.

Register UI from addon service providers, not routes. The working pattern is: an addon declares a section or CP entry, and ui renders the navigation, breadcrumbs, and layout around your views. Keep route registration inside the addon provider and let the UI package own the chrome:

protected function bootNavigation(): void
{
    $this->sections()->add('reports', [
        'title' => 'Reports',
        'route' => 'addon.reports.index',
    ]);
}

Lean on the form and table builders for CRUD. For the resource screens that dominate back-office work, drive forms and tables through the platform builders rather than writing raw Blade. This is where the package actually accelerates delivery — it is the part worth learning deeply and the part that determines whether adoption paid off.

Customize via published views and theme config, not by editing vendor/. Publish the ui tag, override the layout or partial you need, and record each override. Theme lock-in is a real cost later, so keep the override set small and documented.

Isolate streams/ui behind a service boundary. Given three stars, zero dependents, and single-vendor stewardship, wrap CP entry points so the UI layer can be swapped or forked without destabilising the rest of the app. If you expect to migrate off Streams eventually, keep the domain logic out of your Blade overrides.

Treat the published views as a diffable fork, not ad-hoc edits. Establish a fork policy up front — a tracked fork with a documented delta is far cheaper than one-off vendor/ patches when the next platform release lands.

Gotchas and Tips

• It is not a drop-in for existing Laravel apps. Adopting it into a conventional Eloquent/Blade codebase means running Streams alongside your existing MVC. The realistic path is a strangler pattern, migrating administrative surfaces addon by addon — validate routing, auth, sessions, and asset publishing coexistence before committing.
• Version pinning is non-negotiable. Expect hard alignment with streams/core and possibly sibling addons. Pin exact versions, commit composer.lock, and test the full matrix (PHP, Laravel major, Node for asset compilation, database driver) rather than assuming.
• Zero dependents means zero precedent. There is no downstream issue history, no community-tested upgrade path, and no hiring pool to lean on. The first integration is effectively greenfield research — budget weeks, not days, before a developer is productive.
• Read streams/core first, streams/ui second. The Streams mental model — streams, fields, assignments, criteria, repositories, addons — must land before the UI layer makes sense. Onboarding through the UI package alone will be slow and confusing.
• Debugging the CP: if /admin 404s or renders unstyled, check, in order — the configured route prefix in the ui config, that the ui service provider is registered, that assets were published, and that the core install ran. A broken login screen is almost always one of those four.
• Semver discipline is unverified. On a package with this adoption profile, assume breaking changes may land in minor releases; read the changelog before every bump, and schedule upgrades as planned work tied to Laravel majors. An abandoned UI layer pinning the app to an unsupported Laravel version is a security-patching incident, not a feature bug.
• Watch the asset build pipeline. Confirm whether theme compilation is part of the deploy or the request path, and audit cache busting, CDN behaviour, and any custom Vite/Mix setup. Toolchain drift (Node version) is a plausible breakage vector.
• Extension points are source-read, not documented. Custom fields, table columns, form controls, and theme hooks exist but will be learned by inspecting src/Streams/Ui/ and the core addon contracts. Capture what you learn in an internal primer — knowledge concentration in one spike owner is a real bus-factor risk.
• Keep an exit assessment on file. Document how much of the application is genuinely portable back to plain Laravel, so a decision to abandon the platform is a scheduled migration rather than an incident.