Guide for AI agents

@belvador/tanstack-startRuntime: browser+workersreact: ^18.0.0 || ^19.0.0@tanstack/react-router: ^1.168.0@tanstack/react-start: ^1.168.0Cloudflare Workers: nodejs_compatInstallAdd the package to your app.```bashnpm install @belvador/tanstack-start@0.6.1```InitializeInitialize it as early as possible. Personal data and credentials are removed before anything is sent.src/instrument.ts```typescriptimport { init } from "@belvador/tanstack-start/client";// Imported first by src/start.ts and src/router.tsx. Runs only in the browser.if (typeof window !== "undefined") {  init({    dsn: "https://<public-key>@ingest.belvador.dev/<project-id>",    release: import.meta.env.VITE_APP_VERSION, // your build or commit id    environment: import.meta.env.MODE,  });}```BrowserImport ./instrument on the first line and report route error pages with defaultOnCatch. It runs only where an error component exists.src/router.tsx```typescriptimport "./instrument"; // first line, before the route treeimport { withBelvadorRouter } from "@belvador/tanstack-start/client";// In getRouter(): wrap the options you already pass to createRouter.// createRouter(withBelvadorRouter({ routeTree, ...yourOptions }))// It reports route errors, calls your own defaultOnCatch after that, and adds// TanStack's error component only if you set no defaultErrorComponent.```Server (Cloudflare Workers)Wrap the server entry: each request gets its own scope, errors are re-thrown and responses stay unchanged. Needs the nodejs_compat flag (Lovable apps have it).src/server.ts```typescriptimport handler from "@tanstack/react-start/server-entry";import { withBelvador } from "@belvador/tanstack-start/server";// Requires Cloudflare Workers with nodejs_compat enabled.// If src/server.ts already exists, wrap its default export instead of `handler`.// vite.config.ts needs tanstackStart: { server: { entry: "server" } } (Lovable apps have it).export default withBelvador(  (env: { BELVADOR_DSN?: string; BELVADOR_RELEASE?: string }) => ({    dsn: env.BELVADOR_DSN ?? "https://<public-key>@ingest.belvador.dev/<project-id>",    release: env.BELVADOR_RELEASE,  }),  handler,);```MiddlewarePut them last in each list so server-function and server-route errors are seen before an error-page middleware handles them.src/start.ts```typescriptimport "./instrument"; // first line: the browser loads start.ts before the routerimport { createStart } from "@tanstack/react-start";import { belvadorFunctionMiddleware, belvadorRequestMiddleware } from "@belvador/tanstack-start";export const startInstance = createStart(() => ({  // Last in each list, after your own middleware.  requestMiddleware: [/* …your middleware, */ belvadorRequestMiddleware],  functionMiddleware: [/* …your middleware, */ belvadorFunctionMiddleware],}));```Content Security PolicyIf your app sends a CSP header, allow the ingest address in connect-src.```textconnect-src 'self' https://ingest.belvador.dev;```Verify the browserProves that captured and uncaught browser errors reach this project, then reads the result back from Belvador.```typescriptimport { verifyIntegration } from "@belvador/tanstack-start/client";// Run once after setup or deploy (for example behind a debug flag), never on every page load.// The console shows one expected "Belvador verification (uncaught)" error — that is the test.const result = await verifyIntegration();// result.outcome: "verified" | "problem" | "unconfirmed"; the console prints one summary line.```Verify the serverProves that server code runs inside Belvador's middleware and that its errors reach this project.src/routes/api/verify-belvador.ts```typescriptimport { createFileRoute } from "@tanstack/react-router";import { verifyIntegration } from "@belvador/tanstack-start/server";// Temporary: open /api/verify-belvador once after deploying, then delete this file.// It must run inside belvadorRequestMiddleware (src/start.ts) — that is part of the check.export const Route = createFileRoute("/api/verify-belvador")({  server: {    handlers: {      GET: async () => Response.json(await verifyIntegration()),    },  },});```Read the result backUse the id the app printed. The answer lists which checks reached your node.```bashcurl -s "https://ingest.belvador.dev/api/<project-id>/verification/bv1_<id printed by your app>/?sentry_key=<public-key>"```Before you report doneRun the check for every runtime listed above. Report done only when each result is verified (or the read-back lists every check). If a result is problem or unconfirmed, show the user the exact "[belvador] verify …" line or read-back answer. Never remove existing middleware, error pages or security headers to make a check pass.Monitor background workAsk the user which scheduled jobs, queues or workers to monitor — don't guess. Use withMonitor (Belvador SDK), the Sentry SDK's crons API, or HTTP check-ins. Run each job once and finish only when the Belvador Monitors page shows that run. Browsers never send check-ins.

