Laravel Ninja Keys Laravel Package

Product Decisions This Supports

• Build vs. buy for the command palette. A keyboard-driven "jump to / do anything" palette is one of the highest perceived-value, lowest-cost UX investments for power users (the Linear/Notion/Raycast pattern). v1.0.0 turns this from a bespoke, per-team chore into an install-and-configure decision: one Blade component (<x-ninja-keys />) or directive, no custom JS bundling, no frontend build-pipeline work required.
• Power-user and admin-tool roadmap bets. The new href() / route() actions, data-ninja-keys-open click triggers, and submenu support let you expose navigation and multi-step action trees without designing new navigation UI. Good fit for internal tools, admin panels, back-office SaaS, and any product where "expert users want to stop clicking."
• Permission-aware UX as a first-class requirement. Gate filtering now also hides sub-actions and nested children of hidden actions — meaning a palette can be shipped broadly without leaking actions a user isn't allowed to run. That converts an "accessibility/security review" blocker into a solved problem, and is the detail that typically decides whether a palette ships at all in enterprise or multi-tenant products.
• Stability signal for the roadmap. First tagged release with a versioned API, pinned upstream ES module, self-hosted assets, Octane-safe per-request scoping, and CSP nonce support. This is the point where the package moves from "spike / prototype only" to "safe to put on the committed roadmap."
• Feature scope decisions this forces. Handlers now receive the action object, onSelected and render-time NinjaKeys::define() callbacks exist, and per-page overrides are component attributes — so PMs can scope per-page palettes (e.g. a different action set on a billing page vs. an inbox) without new engineering architecture.
• Onboarding and discoverability experiments. searchPlaceholder, per-page overrides, and programmatic open triggers are enough to A/B a "press ⌘K" hint, an empty-state prompt, or a contextual palette on a specific workflow — cheap experiments, measurable in feature-adoption and time-to-task.

When to Consider This Package

Adopt when most of the following hold:

• You are on Laravel 12 or 13 and PHP 8.3+. This is a hard floor in v1.0.0 — not a soft recommendation. If you're on Laravel 10/11 or PHP 8.2, this release is not available to you; treat it as a future upgrade dependency rather than an immediate option.
• Your frontend is Blade/Livewire-first. The package's value is that it removes the glue: asset publishing via laravel-assets, Livewire navigate() integration, and wire:navigate hotkey de-duplication. In an Inertia/React/Vue SPA you would get more control (and less indirection) by using ninja-keys or cmdk directly.
• You have a set of discrete, nameable actions — navigate to a record, create an entity, run an admin operation, toggle a setting. This is an action palette. It is not a full-text content search index, and it is not a replacement for site search, Elasticsearch/Meilisearch, or a docs search layer.
• You need permission-scoped actions. If actions must be hidden per role/tenant, the gate-filtering behavior (including nested children) is a real reason to prefer this over hand-rolling.
• You have CSP requirements or want no third-party CDN dependency in production. Self-hosted, version-pinned assets plus nonce support on both scripts is the enterprise checkbox; the jsDelivr fallback is a bootstrap convenience, not something to rely on in production.
• You are on Octane or another long-lived worker runtime. Per-request singleton scoping is now handled.

Look elsewhere or defer when:

• You're upgrading from dev-main. This is effectively a breaking release: config keys use_cdn/asset_path became script/asset_url, hotKeys/searchPlaceholder/noHeader were removed, the publish tag changed to ninja-keys-config, and actions missing id or title now throw InvalidArgumentException instead of silently degrading. Budget a migration pass and an audit of every registered action, not a composer update.
• Mobile-first or consumer products. A ⌘K palette has near-zero value on touch-primary surfaces; the payoff is concentrated in desktop, high-frequency, professional workflows.
• Your team wants full styling control or a non-Lit runtime. The bundled ES module pins Lit 2 and hotkeys-js exactly — good for reproducibility, a constraint if you need to align with a different Lit version in your own bundle.
• You need deep customization of the matching algorithm. Search-input escaping now prevents the upstream regex crash, but matching semantics remain ninja-keys' fuzzy behavior — if ranking quality is a product requirement, you'll be forking or building.

How to Pitch It (Stakeholders)

For executives (one paragraph): A command palette is the cheapest credible "this product is fast" signal we can ship — it's what users associate with Linear, Notion, and Raycast. This package lets us deliver that in days rather than weeks, on top of our existing Laravel stack, with no new frontend framework, no new build pipeline, and no third-party CDN in the critical path. It just hit a stable 1.0: versioned API, self-hosted assets, CSP-compliant script loading, per-role action filtering, and compatibility with our long-running worker setup. The main cost is not engineering — it's a Laravel 12/13 and PHP 8.3 baseline, which should be sequenced against our existing upgrade plan rather than treated as a palette-only decision.

For engineering leads: v1.0.0 closes the reasons we'd have said no. The three upstream bugs that make hand-rolled palettes flaky are fixed in-package: the action.handler is not a function failure (handler was being passed by name), nested-action tree flattening (ninja-keys 1.2.2 silently moved root actions into submenus), and the regex SyntaxError on every keystroke when typing ( or [. wire:navigate no longer double-fires stale hotkeys, and the manager is per-request scoped so Octane is safe. Assets are a single pinned ES module published to public/vendor/ninja-keys with a jsDelivr fallback only until published — no unpkg mixed-Lit resolution risk. CSP nonces are applied to both scripts and there's a php artisan about entry for support triage. The trade-off we're accepting: a Laravel 12/13 + PHP 8.3 floor, and a config surface that renamed use_cdn/asset_path to script/asset_url and dropped hotKeys, searchPlaceholder, and noHeader.

Risks and how to frame them:

• Migration, not adoption. Anyone already on dev-main must treat this as breaking: renamed config keys, new config publish tag (ninja-keys-config), and actions without id or title now throwing instead of failing silently. That last one is arguably a feature — it surfaces broken registrations at render time — but it will page someone on day one if we don't audit.
• No CDN safety net in production. Publish assets in the deploy pipeline and verify public/vendor/ninja-keys ships; the jsDelivr fallback is a stopgap.
• Scope discipline. Position this as an action palette. If stakeholders hear "search," we inherit an expectations gap we can't close with this package.

Effort estimate: hours to a first palette; one to two days for a permission-scoped, per-page action set with tests; the real cost is the framework/PHP baseline upgrade, which should be justified on its own merits.