Tallstackuifilament Laravel Package

Getting Started

Treat this as a thin integration layer, not a batteries-included package. The order of operations matters:

1. Confirm your stack versions match. Check composer.json of the package against your installed filament/filament, tallstackui/tallstackui, and livewire/livewire versions. With only ~10 stars and a single dated release, you should not assume Filament v4 or newer TallStackUI majors are supported.
2. Install TallStackUI first, then the bridge. The integration depends on TallStackUI already being set up (service provider, Tailwind config, Alpine plugin). Don't install the bridge into an app that hasn't finished the base TallStackUI setup.
3. Register the plugin on your panel. The primary entry point is a Filament plugin class you add in your PanelProvider's ->plugin() chain — open src/ and locate the plugin class (typically *Plugin.php) to see exactly what it registers (theme, views, assets, or custom components).
4. First use case: render a small Filament resource form (e.g., a TextInput and Select) using the TallStackUI-styled components rather than Filament's stock ones, so you can confirm styling, Alpine interactivity, and dark mode all survive the round-trip through Filament's form renderer.

If the README is thin (very likely here), the fastest path is: install, register the plugin, create a one-field form, and diff the rendered HTML against a plain TallStackUI Blade view to see what the integration actually changes.

Implementation Patterns

Plugin-registration pattern. Most of what this package does lives in the Filament plugin class. Register it like any other Filament plugin:

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            \Andrefelipe18\TallStackUIFilament\TallStackUIFilamentPlugin::make(),
        ]);
}

Confirm the plugin's register() and boot() methods to know whether it's pushing assets, views, or colors — that tells you where to look when something renders wrong.

Theme / preset swap. The typical use case is making Filament use TallStackUI's look instead of Filament's default theme. Expect the integration to either ship a Tailwind preset or expose a ->theme() / ->preset() chain on the plugin. Keep one source of truth for colors: if you define a primary palette in TallStackUI, mirror it in the Filament panel config so buttons, badges, and notifications stay consistent.

Custom page pattern. For panels that mix admin CRUD with handcrafted TallStackUI screens, use Filament custom pages as the seam. Render your TallStackUI Blade content inside a Filament page's getView(), so you gain Filament's auth, navigation, and layout while keeping TallStackUI's component ergonomics. This is the pattern that pays off day-to-day — you don't have to choose between "Filament admin" and "hand-rolled Blade."

Resource form pattern. Start with one resource, convert a subset of fields to TallStackUI-backed inputs, and compare against Filament's native inputs. Anything that relies on Filament's richer field features (relationship search, ->reactive(), complex validation states) may not carry over cleanly, so migrate field-by-field rather than rewriting a whole form.

Dark mode. Wire the dark mode toggle once at the panel level (a header action calling $this->dispatch('dark-mode-toggled') or whatever the integration exposes) and make sure both Filament's dark: classes and TallStackUI's dark tokens resolve against the same root class. Test in a fresh browser profile — cached dark-mode state is the top "it looks broken" false alarm.

Vite build step. Anything this package ships as a theme still compiles through your app's Vite pipeline. Add the package's CSS entry to your vite.config.js inputs if it isn't already, and run npm run build (not just dev) before deploying.

Gotchas and Tips

• Version pinning is non-negotiable. With one release and low adoption, pin exact versions of this package and TallStackUI in composer.json ("andrefelipe18/tallstackuifilament": "x.y.z"). Don't use ^ and don't let composer update pull a TallStackUI major that changes component tokens.
• Tailwind content paths. If styles are missing, the classic cause is the Tailwind content array not scanning the package's compiled views/classes. Add the package's src/ or resources/views path to tailwind.config.js and rebuild. If the package ships pre-compiled CSS, verify it's actually pushed via the plugin's FilamentAsset registration.
• Asset pipeline order. Filament assembles CSS/JS in a specific order at boot. If your custom panel theme is overriding TallStackUI styles, check php artisan filament:assets output and inspect the rendered <link> order in the page source. php artisan filament:assets after any plugin or theme change.
• Cache layers to clear. When changes don't appear: php artisan view:clear, php artisan filament:clear-cached-components, php artisan optimize:clear, then hard-refresh the browser. Nine times out of ten on a package this young, the problem is stale cached views rather than the package itself.
• Alpine plugin registration. TallStackUI depends on Alpine plugins registered via Livewire::listen('livewire:init') or a script tag. Filament also initializes Livewire. If interactive components (dropdowns, modals, tabs) don't work, verify Alpine isn't being initialized twice — inspect console for Alpine already initialized warnings.
• Blade component name collisions. Filament and TallStackUI both register Blade components with similar names (e.g., x-button, x-input). If you're rendering one and getting the other, the package likely resolves this by a namespace prefix like x-tallstackui-button. Prefer the namespaced alias in custom Blade views.
• Dark mode root class mismatch. Filament uses .dark on <html> while some TallStackUI presets expect it on <body> or read from a different source. If only part of the UI goes dark, this is the culprit. Fix with a small Tailwind variant or a JS shim before the page renders.
• Check the plugin's boot() for a hidden Theme:: call. That's the most common place these integrations diverge from your expected panel config — knowing whether the theme is set inside the plugin or by your own ->theme() call determines what wins.
• Don't trust the README to be current. Diff the src/ classes against the release tag you installed. The description and release date tell you the project is a one-person effort; treat the code as the source of truth.
• Extension point to watch: if the plugin exposes a ->colors([...]) or ->preset() method, that's your stable seam. Favor using it over editing published views or re-emitting the theme, so upgrading past the current single release stays tractable.
• Debugging tip: create a throwaway route with Route::get('/debug-tall', fn () => view('tallstackui.plain')) (or any base TallStackUI view) outside Filament. If it renders correctly there but breaks inside Filament, the problem is in the integration/theme wiring, not in TallStackUI itself — and you've halved the surface area in one step.
• Budget for abandonment. 10 stars, one release, zero dependents. It's a good fit for a side project or a spike; for a production panel, isolate the integration behind a small internal wrapper so swapping it out later is a one-file change.