@flareapp/inertia 2.8.0

package/README.md

@@ -0,0 +1,139 @@
+# @flareapp/inertia
+
+Performance tracing for [Inertia.js](https://inertiajs.com) apps, reporting to
+[flareapp.io](https://flareapp.io).
+
+Every Inertia visit opens a `browser_navigation` span named after the page component, so navigations show up
+in Flare's performance monitoring the same way a server request does. Works with every Inertia adapter: the
+router is passed in, so the Vue, React and Svelte adapters all use the identical call.
+
+## Installation
+
+```bash
+npm install @flareapp/inertia
+```
+
+`@flareapp/js` is a peer dependency and must be installed and initialized separately.
+
+## Usage
+
+Call `traceInertiaRouter` once at boot, **before** `createInertiaApp` runs.
+
+Vue:
+
+```js
+import { createInertiaApp, router } from '@inertiajs/vue3';
+import { flare } from '@flareapp/js';
+import { traceInertiaRouter } from '@flareapp/inertia';
+import { createApp, h } from 'vue';
+
+flare.configure({ enableTracing: true, tracesSampleRate: 1 });
+flare.light('YOUR_FLARE_API_KEY');
+
+traceInertiaRouter(router);
+
+createInertiaApp({
+    resolve: (name) => {
+        const pages = import.meta.glob('./Pages/**/*.vue');
+        return pages[`./Pages/${name}.vue`]();
+    },
+    setup({ el, App, props, plugin }) {
+        createApp({ render: () => h(App, props) })
+            .use(plugin)
+            .mount(el);
+    },
+});
+```
+
+React, identical apart from the import:
+
+```jsx
+import { createInertiaApp, router } from '@inertiajs/react';
+import { flare } from '@flareapp/js';
+import { traceInertiaRouter } from '@flareapp/inertia';
+import { createRoot } from 'react-dom/client';
+
+flare.configure({ enableTracing: true, tracesSampleRate: 1 });
+flare.light('YOUR_FLARE_API_KEY');
+
+traceInertiaRouter(router);
+
+createInertiaApp({
+    resolve: (name) => {
+        const pages = import.meta.glob('./Pages/**/*.jsx', { eager: true });
+        return pages[`./Pages/${name}.jsx`];
+    },
+    setup({ el, App, props }) {
+        createRoot(el).render(<App {...props} />);
+    },
+});
+```
+
+## Why the call has to come first
+
+Inertia fires a `navigate` event for the initial page load. That event is how the integration learns the name
+of the page the browser landed on. Calling `traceInertiaRouter` after Inertia has booted misses it, and the
+first back/forward step is then mistaken for the initial load.
+
+## Span naming
+
+Navigation spans are named after the page component from Inertia's page object, for example `Products/Show`.
+That keeps names low-cardinality so Flare can aggregate them, unlike the raw URL `/products/42`. When a
+response carries no component name, the URL path is used instead.
+
+## What does not get a navigation span
+
+Inertia sends a request for plenty of things that do not move you to another page. None of these open a
+navigation span:
+
+- prefetches, including `<Link prefetch>` on hover, mount or viewport
+- deferred props loaded after the page arrives
+- polling, via `usePoll` or `router.poll`
+- infinite scroll fetching the next page
+- any other `router.reload()`
+
+The requests themselves are still traced. Inertia sends them over XHR, which Flare instruments, so each one
+shows up as a child span under whichever page it belongs to, with its real timing.
+
+An asynchronous visit that does take you to a different page, such as
+`router.visit('/cart', { async: true })`, is a navigation and does open a span.
+
+Clicking a second link before the first page arrives is also one navigation, not two. The span runs from the
+first click to the page that actually loaded, which is what the person waiting for it experienced.
+
+## Prefetched navigations report near-zero duration
+
+A click on a `<Link prefetch>` that is served from Inertia's prefetch cache is currently reported as an instant
+navigation. Inertia fires neither `start` nor `finish` for it, only `navigate` and `success`, so the integration
+cannot tell it apart from a back/forward step and opens and settles the span in the same tick. The navigation
+still shows up as a `browser_navigation` span, but its duration should not be read as the time the user actually
+waited. `<Link prefetch>` defaults to hover as its trigger, so this is a common path, not an edge case.
+
+## Cleanup
+
+`traceInertiaRouter` returns a function that removes its listeners:
+
+```js
+const stopTracing = traceInertiaRouter(router);
+
+stopTracing();
+```
+
+Calling `traceInertiaRouter` twice on the same router replaces the first instrumentation rather than stacking
+a second set of listeners, so Vite HMR does not accumulate them.
+
+## Requirements
+
+- `@flareapp/js` with `enableTracing: true`
+- Inertia v2 (any adapter). v1 works, but it has no `prefetch` or `async` visit flags, so background work
+  driven by `router.reload()` (polling, deferred props, infinite scroll) cannot be told apart from a real
+  navigation, and each tick reports its own `browser_navigation` span.
+
+## Documentation
+
+Full documentation on performance tracing is available at
+[flareapp.io/docs/javascript/general/installation](https://flareapp.io/docs/javascript/general/installation).
+
+## License
+
+The MIT License (MIT). Please see [License File](../../LICENSE.md) for more information.

package/dist/index.cjs

@@ -0,0 +1,128 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+let _flareapp_js_browser = require("@flareapp/js/browser");
+
+//#region src/traceInertiaRouter.ts
+/** Resolve a router-reported location (a `URL` on visits, a relative string on pages) to a full href
+*  plus its path. Both are undefined outside a browser or for an unparseable value. */
+function locationOf(raw) {
+	if (raw == null) return {};
+	const url = (0, _flareapp_js_browser.absoluteUrl)(String(raw));
+	if (!url) return {};
+	return {
+		href: url.href,
+		path: url.pathname
+	};
+}
+/** Background work fires the same `start` and `finish` a real visit does, so opening a root for one both
+*  invents a navigation and ends the root that was live. */
+function isBackgroundVisit(visit) {
+	if (!visit) return false;
+	if (visit.prefetch) return true;
+	const { path } = locationOf(visit.url);
+	return !!visit.async && path !== void 0 && path === (0, _flareapp_js_browser.currentPath)();
+}
+/** `component` ('Products/Show') is Inertia's route identifier, and there is a small fixed set of them,
+*  so reports group by it the way the other integrations' route templates do. */
+function routeNameFor(page) {
+	const { href, path } = locationOf(page?.url);
+	return (0, _flareapp_js_browser.routeName)(() => page?.component, path ?? (0, _flareapp_js_browser.currentPath)(), href);
+}
+/**
+* Trace an Inertia router: open a held `browser_navigation` root per visit, settled once the page
+* arrives. Call it before Inertia boots, so the initial `navigate` is seen. Returns a cleanup that
+* removes the listeners and unregisters. The runtime guard protects untyped JavaScript callers.
+*/
+function traceInertiaRouter(router) {
+	if (!isInertiaRouter(router)) return () => {};
+	return (0, _flareapp_js_browser.instrumentOnce)(router, (track) => install(router, track));
+}
+function isInertiaRouter(router) {
+	return !!router && typeof router.on === "function";
+}
+function install(router, track) {
+	const nav = (0, _flareapp_js_browser.registerNavigationSource)();
+	track(() => nav.unregister());
+	let inFlight = false;
+	let inFlightPath;
+	let sawInitial = false;
+	let lastComponent;
+	const nameFor = (page) => {
+		const route = routeNameFor(page);
+		if (route.source === "route") lastComponent = {
+			path: locationOf(page?.url).path,
+			name: route.name
+		};
+		return route;
+	};
+	const settle = (page) => {
+		inFlight = false;
+		inFlightPath = void 0;
+		nav.settleNavigation(nameFor(page));
+	};
+	const on = (event, handler) => track(router.on(event, (0, _flareapp_js_browser.insulate)(handler)));
+	on("start", (event) => {
+		const visit = event?.detail?.visit;
+		if (isBackgroundVisit(visit)) return;
+		const { href, path } = locationOf(visit?.url);
+		if (inFlight) {
+			inFlightPath = path;
+			nav.setActiveRouteName({
+				name: path ?? (0, _flareapp_js_browser.currentPath)(),
+				source: "url",
+				url: href
+			});
+			return;
+		}
+		sawInitial = true;
+		inFlight = true;
+		inFlightPath = path;
+		nav.startNavigation({
+			path,
+			url: href,
+			hold: true
+		});
+	});
+	on("navigate", (event) => {
+		const page = event?.detail?.page;
+		if (inFlight) {
+			settle(page);
+			return;
+		}
+		if (!sawInitial) {
+			sawInitial = true;
+			nav.setActiveRouteName(nameFor(page));
+			return;
+		}
+		const { href, path } = locationOf(page?.url);
+		nav.startNavigation({
+			path,
+			url: href
+		});
+		settle(page);
+	});
+	on("success", (event) => {
+		if (!inFlight) return;
+		const page = event?.detail?.page;
+		if (locationOf(page?.url).path !== inFlightPath) return;
+		settle(page);
+	});
+	/** Whether `visit` is the one that opened the currently held root, i.e. `finish` may settle it. */
+	const belongsToThisNavigation = (visit) => {
+		if (isBackgroundVisit(visit)) return false;
+		if (visit && locationOf(visit.url).path !== inFlightPath) return false;
+		if (visit?.interrupted) return false;
+		return true;
+	};
+	on("finish", (event) => {
+		if (!inFlight) return;
+		if (!belongsToThisNavigation(event?.detail?.visit)) return;
+		inFlight = false;
+		inFlightPath = void 0;
+		const { href, path } = locationOf((0, _flareapp_js_browser.currentPath)());
+		const knownComponentName = lastComponent?.path === path ? lastComponent?.name : void 0;
+		nav.settleNavigation((0, _flareapp_js_browser.routeName)(() => knownComponentName, path ?? (0, _flareapp_js_browser.currentPath)(), href));
+	});
+}
+
+//#endregion
+exports.traceInertiaRouter = traceInertiaRouter;

package/dist/index.d.cts

@@ -0,0 +1,38 @@
+//#region src/vendor/inertiaTypes.d.ts
+/** The page object Inertia ships with every response. `component` is the page component name
+ *  ('Products/Show'), `url` a relative string ('/products/42'). */
+type InertiaPageLike = {
+  component?: string;
+  url?: string;
+};
+/** `visit.url` is a `URL` instance in @inertiajs/core. A string is tolerated for older versions.
+ *  `prefetch` and `async` are how a background visit gives itself away: see `isBackgroundVisit`.
+ *  `interrupted` and `cancelled` are set on the visit `finish` carries, and only the first of the two
+ *  means a successor visit is already on its way. */
+type InertiaVisitLike = {
+  url?: URL | string;
+  prefetch?: boolean;
+  async?: boolean;
+  interrupted?: boolean;
+  cancelled?: boolean;
+};
+type InertiaEventLike = {
+  detail?: {
+    visit?: InertiaVisitLike;
+    page?: InertiaPageLike;
+  };
+};
+type InertiaEventName = 'start' | 'navigate' | 'success' | 'finish';
+type InertiaRouterLike = {
+  on(event: InertiaEventName, callback: (event: InertiaEventLike) => void): () => void;
+};
+//#endregion
+//#region src/traceInertiaRouter.d.ts
+/**
+ * Trace an Inertia router: open a held `browser_navigation` root per visit, settled once the page
+ * arrives. Call it before Inertia boots, so the initial `navigate` is seen. Returns a cleanup that
+ * removes the listeners and unregisters. The runtime guard protects untyped JavaScript callers.
+ */
+declare function traceInertiaRouter(router: InertiaRouterLike): () => void;
+//#endregion
+export { type InertiaEventLike, type InertiaEventName, type InertiaPageLike, type InertiaRouterLike, type InertiaVisitLike, traceInertiaRouter };

package/dist/index.d.mts

@@ -0,0 +1,38 @@
+//#region src/vendor/inertiaTypes.d.ts
+/** The page object Inertia ships with every response. `component` is the page component name
+ *  ('Products/Show'), `url` a relative string ('/products/42'). */
+type InertiaPageLike = {
+  component?: string;
+  url?: string;
+};
+/** `visit.url` is a `URL` instance in @inertiajs/core. A string is tolerated for older versions.
+ *  `prefetch` and `async` are how a background visit gives itself away: see `isBackgroundVisit`.
+ *  `interrupted` and `cancelled` are set on the visit `finish` carries, and only the first of the two
+ *  means a successor visit is already on its way. */
+type InertiaVisitLike = {
+  url?: URL | string;
+  prefetch?: boolean;
+  async?: boolean;
+  interrupted?: boolean;
+  cancelled?: boolean;
+};
+type InertiaEventLike = {
+  detail?: {
+    visit?: InertiaVisitLike;
+    page?: InertiaPageLike;
+  };
+};
+type InertiaEventName = 'start' | 'navigate' | 'success' | 'finish';
+type InertiaRouterLike = {
+  on(event: InertiaEventName, callback: (event: InertiaEventLike) => void): () => void;
+};
+//#endregion
+//#region src/traceInertiaRouter.d.ts
+/**
+ * Trace an Inertia router: open a held `browser_navigation` root per visit, settled once the page
+ * arrives. Call it before Inertia boots, so the initial `navigate` is seen. Returns a cleanup that
+ * removes the listeners and unregisters. The runtime guard protects untyped JavaScript callers.
+ */
+declare function traceInertiaRouter(router: InertiaRouterLike): () => void;
+//#endregion
+export { type InertiaEventLike, type InertiaEventName, type InertiaPageLike, type InertiaRouterLike, type InertiaVisitLike, traceInertiaRouter };

package/dist/index.mjs

@@ -0,0 +1,127 @@
+import { absoluteUrl, currentPath, instrumentOnce, insulate, registerNavigationSource, routeName } from "@flareapp/js/browser";
+
+//#region src/traceInertiaRouter.ts
+/** Resolve a router-reported location (a `URL` on visits, a relative string on pages) to a full href
+*  plus its path. Both are undefined outside a browser or for an unparseable value. */
+function locationOf(raw) {
+	if (raw == null) return {};
+	const url = absoluteUrl(String(raw));
+	if (!url) return {};
+	return {
+		href: url.href,
+		path: url.pathname
+	};
+}
+/** Background work fires the same `start` and `finish` a real visit does, so opening a root for one both
+*  invents a navigation and ends the root that was live. */
+function isBackgroundVisit(visit) {
+	if (!visit) return false;
+	if (visit.prefetch) return true;
+	const { path } = locationOf(visit.url);
+	return !!visit.async && path !== void 0 && path === currentPath();
+}
+/** `component` ('Products/Show') is Inertia's route identifier, and there is a small fixed set of them,
+*  so reports group by it the way the other integrations' route templates do. */
+function routeNameFor(page) {
+	const { href, path } = locationOf(page?.url);
+	return routeName(() => page?.component, path ?? currentPath(), href);
+}
+/**
+* Trace an Inertia router: open a held `browser_navigation` root per visit, settled once the page
+* arrives. Call it before Inertia boots, so the initial `navigate` is seen. Returns a cleanup that
+* removes the listeners and unregisters. The runtime guard protects untyped JavaScript callers.
+*/
+function traceInertiaRouter(router) {
+	if (!isInertiaRouter(router)) return () => {};
+	return instrumentOnce(router, (track) => install(router, track));
+}
+function isInertiaRouter(router) {
+	return !!router && typeof router.on === "function";
+}
+function install(router, track) {
+	const nav = registerNavigationSource();
+	track(() => nav.unregister());
+	let inFlight = false;
+	let inFlightPath;
+	let sawInitial = false;
+	let lastComponent;
+	const nameFor = (page) => {
+		const route = routeNameFor(page);
+		if (route.source === "route") lastComponent = {
+			path: locationOf(page?.url).path,
+			name: route.name
+		};
+		return route;
+	};
+	const settle = (page) => {
+		inFlight = false;
+		inFlightPath = void 0;
+		nav.settleNavigation(nameFor(page));
+	};
+	const on = (event, handler) => track(router.on(event, insulate(handler)));
+	on("start", (event) => {
+		const visit = event?.detail?.visit;
+		if (isBackgroundVisit(visit)) return;
+		const { href, path } = locationOf(visit?.url);
+		if (inFlight) {
+			inFlightPath = path;
+			nav.setActiveRouteName({
+				name: path ?? currentPath(),
+				source: "url",
+				url: href
+			});
+			return;
+		}
+		sawInitial = true;
+		inFlight = true;
+		inFlightPath = path;
+		nav.startNavigation({
+			path,
+			url: href,
+			hold: true
+		});
+	});
+	on("navigate", (event) => {
+		const page = event?.detail?.page;
+		if (inFlight) {
+			settle(page);
+			return;
+		}
+		if (!sawInitial) {
+			sawInitial = true;
+			nav.setActiveRouteName(nameFor(page));
+			return;
+		}
+		const { href, path } = locationOf(page?.url);
+		nav.startNavigation({
+			path,
+			url: href
+		});
+		settle(page);
+	});
+	on("success", (event) => {
+		if (!inFlight) return;
+		const page = event?.detail?.page;
+		if (locationOf(page?.url).path !== inFlightPath) return;
+		settle(page);
+	});
+	/** Whether `visit` is the one that opened the currently held root, i.e. `finish` may settle it. */
+	const belongsToThisNavigation = (visit) => {
+		if (isBackgroundVisit(visit)) return false;
+		if (visit && locationOf(visit.url).path !== inFlightPath) return false;
+		if (visit?.interrupted) return false;
+		return true;
+	};
+	on("finish", (event) => {
+		if (!inFlight) return;
+		if (!belongsToThisNavigation(event?.detail?.visit)) return;
+		inFlight = false;
+		inFlightPath = void 0;
+		const { href, path } = locationOf(currentPath());
+		const knownComponentName = lastComponent?.path === path ? lastComponent?.name : void 0;
+		nav.settleNavigation(routeName(() => knownComponentName, path ?? currentPath(), href));
+	});
+}
+
+//#endregion
+export { traceInertiaRouter };

package/package.json

@@ -0,0 +1,60 @@
+{
+    "name": "@flareapp/inertia",
+    "version": "2.8.0",
+    "description": "Inertia.js performance tracing for flareapp.io",
+    "homepage": "https://flareapp.io",
+    "bugs": "https://github.com/spatie/flare-client-js/issues",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/spatie/flare-client-js.git"
+    },
+    "license": "MIT",
+    "author": {
+        "name": "Spatie",
+        "email": "info@spatie.be"
+    },
+    "contributors": [
+        "Dries Heyninck <dries@spatie.be>"
+    ],
+    "files": [
+        "dist"
+    ],
+    "sideEffects": false,
+    "main": "./dist/index.cjs",
+    "module": "./dist/index.mjs",
+    "types": "./dist/index.d.cts",
+    "exports": {
+        ".": {
+            "import": {
+                "types": "./dist/index.d.mts",
+                "default": "./dist/index.mjs"
+            },
+            "require": {
+                "types": "./dist/index.d.cts",
+                "default": "./dist/index.cjs"
+            }
+        }
+    },
+    "scripts": {
+        "prepublishOnly": "npm run build",
+        "build": "tsdown src/index.ts --format cjs,esm --dts --clean",
+        "typescript": "tsc --noEmit",
+        "test": "vitest run",
+        "release": "release-it"
+    },
+    "devDependencies": {
+        "@flareapp/js": "file:../js",
+        "@flareapp/test-helpers": "*",
+        "@inertiajs/core": "^2.3.27",
+        "jsdom": "^26.1.0",
+        "tsdown": "^0.20.3",
+        "typescript": "^5.7.0",
+        "vitest": "^4.0.0"
+    },
+    "peerDependencies": {
+        "@flareapp/js": "^2.8.0"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
+}