@belvador/reactRuntime: browserreact: ^18.0.0 || ^19.0.0InstallAdd the package to your app.```bashnpm install @belvador/react@0.6.1```InitializeInitialize it as early as possible. Personal data and credentials are removed before anything is sent.src/instrument.ts```typescriptimport { init } from "@belvador/react";init({  dsn: "https://<public-key>@ingest.belvador.dev/<project-id>",  release: import.meta.env.VITE_APP_VERSION, // your build or commit id  environment: import.meta.env.MODE,});```Import it firstMake it the first import of your entry file. Imports run before the rest of the file, so an error while your app's modules load is reported only if Belvador started before them.src/main.tsx```tsximport "./instrument"; // first line: starts Belvador before App's modules loadimport { createRoot } from "react-dom/client";import { ErrorBoundary } from "@belvador/react";import App from "./App";const root = document.getElementById("root");if (!root) throw new Error("Root element missing");createRoot(root).render(  <ErrorBoundary fallback={<p>Something went wrong.</p>}>    <App />  </ErrorBoundary>,);```Content Security PolicyIf your app sends a CSP header, allow the ingest address in connect-src.```textconnect-src 'self' https://ingest.belvador.dev;```Verify the browserProves that captured and uncaught browser errors reach this project, then reads the result back from Belvador.```typescriptimport { verifyIntegration } from "@belvador/react";// Run once after setup or deploy (for example behind a debug flag), never on every page load.// The console shows one expected "Belvador verification (uncaught)" error — that is the test.const result = await verifyIntegration();// result.outcome: "verified" | "problem" | "unconfirmed"; the console prints one summary line.```Read the result backUse the id the app printed. The answer lists which checks reached your node.```bashcurl -s "https://ingest.belvador.dev/api/<project-id>/verification/bv1_<id printed by your app>/?sentry_key=<public-key>"```Before you report doneRun the check for every runtime listed above. Report done only when each result is verified (or the read-back lists every check). If a result is problem or unconfirmed, show the user the exact "[belvador] verify …" line or read-back answer. Never remove existing middleware, error pages or security headers to make a check pass.Monitor background workAsk the user which scheduled jobs, queues or workers to monitor — don't guess. Use withMonitor (Belvador SDK), the Sentry SDK's crons API, or HTTP check-ins. Run each job once and finish only when the Belvador Monitors page shows that run. Browsers never send check-ins.

OpenTelemetry traces and logs → Belvador: Node.jstraces: supported (Belvador certification run 2026-10-24)logs: supported (Belvador certification run 2026-10-24), records carry trace_id/span_idTested with: node 22.23.4, @opentelemetry/sdk-node 0.300.0, @opentelemetry/auto-instrumentations-node 0.82.0, pino 10.4.0Guide: https://belvador.dev/en/docs/otel/nodeGoalSend this service's OpenTelemetry traces and logs to Belvador over OTLP/HTTP. Keep the existing error SDK (Belvador or Sentry) exactly as it is.Before you change anythingFind the runtime and version, the module system (CommonJS or ES modules for Node.js), the framework, how the app is started in production and where it is hosted. Look for an existing OpenTelemetry, Sentry tracing or vendor bootstrap. If something already creates spans, add Belvador as an exporter to that setup; if you cannot tell who owns tracing, ask the user. Never read, print or commit secrets — use the key placeholder.RulesOne tracer provider per process; no second SDK or handler wrapper that also creates spans. Do not change authentication, middleware order or business logic. Do not turn on capture of request or response bodies, headers, cookies, query values or GenAI message content. Keep metrics off. The ingest key is a server secret: environment or secret store only, never in browser code or a public env variable. No OpenTelemetry in browsers. Keep the exporter's batching; never await an export per request.Environment variablesSet these where the app runs (secret store for the key). Use the service's real name and the deployment's environment.```bashexport OTEL_EXPORTER_OTLP_ENDPOINT=https://ingest.belvador.dev/otlp/<project-id>export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobufexport OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer%20<your-ingest-key>export OTEL_TRACES_EXPORTER=otlpexport OTEL_LOGS_EXPORTER=otlpexport OTEL_METRICS_EXPORTER=noneexport OTEL_SERVICE_NAME=my-serviceexport OTEL_RESOURCE_ATTRIBUTES=deployment.environment.name=production```Certified recipeUse these steps as written; they are the ones Belvador's certification run executes. Change only file names, the start command and the service name to fit the project, and pin package versions like the rest of the project.```bashnpm install @opentelemetry/api @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node``````bashexport OTEL_SEMCONV_STABILITY_OPT_IN=httpexport OTEL_NODE_RESOURCE_DETECTORS=env,host,osnode --require @opentelemetry/auto-instrumentations-node/register app.js``````bashexport OTEL_SEMCONV_STABILITY_OPT_IN=httpexport OTEL_NODE_RESOURCE_DETECTORS=env,host,osnode --experimental-loader=@opentelemetry/instrumentation/hook.mjs --import @opentelemetry/auto-instrumentations-node/register app.mjs```VerifyStart the app locally with the variables set and send one request. Confirm one trace with server and client spans in Belvador's Traces page and one log line with the same trace id in Logs. Then ask the user to run "Check the OTLP connection" on the project's Connection tab. Do not send test traffic to production unless the user says so.ReportList the files you changed, the packages added with exact versions, how to turn it off (unset OTEL_EXPORTER_OTLP_ENDPOINT or remove the start flag), the environment and signals you actually saw arrive, and anything not verified.