Ux Bootstrap 5 Laravel Package

Getting Started

Start with the framework mismatch, because it determines everything else. composer require krystal-sf/ux-bootstrap-5 into a Laravel app gets you a Symfony bundle: a Bundle subclass, Twig templates, Stimulus controllers registered through the Symfony UX Stimulus bridge, and asset wiring for AssetMapper or Webpack Encore. Laravel has none of those primitives. There is no service provider, no Blade views, no Vite manifest hook. So the honest first step is not installation — it is deciding that you are reading this repository as a markup and behaviour specification, not installing it as a dependency.

Where to look first, in order:

1. src/ for the bundle class and any Twig namespace / form-theme registration — this tells you which templates are actually the product versus which are glue.
2. The form theme template(s) — typically a form/bootstrap_5_layout.html.twig plus per-type blocks (form_widget, choice_widget, checkbox_widget, file_widget, form_errors, form_help). This is 80% of the package's value and the only part you will actually port.
3. assets/controllers/ for the Stimulus controllers. Read them to identify what behaviour is being wired (dropdowns, modals, autocomplete, dropzones, tooltips) and how small each one is — most are three-line wrappers around Bootstrap's own JS.
4. Any package.json / importmap.php / webpack.config.js to see which Bootstrap version is pinned and how CSS is imported.

First use case — one control end to end. Pick the highest-traffic control in your app (usually a text input with label, help text, and validation state, or a <select>). Extract the exact Bootstrap 5 markup the theme emits for it, and rebuild it as a single Blade component:

{{-- resources/views/components/form/input.blade.php --}}
@props(['name', 'label' => null, 'help' => null])
<div class="mb-3">
    @if ($label)
        <label for="{{ $name }}" class="form-label">{{ $label }}</label>
    @endif
    <input
        id="{{ $name }}"
        name="{{ $name }}"
        {{ $attributes->class(['form-control', 'is-invalid' => $errors->has($name)]) }}
    >
    @if ($help)
        <div id="{{ $name }}-help" class="form-text">{{ $help }}</div>
    @endif
    @error($name)
        <div class="invalid-feedback">{{ $message }}</div>
    @enderror
</div>

Get one component right, with a rendered-HTML test, before extracting the rest. That single file is the deliverable; the repository was the input.

Implementation Patterns

Pattern 1 — markup-contract extraction (the default). Walk the Twig form theme block by block and record, for each control type, the exact class list and wrapper structure: mb-3 row wrapper, form-label, form-control / form-select / form-check, form-text for help, invalid-feedback for errors, input-group for prefix/suffix, is-invalid / is-valid on validation states, aria-describedby linking help and error nodes to the input. Turn each into a row in a short table (control type → markup contract). That table is your Blade component API and your test fixture source.

Pattern 2 — Blade component library with HTML snapshot tests. Build x-form.input, x-form.select, x-form.checkbox, x-form.radio-group, x-form.file, x-form.textarea, x-form.errors, x-form.help. Assert rendered HTML against the extracted contracts with Pest/PHPUnit snapshot assertions. This is what makes the port durable — without tests, "we ported the Bootstrap theme" silently drifts the moment someone edits a component.

Pattern 3 — behaviour via Bootstrap's own JS, not Stimulus. Everything the Stimulus controllers do is already available through data-bs-toggle / data-bs-target attributes and bootstrap.bundle.js. Import once in resources/js/app.js:

import * as bootstrap from 'bootstrap';
window.bootstrap = bootstrap;

and rely on declarative data-bs-* attributes in Blade. Use Alpine for genuinely custom behaviour (dependent selects, autocomplete) rather than reimplementing Stimulus controllers. Alpine lives in the DOM you already control; Stimulus assumes a Symfony controller registry that does not exist here.

Pattern 4 — Symfony side-by-side, source-level only. If your organisation also runs Symfony services, the package may belong in that repo — but keep the two codebases separate. Do not attempt dual-framework runtime coexistence or share a PHP package across a Symfony and a Laravel service. Port markup and behaviour at source level; share nothing at runtime.

Pattern 5 — asset pipeline consolidation. Install [email protected] via npm, pin the exact version in package.json, import it once from resources/css/app.css and resources/js/app.js, and configure the theme override layer after the import. Standardise on one import path across the app; if a second team starts pulling Bootstrap from a CDN or an old Compile-time asset pipeline, you get duplicate CSS and version skew, which is the one scaling failure mode that actually bites.

Workflow that works:

