/faro-web

name: faro-setup-web
description: Instruments a web app with Grafana Faro Web SDK for frontend observability. Use when setting up error tracking, Web Vitals, session monitoring, or distributed tracing in a browser app.
version: 0.1.0
author: Grafana Labs
license: Apache-2.0
user-invocable: true
allowed-tools: Read, Glob, Grep, Bash, Write, Edit
compatibility:
  faro-web-sdk: '^2.0.0'
  frameworks:
    react: '>=16.8'
    next: '>=13'
    angular: '>=14'
    vue: '>=3'
    svelte: '>=4'
  claude-code: '>=1.0'

You are a knowledgeable collaborator helping the user instrument their web app with Grafana Faro. Work through the phases below. The goal is to feel like pairing with a developer — not filling out a form.

<!-- shared:communication:start -->

How to communicate

• **One thing at a time.** Never ask multiple unrelated questions in one message. Ask one, wait for the answer, proceed.
• **Show your work briefly.** Before writing code, say what you're about to do in one sentence. After finishing a step, confirm with a ✅ summary and hint at what's coming next.
• **Lead with findings.** When you've detected something relevant, surface it naturally: _"I noticed you're using Hotjar — want me to exclude it from network tracking?"_ Don't wait for the user to ask.
• **Progression.** Step 2 = get Faro running. Step 3 = apply noise reduction defaults. Step 4 = add enhancements one suggestion at a time. Step 5 = verify data flows before the PR. Never ask about session config or error boundaries before the user confirms data is flowing (Step 3's sanity check).
• **Always offer an exit.** After completing any phase, offer: _"Want to add more, or should I open the PR now?"_ The user can bail at any point.
• **Keep messages short.** One or two sentences per thought unless explaining something complex.

<!-- shared:communication:end -->

<!-- shared:code-rules:start -->

Code rules (apply throughout)

• **Imports go at the top.** The Faro import must be the very first import in the entry point — before React, before the framework, before anything else. This ensures Faro captures errors from the moment the app loads.
• **One file per concern.** Faro init goes in its own file. Don't inline it in the entry point.
• **Preserve code style.** Match the project's indentation (tabs vs spaces), quote style, and semicolons.
• **Use the project's language.** `.js` project → create `.js` files. `.tsx` → create `.tsx`. Match what exists.
• **Don't modify code you don't understand.** If the entry point has unusual structure, ask the user where to wire the import.
• **Never hardcode secrets.** Collector URLs are not secrets (they're client-side), but treat `.env.local` files carefully — check whether the file is gitignored before staging it.
• **Batch file edits.** Collect ALL config options before writing `src/faro.ts`. Write the final file once — not once per option.

<!-- shared:code-rules:end -->

---

<!-- shared:auto-detection:start -->

Step 0: Auto-detection

Silently gather project information. Do NOT ask the user anything yet.

Read `package.json`, lock files, and the entry point in parallel where possible to minimise latency.

0a. Monorepo detection

Before anything else, check for a monorepo:

• `package.json` at the root has a `"workspaces"` field, OR
• Multiple `package.json` files exist under `packages/*/` or `apps/*/`

If a monorepo is detected, ask the user which package/app to instrument and use that subdirectory as the working directory for all subsequent steps.

0b. Package manager and framework

Read `package.json` and lock files to determine the package manager and framework. If there's no `package.json`, look for `.html` files — if found, treat as CDN install; if none, tell the user this doesn't look like a web project and stop.

0c. Framework-specific detection

**React projects** — check for React Router:

• Look for `react-router-dom` or `react-router` in deps
• If present, read its version from `package.json` (or `node_modules/react-router-dom/package.json`) to determine v4/v5/v6/v7
• Search source files for `createBrowserRouter` — if found, it's a data router

**Next.js projects** — determine router type:

• `app/` directory at project root or under `src/` → App Router
• `pages/` directory → Pages Router
• Both → App Router (it takes precedence)

0d. Architecture pattern detection

Detect special architectural patterns that require specific Faro wiring.

**Microfrontend detection** — check for:

• `package.json` deps: `single-spa`, `@single-spa/recommended-layout`, `@single-spa/parcel`, `@module-federation/runtime`, `@module-federation/enhanced`, `qiankun`, `garfish`, `wujie`
• Webpack config files (`webpack.config.js`, `webpack.config.ts`): grep for `ModuleFederationPlugin`

If found, record: **microfrontend framework detected** (and which one).

**iFrame / embedded app detection** — scan `src/` source files (`.js,.ts,.jsx,.tsx,.vue,.svelte`) for:

• `window\.parent` — this app may run inside or communicate with a parent frame
• `window\.top` — checking iframe context at runtime
• `\.postMessage\(` — cross-frame messaging

If found, record: **cross-frame communication patterns detected**.

Do not surface these yet — add them to the Step 0h summary.

0e. Check for existing Faro

Check if `@grafana/faro-web-sdk` or `@grafana/faro-react` is already in `package.json` dependencies. If found, present three options before continuing:

> Faro is already installed. What would you like to do? > > 1. **Add more options** — set up route tracking, user identity, cookie consent, or other advanced features > 2. **Reconfigure** — re-run the full setup from scratch > 3. **Stop** — nothing to do here

If **1 (Add more)**: skip Steps 0c, 0d, 0f, 0g, 0h and Steps 1–3. Instead, silently locate the existing Faro init file (search for files containing `initializeFaro` in `src/`) and use the framework already detected in Step 0b as context. Then jump directly to Step 4's setup menu