Flowforge Laravel Package

Getting Started

Flowforge is a Laravel Kanban package with two rendering modes: Classic and Modern. v4.3.0 only touches Modern — Classic boards are byte-for-byte unchanged, so the upgrade path depends entirely on which mode your boards use.

First steps on a fresh install:

1. Require the package and run the install/publish commands from its service provider (config + migrations + assets). Publish assets as well as config — the Modern board's JS is versioned with the package and stale published assets are the single most common "the new features don't appear" cause.
2. Open config/flowforge.php first. That's where board defaults, asset/route registration and mode selection live. Read it before writing any board class.
3. Implement the card contract on your model (title accessor, lane/status source, ordering column) and expose a board class that returns the card query plus the list of lanes.
4. Start with one read-mostly board (e.g. a project's tasks) before wiring drag persistence. Drag ordering writes back to your ordering column, so confirm that column exists and is unique-scoped per lane before your first drag.

First use case to aim for: a single board page for one aggregate (project, sprint, pipeline), Classic mode, drag-and-drop persisting to an order column. Once that renders, flip the same board to Modern to pick up grouping and collapsible lanes.

Implementation Patterns

Pick the mode per board, not globally. Since Classic is unchanged in this release, put Modern on your highest-traffic boards where the new perf and lane UX matter, and leave heavily customised boards on Classic. This gives you a per-board rollback if something regresses.

Replace custom swimlane code with "Group by". Modern lanes now ship a group-by menu plus sticky lane labels and collapsible lanes. If you previously built your own grouped views by issuing multiple board instances or post-processing the card query, delete that and drive grouping through the board definition instead — you get sticky headers and collapse for free, and one board page instead of N.

Stop shipping card payloads to the browser. The headline change is real: a 125-card flat board dropped 2.6 MB → 1.0 MB because per-card records are no longer embedded in the HTML. The pattern this enables: render cards server-side as the package does, and when a user opens a card action, fetch the detail over Livewire/a small endpoint rather than reading inlined JSON. If you were relying on embedded records to avoid a round-trip, this is the one place you'll feel the change — the fix is an on-demand fetch, not a workaround.

Keep your Alpine state owned by you. Write x-data on your own wrapper and talk to the board through $wire, Livewire events, or the package's public props. Never treat the board component's internal $data as an API — this release proves the point.

Eager-load what your card view renders. Payload got smaller, not zero. Cards still render N times; any relationship touched in the card partial must be eager-loaded in the board query or you've traded a big HTML payload for an N+1.

Test the board as a Livewire component. Assert the rendered board contains the expected card titles, then fire the drag/order persist path and assert your ordering column. This catches both query regressions and the click/drag behaviour change below.

Gotchas and Tips

• $data.state is gone on Modern boards. If your Alpine code read it, it silently loses its value — no deprecation, because it was never part of the contract. Grep your Blade views for $data and move that state into your own x-data before upgrading. This is the only breaking-ish change in v4.3.0 and it is scoped strictly to Modern.
• Card records are no longer in the HTML. Anything scraping inlined JSON or per-card data attributes will now be empty. The perf win and this breakage are the same change; audit custom JS that inspected the DOM for card data.
• The click threshold changed. A click that drifts a few pixels on a Modern card now opens the card action instead of starting a drag. In practice: browser/Dusk tests that simulate a slightly wobbly click may now pop a modal or navigate, and users who previously "failed to drag" will now trigger actions. Verify your card click handler is idempotent and safe to fire on small movements.
• Classic boards are untouched. Safe upgrade if every board is Classic. If you mix modes, remember behaviour now differs between them — document which boards are Modern so support doesn't chase ghosts.
• Republish assets after composer update. New group-by menu, sticky labels and collapse are UI-layer; if the board HTML references assets you haven't republished (or your build cached them), the features appear broken rather than missing. Clear view/asset caches too.
• Collapse and group state is client-side. Don't assume it's persisted server-side or that you can read it from PHP; if you need "remember my collapsed lanes", persist it yourself (localStorage or a user preference).
• Stable keys matter more now. Collapsing/regrouping re-renders lanes; give cards stable wire:key values or you'll see state bleed between cards after a group-by switch.
• Extension points: publish the board views to override lane and card partials rather than editing vendor files, and keep query scoping (lane filters, ordering, eager loads) in your board class — that's the supported seam and the one place a package upgrade is least likely to break you.