Blast Laravel Package

Getting Started

Blast wires a Twig-based component library into a Laravel app and exposes those components in Storybook, so the same .twig partial is both rendered by Laravel and previewed in isolation by front-end devs.

1. composer require area17/blast — use ^1.11 if you are on Laravel 12 (see Gotchas).
2. Publish the config and any front-end scaffolding: php artisan vendor:publish --tag=blast (check php artisan vendor:publish for the exact tags this version exposes).
3. Run the package's install/setup command and then npm install && npm run storybook in the generated front-end workspace. Discover the registered commands with php artisan list | grep blast rather than guessing names — they have shifted between minor versions.
4. Look first at config/blast.php. It is the single source of truth for component paths, the story namespace, and (new in 1.11.0) the Storybook version.

First use case: create one component directory (a .twig template plus its co-located story file), render it from a Blade view, and confirm the identical markup appears at localhost:6006. That round-trip is the whole value proposition — if it works once, the rest is convention.

Implementation Patterns

Component-per-directory. Everything lives beside its story. A button/ folder holds button.twig and button.stories.js (or the JSON/PHP story format the package expects). Blast's generators derive stories from the template's own variables, so keep default props defined in one place and let the story consume them.

Laravel renders, Storybook documents. Controllers and Blade pass data down as usual; Blast only owns the template layer. Treat the story file as the canonical fixture — if a component needs data the story can't express, that's usually a sign the component is doing too much.

Pin the Storybook version in config (1.11.0+). Previously the Storybook version was baked into the package's generated package.json. Now you can declare it explicitly. Do this deliberately rather than inheriting the default: it decouples your component library's upgrade cadence from Blast's release cadence, and it stops a composer update from silently bumping Storybook majors.

Storybook as living documentation and CI artifact. Build a static Storybook in CI and publish it alongside the app preview. Because stories are generated from templates, they rot less than hand-written docs. Wire the static build into the same pipeline that lints the Twig so a template change can't merge with a broken story.

Tests against the same fixtures. Where stories are data-driven, reuse the story props as PHPUnit/Pest datasets for rendering assertions. It keeps the demo data honest and catches Twig-side regressions without duplicating fixtures.

Integration tip: for design-system work, keep Blast components free of Laravel-specific Twig extensions (route helpers, csrf_field, auth checks). Components that depend on framework services can't render in Storybook without stubs, which erodes the isolation you set the package up to get.

Gotchas and Tips

Upgrade to 1.11.0 on PHP 8.2+. The dynamic-property deprecation fix (#130) resolves warnings that older versions emitted under PHP 8.2/8.3. If you saw Creation of dynamic property ... is deprecated noise in logs or test output, that's this — upgrading clears it. It is a bugfix, not a breaking change, so it's a safe patch-level bump within ^1.10.

Laravel 12 requires 1.11.0 or later. The Laravel 12 compatibility work (#138) landed here. Constrain to ^1.11 explicitly if you're upgrading the framework, otherwise a stale composer.lock can leave you on a version whose service provider and dependency constraints were never tested against Laravel 12.

Storybook version drift is the sharpest edge. Now that the version is configurable, a mismatch between the pinned version and the installed node_modules (or between Storybook's major and your Node runtime — Storybook 8 needs Node 18+) produces confusing build failures that look like Blast bugs. Pin the version in config, pin Node in .nvmrc/engines, and rebuild node_modules after changing it.

Config and view caches. Blast resolves paths and namespaces from config at boot. After editing config/blast.php, run php artisan config:clear (and view:clear when templates move) — otherwise a moved component directory appears "missing" with no error explaining why.

Twig ≠ Blade. Laravel helpers, @directives, and Blade's automatic escaping semantics do not carry over. Escaping defaults and |raw usage differ; audit anything user-supplied that you render through a Twig partial.

Debugging order when a story won't render: (1) is the component discoverable from the configured path, (2) does the template parse in isolation (twig lint), (3) does the story file export the props the template declares, (4) is the Storybook version the one you pinned. Most failures land in step 2 or 3.

Extension points: published config and front-end assets are the intended override surface; prefer overriding generated scaffolding there over editing vendor/ (which composer update will overwrite). Custom story templates are the clean way to adapt generation to your own conventions.