Ui Laravel Package

Getting Started

1. composer require storyfeed/ui (this release aligns with Render Payload v1 at 1.0 and Storyfeed core 0.21).
2. Pick a kit — Blade, Vue or React — and follow the README's kit install. The install boils down to publishing/copying the kit's components and adding the matching Tailwind @source line(s) so the kit's classes are scanned.
3. Run php artisan boost:install and check resources/boost. It ships a guideline plus a storyfeed-ui skill, which is the fastest way to get an agent (or a new teammate) writing correct kit code — it documents the kit install, the @source lines (including the Vite-alias-to-vendor case), @theme token retuning, the feed props, the FEED_* provides, and the FeedMedia renderer path.
4. First use case: drop a feed component into a page with a payload and let the defaults do the work. Then tune image-size, turn on the viewer or rails, and only after that start replacing body renderers.

Where to look first, in order: the Boost guideline (it's the shortest accurate summary of the public API), the README's image-renderer section, then the kit source for the component you're overriding.

Implementation Patterns

Install the kit, then own the Tailwind wiring. Two supported shapes: a copied kit (scan the copied path with @source) and a Vite alias into vendor/storyfeed/ui. In the alias case you must also scan vendor/storyfeed/ui/resources/js — the release notes call this out explicitly because it's the number one cause of "the feed renders unstyled."

Configure through the feed props first. image-size, the viewer, rails and dense child rows cover most product asks without touching a renderer. Dense child rows in particular removes the need to hand-roll a compact comment list.

Use the body renderers as-is for Code and Callout. Code renders escaped source in <pre><code> inside Typography's prose, with an optional title and a language-<name> class. Callout frames escaped content with an optional title and light/dark palettes for note, info, success, warning and danger. In Blade, Vue and React alike. That means: no syntax highlighter is bundled — you supply one and key off language-<name>.

Replace only the body renderers you need, and route images through FeedMedia. A custom Image renderer should pass its body as payload to FeedMedia (Blade: <x-storyfeed::media>) rather than emitting its own <img>. That reuses the feed's image-size limits and the body's own override, including full. If you skip it, your custom renderer silently opts out of the sizing contract the rest of the feed follows.

Format headline text through the seam, not by string-patching. Register once in a service provider for Blade:

app(\Storyfeed\Ui\Support\HeadlineText::class)->register(fn (string $text) => ...);

Vue uses the FEED_HEADLINE_TEXT provide ((text: string) => VNodeChild); React passes headlineText to FeedProvider ((text: string) => ReactNode). Each kit also ships an opt-in inlineCode formatter that turns paired single backticks into a Tailwind-styled <code> — useful as a template for your own mention/link/hashtag formatter.

Treat provides as global config, props as per-feed config. FEED_* in Vue and FeedProvider in React are the right place for app-wide behaviour (headline formatting, shared media defaults). Per-feed overrides stay on the component.

Let the Boost skill drive scaffolding. When asking an agent to add a feed screen, point it at the storyfeed-ui skill first. The package ships a test that fails if the guideline or skill names a component, prop, export, provide key, class or path the package doesn't ship — so the guidance is a reliable contract, not prose.

Gotchas and Tips

• @source is the top failure mode. Both the copied-kit path and the Vite alias path need explicit @source lines, and the alias case also needs vendor/storyfeed/ui/resources/js. Missing either produces a feed that renders structurally but looks broken.
• Blade headline callbacks return trusted HTML. You must escape the text yourself. Vue and React return nodes, so escaping is handled by the framework — the risk profile is not symmetric across kits.
• The headline seam is narrower than it looks. It draws template text and the pre-rendered headline fallback only. Entity names, lists, counts and "You" are never passed through it. If a product ask is "style the like count," the seam is the wrong tool.
• Count handling depends on core 0.21. Blade delegates count-token exclusion and count pluralisation to Storyfeed core's headline text API. On an older core, headlines stay plain rather than erroring — a quiet degradation worth pinning in composer.json.
• Unknown Callout intents fall back to note. Safe, but silent. Validate intent strings at your payload boundary if authors can type them.
• Media crop behaviour is intentionally asymmetric. Media frames shrink to the whole picture (no muted box beyond it) in all three kits, while fixed icon and sample tiles keep their crop. Don't "fix" the difference — it's the design.
• language-<name> is a class, not a highlighter. Wire it to Shiki/Prism/highlight.js if you want colour; otherwise Code bodies render as plain escaped text in a <pre>.
• inlineCode parses nothing else. Unmatched backticks stay literal, and no other Markdown is interpreted. If you need bold/links, write your own formatter on the seam rather than reaching for a Markdown parser.
• Retune tokens via @theme, not overrides. The guideline documents the token surface; fighting it with utility overrides makes future kit upgrades painful.
• No breaking changes in this release. The upgrade path from v0.9.8 is additive, but re-check your Tailwind scan config and, if you use an agent, re-run boost:install so the skill matches v0.10.0's API.