Fission Laravel Package

Getting Started

joshcirre/fission is a starter kit, not a runtime dependency — you scaffold an application from it rather than composer require it into an existing one. Day-to-day "usage" is really working inside the conventions it ships with, so the first hour is about learning the kit's opinionated seams.

Scaffold it

laravel new my-app --using=joshcirre/fission
cd my-app
composer install && bun install
cp .env.example .env && php artisan key:generate
php artisan migrate --seed
composer run dev          # serve + queue + logs + vite/bun in one process

(GitHub "Use this template" + composer install && bun install && php artisan migrate --seed works equally well if you don't use the installer.)

Look here first, in this order

First real use case: ship a team-scoped CRUD page — Flux table + modal form in a Livewire 4 single-file component, a TeamPolicy, and a Pest 4 feature test. That single slice exercises every convention in the kit at once.

Sanity-check the install before building: php artisan about, php artisan route:list --except-vendor, then log in and hit the dashboard. If the manifest error appears, you skipped bun run build (see Gotchas).

Implementation Patterns

1. Skill-first, then code. Treat the skills as pre-flight checklists, not documentation. Before touching a <flux:*> view, activate fluxui-development; before wiring wire:model or islands, livewire-development; before writing any test, pest-testing. The kit is designed so an agent (or you) loads the relevant skill instead of rediscovering the patterns each time.

2. The Boost loop. When the MCP server is wired up, the day-to-day cadence is:

search-docs(['validation', 'form request'])   → version-correct API
database-schema                                → actual columns before a migration
<write the code>
php artisan test --compact --filter=projects   → prove it
vendor/bin/pint --dirty --format agent         → style

search-docs is scoped to the installed versions automatically — use broad topic queries (['rate limiting', 'routing']), not package names.

3. Team-scoped feature slice. The kit's team convention is: current_team_id on the user, team-prefixed URLs, team_id on owned records, queries routed through the bound Team, authorization through TeamPolicy.

// routes/web.php
Route::middleware(['auth', 'verified'])->prefix('{team}')->group(function () {
    Route::get('/playground', PlaygroundIndex::class)->name('playground.index');
});

// app/Livewire/PlaygroundIndex.php  (page-level SFC is often the right call here)
final class PlaygroundIndex extends Component
{
    public Team $team;

    public function mount(Team $team): void
    {
        $this->authorize('view', $team);
        $this->team = $team;
    }

    public function render(): View
    {
        return view('livewire.playground-index', [
            'projects' => $this->team->projects()->latest()->get(),
        ]);
    }
}

Resolve records through the bound model ($team->projects()), never Project::find($id) — that's how cross-team leaks get in.

4. Flux for UI, Tailwind for layout. Compose with <flux:main>, <flux:heading>, <flux:table>, <flux:modal> rather than hand-rolling equivalents; drop to Tailwind utilities for grid/flex scaffolding. Forms follow the Livewire pattern: wire:model bound properties → validate() in the action → Flux::toast() on success.

5. Testing cadence. Feature tests for behavior, arch() for structure, browser tests for the smoke path. Keep it narrow and fast:

it('lists team projects', function () {
    $team = Team::factory()->create();
    $user = User::factory()->for($team)->create();

    $this->actingAs($user)
        ->get(route('playground.index', $team))
        ->assertOk()
        ->assertSeeLivewire(PlaygroundIndex::class);
});

php artisan test --compact --filter=projects

6. Component format selection. Livewire 4 supports SFC / MFC / class-based. Use single-file components for page-level screens that are mostly markup, class-based components for anything reused, tested in isolation, or carrying non-trivial state transitions.

7. Pre-PR gate. pint --dirty, php artisan test --compact, Larastan, Rector. The kit ships them configured; run them in that order so formatting churn doesn't pollute the test diff.

8. Extending the kit, not fighting it. When you add a new domain (billing, imports), add a matching skill file under agents/skills/ and a line in AGENTS.md. Future sessions — human or agent — inherit the pattern instead of re-deriving it. That's the actual leverage of this package.

Gotchas and Tips

• It's a snapshot, not a library. There's no semver contract to upgrade against. composer update can move Livewire/Flux under you; commit the lockfile and read release notes before bumping the Livewire/Flux pair. 213 stars means a small community — you will be reading the source.
• Flux Pro is license-gated. The kit references livewire/flux-pro v2. Without credentials configured (private repo auth / license key), Pro components won't resolve. Stick to free-tier components until auth is in place, and don't copy Pro examples into a free-only install.
• ViteException: Unable to locate file in Vite manifest = assets not built. Run bun run build (or keep composer run dev running). This is the single most common "the app is broken" false alarm in this stack.
• Bun vs npm drift. The kit assumes Bun. Mixing lockfiles produces subtly different Tailwind/vite output; pick one and delete the other lockfile.
• Tailwind v4 has no JS config. Theming lives in resources/css/app.css via @theme and @plugin. Editing a tailwind.config.js that doesn't exist is a classic wasted hour.
• Skills don't self-activate everywhere. AGENTS.md is instructions to the agent. Tooling that doesn't read it (or a fresh chat with no context) will happily write Livewire 3 patterns. Paste the relevant skill into context manually when in doubt.
• Livewire 4 ≠ Livewire 3 snippets. Component formats, islands, and reactivity defaults changed. Any tutorial older than the kit is suspect — resolve API questions through search-docs rather than blog posts.
• Team route binding needs scoping. A {team} parameter binds a model, but binding alone doesn't authorize. Always pair mount() authorization with scoped queries; add a test that asserts a non-member gets 403 — this is the bug most likely to reach production.
• Nav convention: no top-level "Teams" item. Team management hangs off the team switcher and team-scoped routes. Adding one breaks the kit's information architecture and reviewers will flag it.
• Pint: run vendor/bin/pint --dirty --format agent, not --test. The kit's workflow expects auto-fix on changed files only; whole-repo formatting buries your diff.
• Don't write throwaway tinker/verification scripts when a test would prove the same thing. The kit's stated rule — tests over scripts — is also the faster path here.
• Don't scaffold docs unprompted. AGENTS.md explicitly restricts documentation files to explicit requests; a stray README-feature.md is noise.
• Sharing URLs: resolve the real scheme/host/port through Boost's get-absolute-url (or php artisan about) before handing a link to anyone — Sail and native artisan serve disagree on ports.
• Debugging reactive weirdness: php artisan pail for server-side, Boost browser-logs for client-side, and check the network payload before assuming an Alpine/Livewire bug.