Spirit Web Twig Bundle Laravel Package

Getting Started

Read this first: it is not a Laravel package. lmc/spirit-web-twig-bundle is a Symfony bundle — its entry point is a Bundle subclass, a DI Extension, and Twig path registration. It has no ServiceProvider, no config/ publish target, and no Blade directives. In a Blade-first Laravel app it will not boot, and pulling in twigbridge to consume a component library adds a second template engine for marginal gain.

So there are two honest on-ramps:

Path A — you already run Twig in Laravel (twigbridge) or are evaluating a Symfony surface.

1. composer require lmc/spirit-web-twig-bundle.
2. Register the bundle — Flex auto-register won't fire in Laravel, so you'll wire the extensions manually via your Twig environment setup.
3. Install the actual design system: npm install @lmc-eu/spirit-web. The bundle ships Twig helpers and markup only — the CSS/JS is external and mandatory.
4. Load Spirit's CSS/JS through Vite (not Encore/AssetMapper — those Symfony conventions won't apply).
5. First use case: render one button and one text field, verify markup and behavior.

Path B — you're Blade-native (the normal Laravel case). Skip the bundle.

1. npm install @lmc-eu/spirit-web.
2. Read the Spirit component reference for the components you need.
3. Port 4–6 representative components (button, input, alert, card) to Blade partials you own.

Where to look first, either way:

• The upstream Spirit Design System docs — that's the real HTML contract; the Twig bundle just emits that markup.
• If you do install the bundle: vendor/lmc/spirit-web-twig-bundle/templates and src/Twig/ are ground truth. The README is thin and often behind.
• composer.json for PHP/Twig version constraints before you commit.

A sane first task: replace one hardcoded <button class="…"> with either the helper (Path A) or a Blade component (Path B), verify visually, then expand.

Implementation Patterns

Wrap, don't scatter. Whatever form you consume, add your own thin layer on top — Blade components (<x-spirit.button variant="primary">) or a Twig macro/{% embed %} wrapper. Templates then call your component, not the raw bundle signature. If the bundle's API shifts (it will — very low activity), you patch one file.

Form rendering is the highest-leverage integration.

• Laravel/Blade: create Blade components for field types (text, checkbox, select) and use them inside your own form partials / @error blocks. This converts a large surface of generic inputs into consistently styled, Spirit-aligned fields without touching controllers.
• Twig: override Symfony form_theme blocks to emit Spirit markup. Start with one field type, confirm, then roll out.

Compose inside layouts. Use the components within your header/nav/alert/modal layouts. Because Spirit components are custom elements, keep slot content in your template and let the element handle interactivity — don't re-implement open/close or keyboard behavior in Twig/Blade.

Asset pipeline. Install and pin @lmc-eu/spirit-web in package.json, import its CSS/JS in your entrypoint, and let Vite hash and cache-bust it. Do not rely on Symfony AssetMapper/Encore assumptions if you're in Laravel — asset resolution is exactly where bundle assumptions leak.

Version discipline. Pin the spirit-web npm version and record which bundle version you're targeting. These version independently and drift silently: your helpers emit class names that a newer/older CSS package no longer styles, with no error.

Reference-implementation tactic. If your estate has a Symfony/Twig surface, adopt the bundle there first and use its rendered output as a parity oracle for your Blade ports.

Gotchas and Tips

• Framework boundary is the whole story. The bundle assumes a Symfony kernel. There's no artisan vendor:publish, and config discovery you read about in Symfony docs doesn't map. Evaluate the underlying @lmc-eu/spirit-web on its own merits instead.
• Nothing renders correctly without the JS. Spirit web components require the front-end JS bundle. Missing JS = unstyled, inert markup that looks like a styling bug but is a missing init layer. Check the JS is loaded before debugging CSS.
• Accessibility regressions on hand-port. If you port to Blade, you can silently drop the ARIA wiring and focus management the JS layer expects. This fails audits, not tests — diff each ported component against the reference markup carefully, especially select/modal/tooltip.
• Version drift is the silent failure mode. Bundle helpers + npm spirit-web are versioned separately. Pin both, and add a visual smoke check per component after any bump.
• You are the maintainer. One star, zero dependents, no SLA. Budget a fork-to-internal-ownership plan: vendor the Twig templates or mirror them into your repo so a stalled upstream doesn't block a PHP/Twig upgrade. Don't put this in the request-rendering path of a customer-facing app you can't fork.
• Test in a scratch project first. composer require into a throwaway app surfaces Symfony polyfill conflicts and any PHP/Twig constraint surprises before they hit your real tree.
• Don't adopt just for the helpers. For a Blade-native team the Twig learning curve buys you markup you could copy from Spirit's docs in an afternoon — negative ROI. Reserve bundle-specific onboarding for teams already fluent in Symfony and Twig.
• Confirm asset delivery. Verify the bundle doesn't expect a Symfony asset convention (AssetMapper/Encore) that Vite in Laravel won't satisfy. Asset path breakage after a Composer/upstream update is a realistic failure.
• Treat as a pilot. Gate broader adoption on an observable upstream release cadence across at least two minor versions, and an explicit product decision that Spirit is your design system.