npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@rivi-software/posthog-tanstack-start

v1.0.1

Published

PostHog error tracking for TanStack Start apps on Cloudflare Workers: the Worker's capture, the Start middlewares, the browser SDK loaded after hydration, secret-path redaction and the source map upload

Readme

@rivi-software/posthog-tanstack-start

npm version CI status MIT License

PostHog error tracking for TanStack Start apps on Cloudflare Workers:

  • the Worker's exceptions and events, through posthog-node
  • Start middlewares that report what server functions and server routes throw
  • the browser SDK, loaded after hydration
  • redaction of routes whose address is a credential
  • the source map upload

Your app keeps control of what it tracks: its own posthog-js options, such as consent, analytics and session replay.

Install

npm install @rivi-software/posthog-tanstack-start posthog-node posthog-js
# for the source map upload
npm install --save-dev @posthog/rollup-plugin

The PostHog libraries are peer dependencies, so the app and this package share one SDK:

  • posthog-node: ./server and ./start need it.
  • posthog-js: only ./browser needs it.
  • @posthog/rollup-plugin: only ./vite needs it.

The rollup plugin depends on @posthog/cli, whose build script pnpm 12 asks you to approve or deny. Deny it, because the CLI downloads its binary when it first runs: put allowBuilds: { "@posthog/cli": false } in pnpm-workspace.yaml.

It needs TanStack Start 1.169 or later (with TanStack Router 1.170 or later), Vite 6, 7 or 8, posthog-node 5.57.1 or later and posthog-js 1.438.21 or later. The package is ESM only.

Entry points

| Entry point | Contents | Runs in | | --- | --- | --- | | …/server | captureServerException, captureServerEvent, setSecretPaths, installPostHogForTests | The Worker (cloudflare:workers) | | …/start | posthogFunctionErrors, posthogRequestErrors (the Start middlewares), getPostHogBrowserConfig (the browser's settings, for the router's dehydrate) | TanStack Start, both sides | | …/browser | initPostHog(config, options), withPostHog, captureClientException, redactSecretPaths, PostHogBrowserConfig | The browser | | …/vite | posthogSourcemaps({ releaseName, releaseVersion }), PostHogSourcemapOptions | Vite config |

TanStack Start compiles this package as it compiles the app's own code, because the package peer-depends on @tanstack/react-start. So the middlewares' server code and getPostHogBrowserConfig stay out of the browser's bundle.

Configuration

| Variable | Where | What | | --- | --- | --- | | POSTHOG_PROJECT_TOKEN | Worker var | The project API key (phc_…). Empty turns PostHog off on both sides, with a console error in development. | | POSTHOG_HOST | Worker var | The ingestion host: https://us.i.posthog.com (the default) or https://eu.i.posthog.com | | POSTHOG_PERSONAL_API_KEY | Build env | Turns on the source map upload. Set it only on the build that deploys. | | POSTHOG_PROJECT_ID | Build env | The project the maps go to | | POSTHOG_API_HOST | Build env | The app host for the upload: https://us.posthog.com (the default) or https://eu.posthog.com |

One pair of Worker vars configures the browser and the Worker alike: getPostHogBrowserConfig reads them during SSR, and the router hands them to the client. Declare them in the Worker's Env (wrangler types).

Usage

// vite.config.ts
import { posthogSourcemaps } from "@rivi-software/posthog-tanstack-start/vite";

export default defineConfig({
  plugins: [/* tanstackStart(), cloudflare(), … */ ...posthogSourcemaps({ releaseName: "web" })],
});
// src/start.ts
import { posthogFunctionErrors, posthogRequestErrors } from "@rivi-software/posthog-tanstack-start/start";

export const startInstance = createStart(() => ({
  requestMiddleware: [posthogRequestErrors],
  functionMiddleware: [posthogFunctionErrors],
}));
// src/router.tsx
import { captureClientException, initPostHog } from "@rivi-software/posthog-tanstack-start/browser";
import { getPostHogBrowserConfig } from "@rivi-software/posthog-tanstack-start/start";

const router = createRouter({
  routeTree,
  dehydrate: () => ({ posthog: getPostHogBrowserConfig() }),
  hydrate: ({ posthog }) => initPostHog(posthog, { person_profiles: "identified_only" }),
  defaultOnCatch: (error) => captureClientException(error),
});
// Anywhere on the server: a failure the code answers or logs instead of throwing.
import { captureServerException } from "@rivi-software/posthog-tanstack-start/server";

captureServerException(error, { request, properties: { handler: "file-upload" } });

With @rivi-software/deploy-watch, report a router error only once it is not a missing chunk that reloads the page: recoverFromChunkError(error).then((reloading) => reloading || captureClientException(error)).

