feat: TanStack Start docs for 1.0 RC

TkDodo · TkDodo · commit d69d9b5f15a0 · 2025-10-29T13:50:10.000+01:00
diff --git a/docs/platforms/javascript/guides/tanstackstart-react/index.mdx b/docs/platforms/javascript/guides/tanstackstart-react/index.mdx
@@ -4,7 +4,7 @@ title: TanStack Start React
 
 <Alert>
 
-This SDK is currently in **ALPHA**. Alpha features are still in progress, may have bugs and might include breaking changes.
+This SDK is compatible with TanStack Start 1.0 RC and is currently in **ALPHA**. Alpha features are still in progress, may have bugs and might include breaking changes.
 Please reach out on [GitHub](https://github.com/getsentry/sentry-javascript/issues/new/choose) if you have any feedback or concerns.
 
 </Alert>
@@ -50,69 +50,69 @@ pnpm add @sentry/tanstackstart-react
 
 ### Configure Client-Side Sentry
 
-Create a `src/client.tsx` file (if you don't already have one) and initialize Sentry:
-
-```tsx {filename:src/client.tsx}
-import { hydrateRoot } from "react-dom/client";
-import { StartClient } from "@tanstack/react-start";
-import { createRouter } from "./router";
-
-import * as Sentry from "@sentry/tanstackstart-react";
-
-const router = createRouter();
-
-Sentry.init({
-  dsn: "___PUBLIC_DSN___",
-
-  // Adds request headers and IP for users, for more info visit:
-  // https://docs.sentry.io/platforms/javascript/guides/tanstackstart-react/configuration/options/#sendDefaultPii
-  sendDefaultPii: true,
-
-  integrations: [
-    // ___PRODUCT_OPTION_START___ performance
-    Sentry.tanstackRouterBrowserTracingIntegration(router),
-    // ___PRODUCT_OPTION_END___ performance
-    // ___PRODUCT_OPTION_START___ session-replay
-    Sentry.replayIntegration(),
-    // ___PRODUCT_OPTION_END___ session-replay
-    // ___PRODUCT_OPTION_START___ user-feedback
-    Sentry.feedbackIntegration({
-      // Additional SDK configuration goes in here, for example:
-      colorScheme: "system",
-    }),
-    // ___PRODUCT_OPTION_END___ user-feedback
-  ],
-  // ___PRODUCT_OPTION_START___ logs
-
-  // Enable logs to be sent to Sentry
-  enableLogs: true,
-  // ___PRODUCT_OPTION_END___ logs
-
-  // ___PRODUCT_OPTION_START___ performance
-  // Set tracesSampleRate to 1.0 to capture 100%
-  // of transactions for tracing.
-  // We recommend adjusting this value in production.
-  // Learn more at https://docs.sentry.io/platforms/javascript/configuration/options/#traces-sample-rate
-  tracesSampleRate: 1.0,
-  // ___PRODUCT_OPTION_END___ performance
-  // ___PRODUCT_OPTION_START___ session-replay
-
-  // Capture Replay for 10% of all sessions,
-  // plus for 100% of sessions with an error.
-  // Learn more at https://docs.sentry.io/platforms/javascript/session-replay/configuration/#general-integration-configuration
-  replaysSessionSampleRate: 0.1,
-  replaysOnErrorSampleRate: 1.0,
-  // ___PRODUCT_OPTION_END___ session-replay
-});
-
-hydrateRoot(document, <StartClient router={router} />);
+Initialize Sentry in your `src/router.tsx` file:
+
+```tsx {diff} {filename:src/router.tsx}
++import * as Sentry from "@sentry/tanstackstart-react";
+import { createRouter } from '@tanstack/react-router'
+
+// Create a new router instance
+export const getRouter = () => {
+  const router = createRouter();
+
++ if (!router.isServer) {
++   Sentry.init({
++     dsn: "___PUBLIC_DSN___",
++
++     // Adds request headers and IP for users, for more info visit:
++     // https://docs.sentry.io/platforms/javascript/guides/tanstackstart-react/configuration/options/#sendDefaultPii
++     sendDefaultPii: true,
++
++     integrations: [
++       // ___PRODUCT_OPTION_START___ performance
++       Sentry.tanstackRouterBrowserTracingIntegration(router),
++       // ___PRODUCT_OPTION_END___ performance
++       // ___PRODUCT_OPTION_START___ session-replay
++       Sentry.replayIntegration(),
++       // ___PRODUCT_OPTION_END___ session-replay
++       // ___PRODUCT_OPTION_START___ user-feedback
++       Sentry.feedbackIntegration({
++         // Additional SDK configuration goes in here, for example:
++         colorScheme: "system",
++       }),
++       // ___PRODUCT_OPTION_END___ user-feedback
++     ],
++     // ___PRODUCT_OPTION_START___ logs
++
++     // Enable logs to be sent to Sentry
++     enableLogs: true,
++     // ___PRODUCT_OPTION_END___ logs
++
++     // ___PRODUCT_OPTION_START___ performance
++     // Set tracesSampleRate to 1.0 to capture 100%
++     // of transactions for tracing.
++     // We recommend adjusting this value in production.
++     // Learn more at https://docs.sentry.io/platforms/javascript/configuration/options/#traces-sample-rate
++     tracesSampleRate: 1.0,
++     // ___PRODUCT_OPTION_END___ performance
++     // ___PRODUCT_OPTION_START___ session-replay
++
++     // Capture Replay for 10% of all sessions,
++     // plus for 100% of sessions with an error.
++     // Learn more at https://docs.sentry.io/platforms/javascript/session-replay/configuration/#general-integration-configuration
++     replaysSessionSampleRate: 0.1,
++     replaysOnErrorSampleRate: 1.0,
++     // ___PRODUCT_OPTION_END___ session-replay
++   });
+  }
+}
 ```
 
-### Configure Server-Side Sentry
+### Configure Server-side Sentry
 
-Next, import and initialize Sentry in `src/server.tsx`:
+Create an instrument file `instrument.server.mjs` in the root of your project. In this file, initialize the Sentry SDK for your server.
 
-```tsx {filename:src/server.tsx}
+```tsx {filename:instrument.server.mjs}
 import * as Sentry from "@sentry/tanstackstart-react";
 
 Sentry.init({
@@ -138,80 +138,48 @@ Sentry.init({
 });
 ```
 
-<OnboardingOption optionId="performance">
-
-### Apply Tracing to SSR
-
-Wrap `createRootRoute` with `wrapCreateRootRouteWithSentry` in `src/routes/__root.tsx` to apply tracing to Server-Side Rendering (SSR):
+#### Load Instrumentation on Startup
 
-```tsx {filename:src/routes/__root.tsx} {3,6}
-import type { ReactNode } from "react";
-import { createRootRoute } from "@tanstack/react-router";
-import { wrapCreateRootRouteWithSentry } from "@sentry/tanstackstart-react";
+Add a `--import` flag directly or to the `NODE_OPTIONS` environment variable wherever you run your application to import `instrument.server.mjs`.
 
-// (Wrap `createRootRoute`, not its return value!)
-export const Route = wrapCreateRootRouteWithSentry(createRootRoute)({
-  // ...
-});
+```json {filename:package.json}
+{
+  "scripts": {
+    "dev": "NODE_OPTIONS='--import ./instrument.server.mjs' vite dev --port 3000",
+    "start": "node --import ./.output/server/instrument.server.mjs .output/server/index.mjs",
+  }
+}
 ```
 
-</OnboardingOption>
-
-## Step 3: Capture TanStack Start React Errors
+#### Moving the Sentry server config file for production usage
 
-### Instrument Server Requests
+For production monitoring, the Sentry server config file needs to be moved to your build output. Since [TanStack Start is designed to work with any hosting provider](https://tanstack.com/start/latest/docs/framework/react/guide/hosting), the exact location will depend on where your build artifacts are deployed (for example, `"/dist"`, `".output/server"` or a platform-specific directory).
 
-Wrap the default stream handler with `wrapStreamHandlerWithSentry` in `src/server.tsx` to instrument requests to your server:
+For example, when using [nitro](https://nitro.build/), copy the instrumentation file to `".output/server"`.
 
-```tsx {filename:src/server.tsx} {12}
-import {
-  createStartHandler,
-  defaultStreamHandler,
-} from "@tanstack/react-start/server";
-import { getRouterManifest } from "@tanstack/react-start/router-manifest";
-import { createRouter } from "./router";
-import * as Sentry from "@sentry/tanstackstart-react";
-
-export default createStartHandler({
-  createRouter,
-  getRouterManifest,
-})(Sentry.wrapStreamHandlerWithSentry(defaultStreamHandler));
+```json {diff}  {filename:package.json}
+{
+  "scripts": {
+-   "build": "vite build",
++   "build": "vite build && cp instrument.server.mjs .output/server",
+    "dev": "NODE_OPTIONS='--import ./instrument.server.mjs' vite dev --port 3000",
+    "start": "node --import ./.output/server/instrument.server.mjs .output/server/index.mjs",
+  }
+}
 ```
 
-### Instrument Server Functions
-
-Add the Sentry middleware handler to your global middlewares in `src/global-middleware.ts` to instrument your server function invocations:
-
-<Alert level="info">
-
-If you haven't created `src/global-middleware.ts` file, follow the [TanStack Start documentation for Global Middleware](https://tanstack.com/start/latest/docs/framework/react/middleware#global-middleware) to set it up.
-
-</Alert>
-
-```ts {filename:src/global-middleware.ts}
-import {
-  createMiddleware,
-  registerGlobalMiddleware,
-} from "@tanstack/react-start";
-import * as Sentry from "@sentry/tanstackstart-react";
-
-registerGlobalMiddleware({
-  middleware: [
-    createMiddleware({ type: "function" }).server(
-      Sentry.sentryGlobalServerMiddlewareHandler()
-    ),
-  ],
-});
-```
+## Step 3: Capture TanStack Start React Errors
 
-### Capturing Errors in Error Boundaries and Components (Optional)
+### Instrument Server Requests and Server Functions
 
 <Alert level="info">
   Automatic error monitoring is not yet supported on the server side of TanStack
   Start. Use `captureException` to manually capture errors in your server-side
   code.
 </Alert>
 
+### Capturing Errors in Error Boundaries and Components (Optional)
+
 Sentry automatically captures unhandled client-side errors. Errors caught by your own error boundaries aren't captured unless you report them manually:
 
 #### Custom Error Boundary
@@ -255,11 +223,11 @@ const route = createRoute({
 })
 ```
 
-## Step 4: Avoid Ad Blockers With Tunneling (Optional)
+## Step 3: Avoid Ad Blockers With Tunneling (Optional)
 
 <PlatformContent includePath="getting-started-tunneling" />
 
-## Step 5: Verify
+## Step 4: Verify
 
 Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project.
 
@@ -287,18 +255,26 @@ To verify that Sentry captures errors and creates issues in your Sentry project,
 <OnboardingOption optionId="performance">
 ### Tracing
 
-To test tracing, create a new file like `src/routes/sentry-example.ts` to create a test route `/sentry-example`:
+To test tracing, create a new file like `src/routes/api/sentry-example.ts` to create a test route `/sentry-example`:
 
-```typescript {filename:src/routes/sentry-example.ts}
-import { createServerFileRoute } from "@tanstack/react-start/server";
+```typescript {filename:src/routes/api/sentry-example.ts}
+import { createFileRoute } from "@tanstack/react-router";
 import { json } from "@tanstack/react-start";
 
-export const ServerRoute = createServerFileRoute("/sentry-example").methods({
-  GET: async ({ request }) => {
-    throw new Error("Sentry Example Route Error");
-    return json({ message: "Testing Sentry Error..." });
+export const Route = createFileRoute('/api/sentry-example')({
+  server: {
+    handlers: {
+      GET: () => {
+        throw new Error("Sentry Example Route Error");
+        return new Response(JSON.stringify({ message: "Testing Sentry Error..." }), {
+          headers: {
+            'Content-Type': 'application/json',
+          },
+        })
+      },
+    },
   },
-});
+})
 ```
 
 Next, update your test button to call this route and throw an error if the response isn't `ok`:
@@ -313,7 +289,7 @@ Next, update your test button to call this route and throw an error if the respo
         op: "test",
       },
       async () => {
-        const res = await fetch("/sentry-example");
+        const res = await fetch("/api/sentry-example");
         if (!res.ok) {
           throw new Error("Sentry Example Frontend Error");
         }
