Kinetix Laravel Package

Getting Started

Kinetix is a Laravel + Vue package whose documented surface is narrower than its "Hybrid-Driven Framework" tagline: three Vue components (<KinetixAccessibilityPanel>, <KinetixAccessibilityMenu>, <KinetixModeToggle>) plus best-effort server persistence of per-user preferences. Budget your first hour for reading the source in vendor/happones/kinetix before you install it anywhere real — with 2 stars and no dependents, the source is the documentation.

Minimal path, run through Sail:

vendor/bin/sail composer require happones/kinetix
vendor/bin/sail artisan vendor:publish --provider="Happones\\Kinetix\\KinetixServiceProvider"
vendor/bin/sail npm run dev

Then, in order:

1. Confirm what you actually installed. Check composer show happones/kinetix for the version, look for src/, resources/js/, and any tailwind preset or CSS file. If it ships a tailwind.config.js preset, stop — you're on Tailwind 4 (CSS-first, @custom-variant dark) and that preset will not apply.
2. Look for the Vue entry point. Whether you import from the package path directly, from a Vite alias, or from a published resources/js/vendor/kinetix folder determines everything downstream. Register it in vite.config.js the same way the package README or source suggests.
3. First real use case: the mode toggle in your app layout. Drop <KinetixModeToggle /> into resources/js/layouts/AppLayout.vue (or your authenticated layout), then open the app and toggle Light/Dark/System. If nothing changes, your Tailwind 4 dark variant isn't wired to the class the package writes — that's the whole ballgame, fix it before touching the a11y panel.
4. Second use case: <KinetixAccessibilityMenu /> on the Fortify login page and <KinetixAccessibilityPanel /> behind a settings route. Those three placements cover the documented capability.

Do not adopt the "framework" framing. There is no routing, navigation, or state layer worth surrendering to this package, and your stack already has Inertia v3, Wayfinder, Fortify, and Reverb as the sources of truth.

Implementation Patterns

Wrap every component before you use it. Create resources/js/components/kinetix/ with thin local wrappers:

<!-- resources/js/components/kinetix/ThemeToggle.vue -->
<script setup lang="ts">
import { KinetixModeToggle } from '...'
</script>
<template>
  <KinetixModeToggle />
</template>

Call sites import your wrapper. When the package breaks on a Tailwind 4 upgrade (it will), or you fork it, you edit one file, not forty pages. This is the single highest-leverage pattern for a package at this adoption level.

Layout-level placement, not page-level. Theme and preference state is orthogonal to Inertia page props. Mount the toggle once in AppLayout.vue and the guest menu once in AuthLayout.vue / the login view. Keep it out of resources/js/pages/* so page components stay presentational and testable.

Persistence is your work, not the package's. Expect to add:

• a migration for a preferences column (JSON on users, or a user_preferences side table if you anticipate growth),
• a typed FormRequest with validation and authorization,
• a PATCH /preferences route behind auth for the authenticated path,
• a separate, explicitly rate-limited, CSRF-protected guest endpoint if the package's guest persistence needs server backing.

Use vendor/bin/sail artisan route:list --except-vendor when auditing routes — vendor routes will otherwise clutter your output and Wayfinder will generate functions for them.

Own the hydration path. The package's client-side components will read stored preferences; your job is that <html class="dark"> is already correct before hydration. Do this in the root Blade template with a tiny inline script reading a cookie (never localStorage alone — the server can't see it):

<script>
  if (localStorage.theme === 'dark' || (!('theme' in localStorage) && matchMedia('(prefers-color-scheme: dark)').matches)) {
    document.documentElement.classList.add('dark')
  }
</script>

Then treat the Vue component as a controller for that state, not the source of truth.

Guest → authenticated promotion. Best-effort guest persistence means: store in cookie/localStorage while anonymous, then on login POST the stored values once and clear the client copy. Write a Pest feature test asserting the promotion happens exactly once and that a guest write cannot forge a user ID.

Pin hard. "happones/kinetix": "1.0.3" — exact version, no caret. If the maintainer force-pushes or deletes the repo, add a repositories VCS entry pinned to a commit SHA, or vendor the components outright. At 0 dependents, upstream breakage is a build failure on your Monday morning.

Code-split the panel. The accessibility panel is settings-page furniture; it should not be in the login bundle. Dynamic import() inside your wrapper's <script setup> keeps it out of the critical path.

Gotchas and Tips

• Tailwind 4 dark mode is the #1 failure mode. Most theming packages assume darkMode: 'class' in tailwind.config.js. Tailwind 4 is CSS-first. Verify the package toggles a class your @custom-variant dark (&:where(.dark, .dark *)) actually responds to. If it writes data-theme="dark", you need your own variant — not a package bug, an integration gap.
• Flash of incorrect theme under Inertia v3 SSR. Inertia v3 SSR runs automatically via @inertiajs/vite. A component that reads localStorage during render produces hydration mismatch warnings, not just a visual flash. Assert browser-logs is clean after a hard reload on a deep link in dark mode.
• Guest persistence is a trust boundary. "Best-effort, unauthenticated write" is one bad afternoon away from being an unauthenticated spam endpoint. Rate-limit it (throttle:preferences), keep CSRF on, and validate with an enum — never store arbitrary JSON from an anonymous request.
• Verify Inertia v3 compatibility explicitly. Axios was removed in Inertia v3; Inertia::lazy() / LazyProp are gone. If the package's JS uses axios directly or the PHP side returns lazy props, it predates your stack. Grep vendor/happones/kinetix for both before merging.
• route:list --except-vendor and --only-vendor are your friends; Wayfinder generating typed functions for vendor routes is harmless but noisy in diffs.
• A preferences panel is not accessibility compliance. WCAG 2.2 AA / EAA conformance is an audit artifact. Nobody signs off because you adopted a two-star toggle. Keep the audit line item in the budget and say so out loud in planning.
• Debugging strategy: the package is small — dd() inside its service provider, console.log inside its components, and read the compiled output in public/build. Don't hunt for docs; there aren't any.
• Extension points are whatever the source exposes. Config publishing is advertised; check config/kinetix.php for the actual knobs (storage key, cookie name, default mode, component prefix). Bind overrides in a KinetixServiceProvider extension in your own AppServiceProvider rather than editing vendor files, so composer update doesn't eat your changes.
• Assume you're the maintainer. Plan the fork: one folder, one wrapper layer, a Pest test proving persistence round-trips and no-flash behaviour. If that test suite passes after a version bump, you're safe; if it fails, you vendor and move on.
• Get approval before adding the dependency. Your project rules require it, and the justification here is narrow and honest: the a11y panel is the only piece with meaningful build cost. The mode toggle is an afternoon of in-house work, and you may find that building both is cheaper than owning an unmaintained dependency in the UI layer.