Skip to content
Monitoring
Skill

/maple-frontend-tracing

Trace a web frontend with Maple: install @maple-dev/browser, link browser and backend traces, add route navigation and data-loading spans, report errors the framework catches, and join the first page load to the server render. Per-framework references for TanStack Router/Start,

From plugin
maple
2k40 skills

Claude Code

$ npx -y skills add mapletechlabs/maple --skill maple-frontend-tracing --agent claude-code

SKILL.md

maple-frontend-tracing.SKILL.md
name: maple-frontend-tracing
description: "Trace a web frontend with Maple: install @maple-dev/browser, link browser and backend traces, add route navigation and data-loading spans, report errors the framework catches, and join the first page load to the server render. Per-framework references for TanStack Router/Start, React Router, Next.js, Vue/Nuxt, SvelteKit, Angular and Astro. Triggers on 'trace my frontend', 'add frontend observability', 'instrument the browser with Maple', 'trace route changes', 'connect frontend and backend traces', 'add session replay'."

Maple frontend tracing

The goal: **one click is one trace**. A navigation span, the data-loading spans under it, the `fetch` spans they make, and the backend spans behind those. The first page load joins the server render's trace. Errors the framework catches are reported. Session replay links to the traces through a shared `session.id`.

The human-readable version of this skill is the guide at https://maple.dev/docs/frontend. Read it if you need the reasoning behind a step.

Step 0: Detect the framework and read its reference

Read the `package.json` of each web frontend in the repo, then read **only** the matching reference in `frameworks/`:

| Dependency | Reference | | --- | --- | | `@tanstack/react-router`, `@tanstack/react-start` | `frameworks/tanstack.md` | | `react-router` (v7, v8), `react-router-dom` | `frameworks/react-router.md` | | `next` | `frameworks/nextjs.md` | | `vue-router`, `nuxt` | `frameworks/vue.md` | | `@sveltejs/kit` | `frameworks/sveltekit.md` | | `@angular/router` | `frameworks/angular.md` | | `astro` | `frameworks/astro.md` | | anything else (Solid, Qwik, plain SPA, hand-rolled router) | `frameworks/other.md` |

The steps below are the same for every framework. The reference tells you where each one goes. If the references are not next to this file, read them from https://github.com/MapleTechLabs/maple/tree/main/skills/maple-frontend-tracing.

Backends are out of scope for this skill. If the API the frontend calls isn't instrumented with OpenTelemetry yet, use the `maple-onboard` skill for it first, or say in the hand-off that browser traces won't connect to it until it is.

Step 1: Key and region

Maple has two regions. A key only works in the region that issued it.

  • US (default): SDK option `region: "us"`, dashboard `https://app.maple.dev`.
  • EU: `region: "eu"`, dashboard `https://app.eu.maple.dev`. Use it when the prompt mentions the EU or an `eu.maple.dev` URL.

Browser code takes the **public** ingest key (`maple_pk_…`) only. It is write-only and safe to ship, like a Sentry DSN. Inline it in the init call. Never put a private key (`maple_sk_…`) in browser code: if the prompt only has a private key, use `MAPLE_TEST` in the browser and tell the user to swap in the public key. With no key at all, inline the sentinel `MAPLE_TEST` (ingest accepts it and stores nothing) and keep going.

Step 2: Install and initialize the browser SDK

Install `@maple-dev/browser` 0.14.0 or later with the project's package manager. It has two entries only: `@maple-dev/browser` and `@maple-dev/browser/react`. There are no per-framework or `/server` entries; never import `@maple-dev/browser/<framework>`. Add `@opentelemetry/api` only if app code imports it (the `await` rule's `context`, or where a reference says so): strict package managers (pnpm) won't resolve it as the SDK's transitive dependency. Initialize the SDK once, before the app renders, at the place the framework reference names:

import { MapleBrowser } from "@maple-dev/browser"

MapleBrowser.init({
	ingestKey: "MAPLE_TEST", // public key, maple_pk_…
	serviceName: "acme-web",
	region: "us", // "eu" for EU organizations
	serviceVersion: "<commit sha from the build env, if the bundler exposes one>",
	environment: import.meta.env.MODE,
	tracing: {
		// First-party APIs on another origin. Same-origin requests are covered already.
		propagateTraceHeaderCorsUrls: [/^https:\/\/api\.acme\.com\//], // RegExp: a plain string only matches as a prefix from 0.14.1
	},
})
  • `serviceName`: distinct from the backend's, usually `<app>-web`.
  • `init()` is a no-op on the server, so importing it from code that also runs during SSR is safe.
  • The SDK instruments `fetch` and `XMLHttpRequest`, so axios, Angular's `HttpClient` (fetch or XHR backend), `ky` and `ofetch` are all covered. Don't add another fetch or XHR instrumentation.
  • If another tracer already instruments `fetch` (for example `@maple-dev/effect-sdk/client`), set `tracing.instrumentFetch: false`.
  • Keep existing error and RUM vendors (Sentry, Datadog, LogRocket…). If another tool on the page also reports global errors to Maple, set `tracing.captureErrors: false` so errors aren't counted twice.

Step 3: Link browser and backend traces

1. Find every first-party API base URL the frontend calls (API client config, env vars like `VITE_API_URL`). Same-origin requests already carry `traceparent`. List each cross-origin first-party API in `propagateTraceHeaderCorsUrls` as an anchored regex. 2. **Never list third-party origins** (analytics, payment providers, CDNs). It leaks trace ids and often breaks their CORS preflight. 3. Check the API's CORS config. Many setups already echo the requested headers (the `cors` npm package default). If there's an explicit allow-list, add `traceparent` and keep the existing entries (plus `baggage` if the app sets OpenTelemetry baggage). Without this, the browser blocks the request after the preflight.

Step 4: Navigation and data-loading spans

React Router (data routers) and TanStack Router: use `instrumentReactRouter` / `instrumentTanStackRouter` from `@maple-dev/browser/react` as the reference says. Every other framework: copy the reference's router glue, which calls the SDK's three navigation methods from the router's hooks:

  • `MapleBrowser.startNavigation(path)`: call when the router starts a navigation. The first call opens a `pageload` span (joined
Read more
@mapletechlabs
Ships withmaple

OpenTelemetry observability platform

Stars on GitHub

Momentum

stars in total
2.0k
Star history of mapletechlabs/maple on GitHub, a chart by star-history.com

Other skills on maple.

More skills from other plugins.

agentdb-advanced

agentdb-advanced

Master advanced AgentDB features including QUIC synchronization, multi-database management, custom distance metrics, hybrid…

ruview2w102k
@ruvnet@ruvnetInstall Skill
install

install

Kubeshark installation and deployment skill. Use this skill whenever the user wants to install Kubeshark, deploy Kubeshark to a…

@kubeshark@kubesharkInstall Skill
scan

scan

Scan a project with sentrux to get structural health grades (A-F) across 14 dimensions including coupling, cycles, cohesion, dead…

sentrux8mo3.3k
@sentrux@sentruxInstall Skill
phone-input

phone-input

Call the user on the phone for real-time voice conversations. Use this when you need input, want to report on completed work, or…

callme7mo2.7k
@zeframlou@zeframlouInstall Skill

Questions about maple-frontend-tracing.

Which coding agents can use maple-frontend-tracing?
maple-frontend-tracing installs in Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode and Windsurf with the skills CLI, using each agent's flag shown on this page. Flowy's auto-invocation, which fires a skill when your prompt matches, runs in Claude Code only.