Statamic Flow Canvas Laravel Package

Getting Started

1. composer require the package, then publish its assets and config: php artisan vendor:publish --tag=<package>-config and --tag=<package>-assets (check the provider's publishes() for exact tags).
2. Open the published config first — it controls asset paths, default node/edge options, and any route or middleware registration. This is where you should look before touching Blade.
3. Add the package's CSS/JS entry to vite.config.js (or import the published bundle in resources/js/app.js). As of v1.6.1 the seven core components ship plain CSS with fc- classes and scoped <style> blocks, so you no longer need to guarantee Tailwind scans the package for them — but the remaining components still use Tailwind utilities, so keep the package path in your content globs for now.
4. First use case: render a minimal editor in a Blade view — Canvas wrapping NodeLibrary, ControlBar, and PropertiesSection, with a persisted graph passed in as JSON from an Eloquent model. Confirm the layout renders with your normal npm run build and no extra safelist entries.
5. If you use dark mode, confirm your root element carries a .dark class; the new styles key off :global(.dark), not a media query.

Implementation Patterns

• Composition over configuration. Treat the components as a layered editor: Canvas is the surface, NodeLibrary the palette, AdderNode/InsertableEdge the interaction affordances, ControlBar the toolbar, and PropertiesSection the inspector. Wire them through the package's event/props contract rather than reaching into the DOM.
• Graph persistence loop. Serialize node/edge state on change, POST to a Laravel controller, store as JSON (or normalized tables if you need querying), and rehydrate the Canvas on page load. This is the pattern most day-to-day work converges on.
• Theming via CSS variables. Since v1.6.1 colours come from CSS variables rather than hex. Define/override those variables in your app stylesheet (e.g. scoped to .dark and :root) instead of writing .fc-node-card { background: #fff } overrides. This survives package upgrades far better.
• Layout wrapping. Put the editor in a flex/grid shell you own. Don't rely on the package's internal layout classes for page chrome; the fc- classes are for component internals.
• Livewire/Alpine integration. Dispatch change events to Livewire actions and let Alpine handle transient UI state. Keep the graph payload small and debounce persistence.
• Asset splitting. Lazy-load the editor bundle on the routes that need it (import() in Vite); it's a heavy interactive surface and rarely needed on every page.
• Testing. Mirror the package's own tests/js/plain-css.test.js guard with a smoke test that mounts the editor and asserts .fc- classes are present, so a future asset-publish mistake fails CI rather than production.

Gotchas and Tips

• v1.6.1 is a styling-only release, but it can still break your selectors. If you were targeting internals with Tailwind utility selectors (.flex, .bg-white, @apply on package markup), those seven components no longer carry them. Target the new .fc- classes or the CSS variables instead.
• Dark mode is class-based now. :global(.dark) means dark styles only activate under a .dark ancestor. If your app uses prefers-color-scheme without toggling a class, those components will stay light. Add the class strategy or override the variables yourself.
• Scoped styles block deep overrides. The <style> blocks are scoped, so parent selectors won't cascade in. Use :deep() or, preferably, override the CSS variables the components read.
• Half-migrated Tailwind. Utilities not on the seven-component list are unchanged, so you still need the package in your Tailwind content globs (or a safelist). Removing it prematurely will reintroduce the exact "missing layout" bug this release fixed — for the remaining components.
• Republish assets after upgrading. vendor:publish --force (or your asset pipeline) plus a fresh npm run build and php artisan view:clear. Stale compiled CSS is the most common cause of "the fix didn't apply".
• Hardcoded hex overrides are now debt. Any custom CSS setting colours with hex on these components will fight the variable-driven styles. Migrate to variable overrides.
• Extension point: add your own .fc--prefixed classes alongside the package's, keeping specificity low, so future releases that adjust internal values don't collide with yours.