Vibeui Laravel Package

Getting Started

vibeui is a pre-1.0 Laravel UI package (currently 0.8.0), so treat the README and CHANGELOG.md as the source of truth for the exact API surface — the release notes only confirm the new alert/flash feature.

1. Install: composer require teknovateid/vibeui (pin ^0.8 deliberately; see Gotchas).
2. Publish whatever the service provider exposes: php artisan vendor:publish --provider="TeknovateId\VibeUI\VibeUIServiceProvider" — check for tagged publishes (config vs. views vs. assets) rather than publishing everything blindly.
3. Inspect config/vibeui.php (prefixes, component namespace, asset paths) and the package's resources/views/ directory to see the component inventory before writing any markup yourself.
4. First use case: drop the package layout into a page and render one component, e.g. <x-vibeui::alert type="success">Saved.</x-vibeui::alert>, then confirm the asset/CSS pipeline is loading.

For v0.8.0 specifically, the first thing to try is the flash flow: redirect with session()->flash(...) from a controller and confirm the alert renders on the next page load without any extra wiring.

Implementation Patterns

• Flash alerts from controllers. The new feature is the highest-value pattern: flash a message in your controller and let the package's alert component pick it up on redirect.

  return redirect()->route('posts.index')->with('vibeui_alert', [
      'type' => 'success',
      'message' => 'Post created.',
  ]);
  

  Confirm the exact key and shape the package expects — the release notes don't spell it out, so check docs/ or the component class. Where possible, wrap this in a small helper or a FlashMessage trait on your base controller so the key lives in one place.
• Centralise flash in a layout partial. Put the alert render in layouts/app.blade.php (or a partials/flash.blade.php) so every page gets it, rather than repeating the component per view.
• Map Laravel's built-in flashes onto the package's format. If you already use ->with('success', ...) / ->with('error', ...), either migrate call sites or add a middleware/view composer that translates legacy keys into the vibeui structure. This keeps the change incremental across a large codebase.
• Validation errors as alerts. Since validation redirects are flashes too, decide explicitly whether the package alert handles the error bag or whether you keep field-level errors separate. Mixing both without a rule produces duplicated messages.
• Compose with your own components. Treat vibeui as a presentation layer: wrap its alerts in an app-owned <x-app-alert> that enforces your icon, dismiss behaviour, and copy conventions, so a future package bump doesn't ripple into every view.
• Progressive adoption. If you're introducing it into an existing app, start with the alert path only — it's the newest, most self-contained feature and doesn't force a layout rewrite.

Gotchas and Tips

• Pre-1.0 versioning. In 0.x, a minor bump (0.7.2 → 0.8.0) is allowed to break things under semver. Pin "teknovateid/vibeui": "~0.8.0" and read the changelog before each upgrade; don't rely on ^0.7-style ranges to protect you.
• Flashes are single-request by design. If alerts vanish after one navigation, that's Laravel's flash semantics, not a package bug. Use ->with() for redirects; session()->now() only when you intend it to survive within the same request.
• Duplicate rendering. Rendering the alert in both the layout and a page view is the most common cause of "the message shows twice". Pick one location.
• Publishing views shadows updates. Once you publish and edit the package's Blade files, new releases won't reach them. Prefer overriding via your own wrapper component, or re-publish and diff on each upgrade.
• Asset/CSS coupling. UI packages usually assume Tailwind (or ship precompiled CSS). Check whether you need a @vibeuiStyles/@vibeuiScripts directive in your layout and whether your build actually includes the package's source paths in tailwind.config.js content — missing that yields unstyled alerts.
• Dismiss/JS behaviour. If the alert is dismissible, verify the JS is loaded on pages outside your main layout (auth screens, error pages) — those are the usual casualties.
• Debugging empty alerts. When nothing renders, check in order: is the key/type value one the component recognises; is the flash still present (session()->all()); is the component actually in the layout; does the component namespace match the config prefix.
• Error pages and emails. resources/views/errors/* and mail templates usually don't extend your app layout, so flashes and package assets won't appear there — that's expected, but worth a conscious decision.
• Docs drift. This release includes a documentation update alongside the feature, which is a good sign, but for a 0.x package always verify the README against the installed tag (vendor/teknovateid/vibeui/) rather than the main branch — you may be reading docs for an unreleased version.