This file is the canonical project guide for coding agents. CLAUDE.md is kept as a symlink for tools that still look for that name. Keep this file tool-neutral and update it when project commands, package layout, or non-obvious conventions change.

This repository is the Pydantic Logfire JavaScript SDK monorepo. It provides OpenTelemetry-based tracing and logging packages for Node.js, browsers, Cloudflare Workers, and standalone manual tracing.

• packages/logfire-api publishes logfire, the core manual tracing API.
• packages/logfire-node publishes @pydantic/logfire-node, which adds Node.js SDK setup and automatic instrumentation.
• packages/logfire-cf-workers publishes @pydantic/logfire-cf-workers, which adapts Logfire to Cloudflare Workers.
• packages/otel-cf-workers publishes @pydantic/otel-cf-workers, the lower-level Cloudflare Workers OpenTelemetry implementation used by the Logfire wrapper.
• packages/logfire-browser publishes @pydantic/logfire-browser, which adapts Logfire to browser tracing.
• packages/logfire-session-replay publishes @pydantic/logfire-session-replay, the optional standalone rrweb recorder used by the browser package's session replay integration.
• vite.shared.ts holds the build helpers every package config imports: packageDefines() stamps PACKAGE_VERSION and PACKAGE_TIMESTAMP from the package's own package.json, and copyCjsDeclarations() emits the .d.cts files.
• vite.config.ts and tsconfig.base.json at the repository root hold the shared format, lint, task, and TypeScript configuration.
• examples/ contains runnable examples for Express, Next.js, Deno, Cloudflare Workers, browser usage, and related integrations.

• Use the Node.js version in .node-version. The root package.json also enforces Node.js 24 through engines.
• Use pnpm 11.5.2. The package manager is pinned in packageManager.
• Use Vite+ (vp) for the JavaScript toolchain entrypoint. Vite+ manages Vite, Vitest, Oxlint, Oxfmt, and package build tasks.
• Run workspace commands from the repository root unless a package-level command is explicitly needed.

Install dependencies:

vp install

Build all packages:

pnpm run build

Build packages in watch-style development mode:

pnpm run dev

Run all package tests:

pnpm run test

Run all checks before broad or release-oriented changes:

pnpm run check

Run focused checks for one package:

vp run logfire#test
vp run @pydantic/logfire-node#test
vp run @pydantic/logfire-browser#typecheck

Run a single Vite+ test by name from a package:

vp run logfire#test -- -t "test name pattern"

Format or verify formatting:

pnpm run format
pnpm run format-check

Add a changeset when a package-visible change needs a release note or version bump:

pnpm run changeset-add

• logfire wraps OpenTelemetry tracing APIs with convenience methods such as span, startSpan, info, debug, warn, and error.
• Runtime packages depend on logfire and add environment-specific configuration and instrumentation.
• Message templates are formatted by logfireFormatWithExtras() in packages/logfire-api/src/formatter.ts; template fields become structured attributes.
• Sensitive data scrubbing is handled by AttributeScrubber in packages/logfire-api/src/AttributeScrubber.ts.
• Trace IDs use ULIDs through ULIDGenerator.
• Logfire spans use logfire.span_type: log for point-in-time events and span for duration-based work.

• Prefer existing package patterns, helpers, and OpenTelemetry abstractions over introducing new wrappers.
• Keep changes scoped to the package or example relevant to the task.
• Update examples or docs when public behavior, configuration, or package usage changes.
• Add or update tests for behavior changes. If a package has minimal tests or --passWithNoTests, still run typecheck/build for that package when relevant.
• Avoid adding production dependencies without a clear need; keep workspace dependency and lockfile changes together.
• Do not put agent-specific or vendor-specific instructions here unless they are explicitly about repository compatibility. Use generic wording that applies to any coding agent.

• Tests use Vitest and usually live alongside source files as *.test.ts.
• Prefer exact assertions over fuzzy matching for stable output. Use toBe or toEqual with deterministic inputs instead of toContain or broad regex matching.
• When testing formatted errors or stack output, mock stack strings so assertions stay deterministic.
• The focused eval coverage script is temporarily disabled during the Vite+ migration because Vite+ coverage currently reports mixed Vitest package versions. For eval changes, run the package tests and typecheck instead:

vp run logfire#test
vp run logfire#typecheck

• packages/logfire-node/src/logfireConfig.ts owns Node SDK configuration and environment variable handling.
• Relevant environment variables include LOGFIRE_TOKEN, LOGFIRE_SERVICE_NAME, LOGFIRE_SERVICE_VERSION, LOGFIRE_ENVIRONMENT, LOGFIRE_CONSOLE, LOGFIRE_SEND_TO_LOGFIRE, and LOGFIRE_DISTRIBUTED_TRACING.
• packages/logfire-api is the base API package and should not depend on runtime-specific packages.
• Cloudflare Workers code should stay compatible with Worker runtime constraints.
• Browser code should avoid Node-only APIs.
• Prefer browser configureFrontend({ baseUrl, token, ...options }) for direct frontend application setup; it enables auto-instrumentation and Web Vitals metrics by default. Keep configure() for custom transports and proxies. See docs/packages/browser.md for overrides and optional replay.

Use examples to validate integration behavior when package-level tests do not cover the runtime path. Check the target example's package.json before running it, because scripts vary by example.

Typical flow:

cd examples/express
pnpm install
pnpm run dev

• Keep this file concise and operational. Prefer links or file paths over copied explanations when the code is self-describing.
• If a subdirectory needs different build, test, or safety rules, add a nested AGENTS.md in that directory instead of growing this root file.
• Instructions closest to the edited file should be treated as more specific than this root file.
• Preserve the CLAUDE.md symlink unless the repository drops compatibility with tools that read it.