From c281c1f85ea19ce35d9c2e69c2a28bdde0042a55 Mon Sep 17 00:00:00 2001
From: Nicolas Hrubec <nico.hrubec@sentry.io>
Date: Tue, 9 Jun 2026 14:25:34 +0200
Subject: [PATCH] docs(tanstackstart-react): Initialize Sentry from a dedicated
 client init file

Move the client Sentry.init() into a dedicated src/instrument.client.ts file
imported first in the client entry, matching the React setup. This ensures Sentry
initializes before any other import's side effects (and before hydration).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../manual-setup/index.mdx                    | 27 +++++++++++++++----
 1 file changed, 22 insertions(+), 5 deletions(-)

diff --git a/docs/platforms/javascript/guides/tanstackstart-react/manual-setup/index.mdx b/docs/platforms/javascript/guides/tanstackstart-react/manual-setup/index.mdx
index 3a32f8eecd175..5d763ef7558e1 100644
--- a/docs/platforms/javascript/guides/tanstackstart-react/manual-setup/index.mdx
+++ b/docs/platforms/javascript/guides/tanstackstart-react/manual-setup/index.mdx
@@ -81,16 +81,13 @@ pnpm add @sentry/tanstackstart-react
 <SplitSection>
 <SplitSectionText>
 
-Initialize Sentry in your [client entry point](https://tanstack.com/start/latest/docs/framework/react/guide/client-entry-point) `src/client.tsx`:
+Create an `instrument.client.ts` file in your `src/` directory and initialize Sentry in it.
 
 </SplitSectionText>
 <SplitSectionCode>
 
-```tsx {filename:src/client.tsx}
+```tsx {filename:src/instrument.client.ts}
 import * as Sentry from "@sentry/tanstackstart-react";
-import { StartClient } from "@tanstack/react-start/client";
-import { StrictMode, startTransition } from "react";
-import { hydrateRoot } from "react-dom/client";
 
 Sentry.init({
   dsn: "___PUBLIC_DSN___",
@@ -132,6 +129,26 @@ Sentry.init({
   replaysOnErrorSampleRate: 1.0,
   // ___PRODUCT_OPTION_END___ session-replay
 });
+```
+
+</SplitSectionCode>
+</SplitSection>
+
+<SplitSection>
+<SplitSectionText>
+
+Then import this file as the **first import** in your [client entry point](https://tanstack.com/start/latest/docs/framework/react/guide/client-entry-point) `src/client.tsx`. This ensures Sentry initializes before any other code runs, so errors and events before hydration are captured.
+
+</SplitSectionText>
+<SplitSectionCode>
+
+```tsx {filename:src/client.tsx}
+// Sentry initialization should be imported first!
+import "./instrument.client";
+
+import { StartClient } from "@tanstack/react-start/client";
+import { StrictMode, startTransition } from "react";
+import { hydrateRoot } from "react-dom/client";
 
 startTransition(() => {
   hydrateRoot(