@crawlsphere/react

Crawlsphere request tracking, optional React/browser events, and the existing CMS client and renderers.

Request tracking (v0.2)

npm install @crawlsphere/[email protected]

In Crawlsphere, open Agent traffic → Live request log → Set up SDK and create a source. Store its ingestion key in your server secrets. Use separate sources for production and local verification.

Wrap the outermost request handler, including routes that can return 404, redirects and static assets:

import { createRequestTracker } from '@crawlsphere/react/tracking-server';

export default {
  async fetch(request, env, ctx) {
    const tracker = createRequestTracker({
      endpoint: 'https://YOUR-CRAWLSPHERE-HOST/api/v1/ingest',
      key: env.CRAWLSPHERE_INGEST_KEY,
      onError: reason => console.warn('Crawlsphere delivery', reason),
    });
    return tracker.observe(request, () => app.fetch(request, env, ctx), ctx);
  },
};

app.fetch represents your existing handler. ctx.waitUntil must keep the background promise alive. On other runtimes, pass { waitUntil } from your hosting provider. Do not use an unawaited promise in a runtime that terminates after returning a response.

The adapter returns the original response, without reading or buffering its body. Delivery starts in a background task, uses a 3-second timeout, and retries once with the same event IDs. The collector deduplicates retries. tracker.stats exposes scheduled, delivered and failed counters. For durable delivery, provide enqueue(events) backed by your platform queue; its consumer must POST {events} to the ingestion endpoint with the ingestion key, acknowledge successful deliveries, and retry failures. Without that queue, delivery is best effort.

Coverage includes requests that reach this wrapper: successes, errors, redirects, methods, sanitized paths, response duration and user-agent family claims. Ensure your CDN routes cached/static requests through the wrapper if you want those recorded. User-agent labels are claims, not verified bot identities. Server logs cannot see clicks or prove AI citations.

No browser JavaScript is added by this entry point. No request bodies, cookies, IP addresses, raw user agents, query strings or fragments are sent. Sensitive route prefixes are grouped; use redactPath to template any additional identifying path segments. Keys authorize ingestion for one website, not workspace reads.

Optional browser events

Only add this when you need page views, tagged link clicks, dwell time, LCP observations or custom tool events. It adds browser code and has a separate performance cost from the server-only adapter.

import { CrawlSphereTracking } from '@crawlsphere/react/tracking';

<CrawlSphereTracking endpoint="/api/crawlsphere/events" clicks vitals />

Implement that same-origin POST route on your server using tracker.browserRelay(request, ctx). It validates the origin and payload and supplies the secret server-side. Never put the ingestion key in React props, a public environment variable or browser code. The optional client starts after load and idle, batches events, and only tracks clicks on links with data-cs-track.

For a non-React app, use startBrowserTracking({endpoint, clicks, vitals}) from @crawlsphere/react/tracking-browser. Call .page() on SPA navigation, .capture('tool_name', 'success') for a tool result and .stop() during teardown. Browser delivery remains best effort.

Performance verification

Five alternating cold-browser mobile Lighthouse runs per variant used the same clean production Next.js page and identical streaming proxies. Only the server adapter differed. Both variants loaded all required assets and 183,858 bytes of JavaScript; both median performance scores were 90.

| Median | Baseline | Server tracking | | --- | ---: | ---: | | LCP | 3,605.0 ms | 3,606.4 ms | | Total blocking time | 8.5 ms | 7.0 ms | | CLS | 0 | 0 |

LCP difference: +1.4 ms (+0.039%). These local lab results support negligible overhead in this setup, not a guarantee of zero impact on every deployment. This benchmark does not measure the optional browser adapter. Repeat against your own production routes and monitor field data.

Existing CMS exports

The existing CrawlSphereClient, React hooks, Next helpers, content renderer, fonts and styles remain exported through ., /client, /next, /content, /fonts, and /styles.css. These target the earlier CrawlSphere CMS API; they do not replace the current workspace API. Keep authenticated CMS clients on the server and pass public results into browser components. Request tracking is independent and does not require React.

Development

pnpm build
pnpm typecheck
pnpm test

License: MIT.