From ce6c699cc55a6bfdaa36a5058ee1a68c864fa7b3 Mon Sep 17 00:00:00 2001
From: Matt Gros <3311227+mpge@users.noreply.github.com>
Date: Fri, 24 Apr 2026 12:50:44 -0400
Subject: [PATCH] docs(frontend-setup): document window.route() helper
 requirement
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The shared Escalated frontend calls Ziggy's route(name, params) helper
in 77 components. Laravel hosts get it for free; non-Laravel hosts must
ship a compatible shim against their own named-route table, or install
Ziggy directly if it's compatible.

Also mention the safety stub EscalatedPlugin.install() now installs
when no window.route is present — it throws a descriptive error rather
than a bare ReferenceError, but is not a functional replacement.

See escalated-dev/escalated#36 for the plugin-side change.
---
 sections/frontend-setup.md | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/sections/frontend-setup.md b/sections/frontend-setup.md
index 595b5c1..6553453 100644
--- a/sections/frontend-setup.md
+++ b/sections/frontend-setup.md
@@ -51,3 +51,20 @@ createInertiaApp({
   },
 });
 ```
+
+## 4. Provide a `window.route()` helper
+
+The Escalated frontend generates URLs to its own named routes through a global `route(name, params)` helper with the same signature as [Ziggy](https://github.com/tighten/ziggy) — Laravel's named-route URL generator.
+
+- **Laravel hosts:** install Ziggy (`composer require tightenco/ziggy`) and call `route()` is already on `window`. Nothing else to do.
+- **Non-Laravel hosts (Rails, Django, NestJS, Phoenix, Symfony, Adonis, Go, .NET, Spring, WordPress):** you need to ship a compatible shim that speaks Ziggy's API against your host framework's named-route table. At minimum, `route(name)` must return a URL string, and `route(name, params)` must return a URL string with the given params interpolated.
+
+If no `window.route` is installed when `EscalatedPlugin.install()` runs, the plugin installs a stub that throws a descriptive error on first call — this keeps a missing shim from surfacing as a cryptic `ReferenceError` deep inside a component render. You still need to replace the stub with a real helper before the UI is usable.
+
+```js
+// Minimal shim shape
+window.route = function (name, params) {
+  // lookup by `name` in your route table, interpolate `params`, return URL
+}
+```
+