Ui Laravel Package

Getting Started

mach3builders/ui is a small, low-adoption package (1 star, 0 dependents, last release July 2024) that ships Blade-facing UI primitives for Mach3Builders' internal design system. Treat it as an opinionated, possibly internal-only package rather than a general-purpose component library — the fastest way to understand it is to read the source, not the README.

Minimal steps:

1. Install and inspect before configuring.

   composer require mach3builders/ui
   

   Then immediately open vendor/mach3builders/ui/ and read:

   • the service provider (src/*ServiceProvider.php) — this tells you what gets registered, what's publishable, and whether any Blade directives/namespaces are added
   • resources/views/ — the actual component surface area
   • config/ — whether config is publishable at all

   With a package this small, the service provider is the documentation.

2. Publish what's publishable.

   php artisan vendor:publish --provider="Mach3Builders\Ui\UiServiceProvider"
   

   Check the provider for tag names first (--tag=ui-config, --tag=ui-views, etc.); guessing tags on a low-traffic package wastes time. Published views are your override mechanism, so publishing early saves you a later vendor:publish --force.

3. Confirm the frontend dependency. This package almost certainly assumes Tailwind CSS and a specific design-token set (colors, spacing, radii). Before writing any markup, check whether it ships precompiled CSS, a Tailwind preset, or nothing at all. If nothing, you'll need to add its view paths to your tailwind.config.js content array:

   content: [
     './resources/**/*.blade.php',
     './vendor/mach3builders/ui/resources/views/**/*.blade.php',
   ]
   

4. First use case: a single form. Don't adopt the whole design system at once. Pick one real screen — a create/edit form is ideal because it exercises inputs, labels, validation states, and buttons — and rebuild it with the package's components. You'll learn the naming conventions, the prop API, and the styling assumptions in one pass, and you'll have a clean before/after to judge whether the package earns its place.

If step 4 reveals that the components are thin wrappers you could write in an afternoon, that's a valid outcome: vendor the views into your app and drop the dependency.

Implementation Patterns

Blade component invocation is the primary interface. Expect anonymous or class-based components registered under a package namespace, e.g. <x-ui::button> or <x-mach3::input>. Enumerate them once and keep a local cheat sheet:

php artisan blade:list   # if available in your Laravel version
# or simply:
ls vendor/mach3builders/ui/resources/views/components/

Grep the views for @props to extract each component's accepted attributes — this is faster and more reliable than any docs.

Layout shell pattern. Packages like this usually ship one or more layout components (<x-ui::layouts.app>) that assume slots like $slot, $title, and named slots for nav/footer. Adopt the package layout as your base resources/views/layouts/app.blade.php wrapper rather than using it directly in pages — that indirection is your escape hatch when the package goes stale:

{{-- resources/views/layouts/app.blade.php --}}
<x-ui::layouts.app>
    <x-slot:title>{{ $title ?? config('app.name') }}</x-slot:title>
    {{ $slot }}
</x-ui::layouts.app>

Every page then extends your layout, so swapping or forking the package touches one file.

Compose, don't configure. For form controls, the idiomatic pattern is wrapping rather than passing a dozen props:

{{-- resources/views/components/field.blade.php --}}
@props(['name', 'label'])
<div class="mb-4">
    <x-ui::label :for="$name">{{ $label }}</x-ui::label>
    {{ $slot }}
    @error($name) <x-ui::error>{{ $message }}</x-ui::error> @enderror
</div>

This keeps Blade templates readable and insulates you from prop-name churn in the package.

Pair with Laravel's form/validation layer, not instead of it. Use old() and @error at the call site; the package should only own presentation. If its components try to own validation display logic, that's a signal the abstraction is too heavy for your app.

Asset integration via Vite. Add the package's published CSS entry (if any) to resources/css/app.css with @import or @source, and register any JS in resources/js/app.js. Keep the package's assets in your own build pipeline rather than relying on a vendor:publish --tag=assets copy into public/ — published public assets go stale on composer update and are easy to forget.

Overriding components. Publish views, then edit the published copy. Laravel resolves published views ahead of the package path, so this is a clean, upgrade-safe override — but only for views you actually publish. Publish selectively; publishing all of them turns every future package change into a manual merge.

Integration tip: gate it behind a feature flag in a live app. Wire the components into one route or one admin area first, and use a config flag to switch between old and new markup. Given the package's adoption level, you want a one-line rollback.

Gotchas and Tips

The adoption signal is the headline gotcha. One star, zero dependents, a single 2024 release. This is very likely an internal package published publicly for Composer convenience rather than a maintained library. Practical consequences: no community answers when something breaks, no security response process, and no guarantee the next release isn't a breaking change. Pin it exactly in composer.json ("mach3builders/ui": "1.0.0" rather than ^1.0) and be prepared to fork.

Verify Laravel version constraints before committing. A mid-2024 package may not declare support for the newest Laravel major. If composer require fails on constraints, don't reach for --ignore-platform-reqs in a real project — check whether the package's only real dependency is illuminate/support and whether a fork with a widened constraint is trivial.

Tailwind purging silently breaks styling. The most common failure mode for Blade component packages is missing content globs for the vendor view path. Symptoms: components render but are completely unstyled, or only partially styled (classes present in some components, absent in others). Fix by adding the vendor glob and restarting the Vite dev server — Tailwind's content scanning doesn't always pick up new globs hot.

Config file published ≠ config read. If config keys appear to have no effect, check the provider's mergeConfigFrom call. Some small packages publish a config file but never merge it, or read config() at boot time before your published file is loaded. php artisan config:clear after every publish is cheap insurance.

Class-based vs. anonymous components resolve differently. Anonymous components resolve by view path; class-based ones by namespace registration in the provider. If <x-ui::foo> throws "unable to locate component," confirm the namespace prefix in the provider (Blade::componentNamespace(...)) — the prefix may not be ui.

Attribute and class merging. If components use $attributes->merge(), your own class="..." at the call site may be overwritten or duplicated depending on merge order. Test explicitly: pass a conflicting utility class (e.g. class="mt-8" against a component that sets mt-4) and confirm which wins. This is where design systems get frustrating in production.

Extension points, ranked by safety: (1) wrapping components in your own Blade files, (2) publishing and editing individual views, (3) extending class-based components, (4) editing the vendor tree. Only (1) and (2) survive a composer update; (4) should be a fork, not an edit.

Debugging technique that pays for itself. When a component misbehaves, temporarily add {{ dump(get_defined_vars()) }} at the top of the published view. It reveals every prop, slot, and attribute bag the component actually received — far faster than reading the class definition.

Have an exit plan. Because the package is mostly Blade views plus optional Tailwind config, migrating away is a mechanical job: copy the view files you rely on into resources/views/components/, strip the namespace prefix from call sites (<x-ui::button> → <x-button>), and remove the dependency. Decide up front how many components you'd need to absorb before that exit becomes worth it — and if the answer is "few," consider doing it now.