Tomato Splade Laravel Package

Getting Started

Decide which Splade you're installing first. This package is a fork of protonemedia/laravel-splade with TomatoPHP-specific components and "selected updates." If you're on a standalone Laravel app, install upstream instead — you get the same Blade-driven SPA model with an actual changelog. Install this one when you're already inside the Tomato PHP admin stack and want its prebuilt profile/admin screens.

composer require tomatophp/tomato-splade
php artisan vendor:publish        # pick the splade + tomato-splade tags shown
php artisan splade:install        # confirm the command exists: artisan list | grep splade
npm install && npm run dev

The install command publishes config/splade.php and the vendor Blade views; both are your primary customization seams. If the command name differs in the fork, read src/ — the service provider will tell you what it registers and what it publishes.

Look here first, in order:

1. config/splade.php — middleware, component aliases, SSR toggle. Understand what middleware gets pushed onto the web group.
2. resources/views/vendor/splade/ — the actual component templates. This is where you learn what the components do, since documentation will be thin.
3. The package's routes/ and prebuilt profile/admin views — these are the "out of the box" value; confirm they match your auth model before assuming they're drop-in.
4. composer show tomatophp/tomato-splade and a diff against upstream Splade — this is the single most useful 30 minutes you'll spend. You need to know what the fork changed to know what you can't get support for.

First use case: take one read-only index page — a users list, a logs table — and convert it in place to an <x-splade-table>. Nothing is at risk, you learn the request lifecycle, and you get a real measurement of build time and bundle delta before committing anything interactive.

Implementation Patterns

Forms keep Laravel validation. This is the whole pitch — you write Blade, Splade handles the reactive plumbing.

<x-splade-form :default="$user" action="{{ route('users.update', $user) }}" method="put">
    <input v-model="form.name" />
    <p v-if="form.errors.name" v-text="form.errors.name" />

    <x-splade-submit label="Save" :spinner="true" />
</x-splade-form>

The controller is unchanged Laravel — $request->validate(), redirect with a flash message. Splade intercepts the submit, posts it, and merges the 422 error bag back into form.errors. Do not hand-roll the submit handler; you lose the error bag and the redirect handling.

Tables are the highest-leverage component. Search, sort, and pagination are server-driven with almost no code:

<x-splade-table :for="$users" :search-debounce="400">
    @cell('name', $user)
        <x-splade-link :href="route('users.show', $user)">{{ $user->name }}</x-splade-link>
    @endcell
    @cell('actions', $user)
        <x-splade-link method="delete" :href="route('users.destroy', $user)" confirm>Delete</x-splade-link>
    @endcell
</x-splade-table>

The for prop takes a paginator, not a collection. Wire ->search(), ->sort(), and ->paginate() in the controller — the component handles the query-string round-trips.

Wrap fork-specific components behind your own. The single most important discipline for a package with 2 stars and no upstream lifeline:

{{-- resources/views/components/ui/table.blade.php --}}
<x-splade-table {{ $attributes }}>{{ $slot }}</x-splade-table>

Use <x-ui.table> everywhere in your app, never <x-splade-table> directly. When this fork rots against a Laravel major, a swap to upstream Splade or a hand-rolled Inertia table is one file, not four hundred.

Roll out route-scoped, not globally. Splade middleware is applied at the route level, so you can SPA-ify an admin prefix while leaving public marketing pages as plain Blade with server-rendered HTML. Start with the lowest-traffic internal module behind a feature flag; expand module by module.

Lazy-load anything expensive. <x-splade-defer url="/stats" method="get"> with @loading and @response slots lets a dashboard render instantly and hydrate heavy widgets second. This is also your bundle-size lever.

Use <x-splade-modal> for create/edit instead of separate pages — it's the main reason internal-tool delivery speeds up. Pair it with Splade::toast() for confirmation and you have a CRUD loop with no page reloads.

Keep local UI state in <x-splade-data> / <x-splade-toggle> rather than reaching for a separate Vue entry point. If you find yourself writing an SFC, either Splade isn't the right tool for that screen or you've left the intended authoring model — flag it rather than working around it.

Gotchas and Tips

Tailwind will purge the vendor views. By far the most common "the component renders unstyled" bug. Add the package's Blade paths to tailwind.config.js content and rebuild:

content: [
  './resources/**/*.blade.php',
  './vendor/tomatophp/tomato-splade/resources/**/*.blade.php',
],

Check for a duplicate Splade install. If protonemedia/laravel-splade is also pulled in as a transitive dependency you get two service providers, two sets of Blade components registered under the same names, and nondeterministic rendering. Run composer why protonemedia/laravel-splade on day one. The fork must replace or conflict it; if it does neither, you own that reconciliation manually.

Debugging SPA requests: open DevTools → Network. Splade requests carry custom headers and return JSON; non-SPA requests return full HTML. If the browser renders raw JSON, the request was treated as Splade and your layout didn't wrap the response — usually a missing middleware registration or a route outside the SPA'd group. php artisan route:list -v shows what's actually attached.

Clear caches after any publish. Published views and config are cached aggressively. php artisan view:clear && php artisan config:clear should be reflex after vendor:publish.

Validation errors only appear inside <x-splade-form>. A plain <form> on the same page won't show them — errors arrive as a JSON bag consumed by the form component. If you're mixing hand-written forms with Splade ones, expect confusion.

Rebuild assets after every publish and every composer update. Splade's JS isn't a CDN script; it's part of your Vite build. A stale public/build gives you a page where components silently render inert.

Pin everything and mirror the repo. composer.lock plus explicit Laravel/PHP/Node/Inertia constraints. Mirror or vendor the package into a private registry so a Packagist change or an unreviewed release can't break your build. Run composer why-not and npm audit in CI.

Don't put SEO-critical or public pages on this stack. SSR support is thin and unverified in the fork. Keep marketing pages plain Blade.

Testing: Splade has no first-class test helpers. Keep your HTTP feature tests on controllers (they still pass — the server side is ordinary Laravel), and use Dusk or Playwright for anything that requires hydration. Don't try to unit-test the Vue layer.

Extension points, ranked by safety: publish and override vendor Blade views → register your own View Components in app/View/Components → wrap the Splade:: facade → only then patch the package source, and only inside your mirror with the patch documented.

Name a steward. With zero dependents and a last release in April 2024, "we'll deal with it later" is how the fork rots against a Laravel upgrade and freezes your app. Write down who owns the upstream-diff cadence and the security-patch procedure before the second module ships, not after.