How it works

  • The Worker. posthog-node (its workerd build) sends every exception and event on its own (captureExceptionImmediate, captureImmediate) and keeps the send alive past the response with waitUntil. Nothing waits in a batch the isolate could drop.

    captureServerException(error, { request, distinctId, properties }) sends the request's method, origin and path, never its query (which can hold a token or a search term). It also sends the browser's person and session, read from posthog-js' tracing headers on same-origin fetches, or from the SDK's cookie on a page load. That links the exception to the session replay.

    A handler that knows the person passes distinctId. captureServerEvent(event, distinctId, properties, anonymousId) sends any other event. Without a distinctId it sends the event anonymously (no person profile), under anonymousId when you pass one, so related events (one conversation's calls) share an id.

    Neither waits for PostHog or throws: a send that fails logs a console.warn line, and the handler's response goes out either way.

  • Secret paths. A route whose address is a credential, such as a shared ticket's page /t/$token, reaches PostHog as its pattern, never as the link. List the patterns, as TanStack Router writes them, once for each side:

    • In the Worker's entry module, setSecretPaths(patterns) covers what the Worker sends: an exception's $current_url and $pathname, the error's message and stack, and the properties of every exception and event.
    • In the posthog-js options, before_send: redactSecretPaths(patterns) covers every address an event or a person carries: an exception's message and stack, an autocaptured link and the heatmap's keys included.

    A pattern is read part by part, between slashes, as the router reads it, and matches in any case:

    | Part | Matches | | --- | --- | | t, files | That text | | $token | One segment | | {$token}, with fixed text around it: ticket-{$id}, {$token}.pdf | One segment that starts and ends with that text | | {-$token}, with or without text around it | One segment, or none | | $, or {$} with fixed text around it | The rest of the path, slashes included |

    A trailing slash (/t/$token/, an index route) is optional. setSecretPaths and redactSecretPaths throw for a pattern the router would read differently: a part it reads as fixed text, such as prefix$id (write prefix{$id}), {token} or two parameters in one part; anything after $; and anything but fixed text after {$}.

    Three things get past that:

    • Session replay's $snapshot is compressed and goes as it is. Keep replay off, or block those paths in the project settings.
    • posthog-js' flags request sends the person's first address past before_send. Set advanced_disable_flags when you use no feature flags.
    • The redaction walks plain objects and arrays only. An Error or a class instance in the properties goes as the SDK writes it (posthog-node writes an Error's message and stack), so send its message or its fields instead.
  • The middlewares. Server functions turn a thrown error into an error response, and server routes answer one with a 500, before the Worker's fetch sees it; the middlewares report them there. Redirects, notFound and a thrown Response are control flow, and go unreported.

  • The browser. initPostHog loads posthog-js as its own chunk after hydration (about 100 kB gzipped), so no page waits for it. It applies the SDK defaults of 2026-05-30 and tracing headers to the page's own host, then the app's options over them.

    withPostHog runs a callback once the SDK has loaded (identify, reset, a custom event), and does nothing while PostHog is off. captureClientException reports what the router's error boundaries catch, which never reaches window.onerror.

    When posthog-js does not load, such as on a dropped connection or in a tab that outlived the deploy that removed its chunk, initPostHog logs one warning and PostHog stays off: withPostHog and captureClientException do nothing, and no rejection reaches the app's unhandledrejection handlers. The next call to initPostHog imports posthog-js again. When posthog-js throws as it starts, initPostHog logs one warning too, and PostHog stays off for the page: posthog-js counts itself started before it throws, so a second init would do nothing.

  • Source maps. posthogSourcemaps uploads the browser's maps and the server environments' maps as release releaseName at releaseVersion. The version defaults to GITHUB_SHA, else WORKERS_CI_COMMIT_SHA. The browser's maps are deleted after the upload, so they are never served. The server's stay on disk for Wrangler's own upload (upload_source_maps). Without POSTHOG_PERSONAL_API_KEY it returns no plugins, so a local build uploads nothing and needs no PostHog credentials.

    The plugin writes a snippet into every browser chunk that holds the chunk's id and, in event mode (the default), the release's id. Every release then renames every browser chunk, a server-only commit too. With @rivi-software/deploy-watch, every deploy that uploads source maps is a new browser build: each open tab loads the whole page at its next navigation, and a notice without module shows after each deploy. A notice per module still shows only once a deploy changed that module's code.

In your app's tests

vi.mock does not reach a module your test worker already imported, so a test swaps the client instead:

  • installPostHogForTests({ captureImmediate, captureExceptionImmediate }) puts a stand-in in its place. It gets the error and your properties as you passed them: the real client replaces the secret paths in them as it builds the event.
  • installPostHogForTests(null) turns PostHog off again.

Pin POSTHOG_PROJECT_TOKEN empty in your test config, so no test reports to your production project.

Development

The package's tests run in Node: vitest.config.ts points cloudflare:workers at tests/cloudflare-workers.ts, a stand-in with the Worker vars and no request context. tests/browser.test.ts runs in happy-dom instead, a dev dependency, with a stand-in posthog-js that fails to load or to start. In this directory, run pnpm run test, pnpm run check and pnpm run build.

License

Licensed under the MIT License. Copyright © 2026 RIVI Software.