1. Clone the repo, read the form theme, note the Bootstrap minor version it targets.
2. Confirm the license before copying any markup (see Gotchas).
3. Extract the markup contracts into a table.
4. Build Blade components against those contracts, one at a time, with snapshot tests and an axe-core assertion in the test suite.
5. Wire validation states from Laravel's $errors bag rather than Symfony's form error iterator — the mapping differs and is where most porting bugs appear.
6. Install and pin Bootstrap 5 via Vite; delete any ported asset-registration code.
7. Write a one-page ADR: package evaluated, rejected as a dependency, patterns adopted, origin recorded. Future maintainers will ask.

Laravel-native equivalents you should reach for instead of any wrapper: Laravel's built-in Bootstrap pagination views (Paginator::useBootstrapFive()), x-form.* Blade components, @error / $errors for validation display, and old() for repopulation. That combination covers everything this package does on the form side, in a stack you already own.

Gotchas and Tips

It is not a Laravel package, and installing it will not work. There is no service provider, no Blade namespace, no Vite integration. If someone adds it to composer.json "to try it," they will pull in a Symfony bundle class that Laravel's container never registers, plus transitive Symfony UX dependencies that will sit unused in vendor/. Remove it and read the source instead.

License opacity is the blocking gotcha. The repository shows no confirmed license in the metadata available. "Extract and port the markup" is still derivative work. Resolve the license before copying a single class list — not after the components ship. If the license is unclear or restrictive, fall back to Symfony UX's public Bootstrap 5 form theme and Bootstrap's own form documentation as your reference; both are better documented and carry real community usage.

Twig block inheritance does not map to Blade slots. Symfony's form theme is a hierarchy of {% block %} overrides with parent calls; Blade components are self-contained with slots. Do not try to replicate the inheritance tree. Flatten it: each control gets one component, and shared wrapper markup lives in an x-form.row or a layout component. Resisting the temptation to mirror the Twig structure is the single biggest time saver in the port.

Validation state mapping is where behaviour diverges. Symfony's form theme renders errors as part of a form view object (form.vars.errors, form_errors block). Laravel uses a ViewErrorBag keyed by field name with dot notation for nested fields (addresses.0.city). Port the markup, then write a small helper or Blade directive that resolves the error-bag key for nested/array inputs — Symfony's flattening does not match Laravel's. Test the nested case explicitly; it is the one that silently breaks.

Accessibility regressions are the most common porting defect. Symfony's theme likely wires aria-describedby to help and error nodes and aria-invalid on the input. Hand-ported Blade components routinely drop these. Add them to the component template, and assert them in the snapshot test. An axe-core pass in the component test suite catches the rest.

Bootstrap JS state and Livewire/Inertia navigation. Bootstrap's JS attaches listeners at page load; Livewire's wire:navigate swaps the DOM without a reload, so dropdowns and modals attached to the old DOM stop responding. Re-initialise on livewire:navigated, or — better — lean on declarative data-bs-* attributes, which Bootstrap resolves on interaction and therefore survive DOM morphs more gracefully. Modals still need an explicit hidden.bs.modal reset if a Livewire request errors mid-modal; that is a Laravel problem, not this package's, and the package offers no help with it.

Version coupling and the Bootstrap 6 horizon. The package targets a specific Bootstrap 5 minor and a specific Symfony/Stimulus generation. Bootstrap 5 is in maintenance and Bootstrap 6 will change utilities and component APIs. A single-vendor wrapper with zero dependents will not lead that migration. Pin bootstrap in package.json, keep your Blade components thin over utility classes, and treat the eventual 5→6 pass as a scoped component-library task — which it only is if you own the layer.

Debugging the source when it misbehaves: there is no issue tracker activity to consult and no support channel. The Stimulus controllers are small enough to read in full; if a behaviour puzzles you, check whether it is just a wrapper around a documented Bootstrap plugin method before assuming custom logic. In practice, almost nothing in this package is custom — which is precisely the argument for sourcing it from Bootstrap directly.

Extension points you can rely on: essentially none. There is no documented theming API, no compatibility matrix, no named maintainer visible. Treat the repository as frozen: fork it if you must, vendor the extracted markup into your own components if you prefer, but plan on owning every future change. The cost of writing the equivalent Blade components yourself is a few days and is bounded; the cost of an unowned dependency in the rendering path is neither.

Do not cite it in a Laravel architecture review as an option. At most it is a reference implementation to read for how a Bootstrap 5 form theme organises its wrappers and validation states — and that insight is obtainable from the Bootstrap docs and Symfony UX's public theme, at zero supplier risk.