From cbbe6230497123b35c7960ed8118dd90d16d970c Mon Sep 17 00:00:00 2001 From: Nicolas Hrubec Date: Thu, 26 Feb 2026 10:11:14 +0100 Subject: [PATCH 1/4] Update tss guide to include serverless etup --- .../guides/tanstackstart-react/index.mdx | 95 ++++++++++++------- 1 file changed, 61 insertions(+), 34 deletions(-) diff --git a/docs/platforms/javascript/guides/tanstackstart-react/index.mdx b/docs/platforms/javascript/guides/tanstackstart-react/index.mdx index 288bd66381a1b..9b7899b39e560 100644 --- a/docs/platforms/javascript/guides/tanstackstart-react/index.mdx +++ b/docs/platforms/javascript/guides/tanstackstart-react/index.mdx @@ -140,10 +140,15 @@ Sentry.init({ }); ``` - #### Instrument the Server Entry Point -To enable tracing for server-side requests, you need to explicitly define a [server entry point](https://tanstack.com/start/latest/docs/framework/react/guide/server-entry-point) in your application and wrap your request handler with `wrapFetchWithSentry`. +To capture server-side errors and tracing data, you need to explicitly define a [server entry point](https://tanstack.com/start/latest/docs/framework/react/guide/server-entry-point) in your application and wrap your request handler with `wrapFetchWithSentry`. + +Follow the section below that matches your deployment setup: + +#### Node.js Server + +Use this setup when running your application as a long-lived Node.js process (e.g. a traditional server or container). Create a `src/server.ts` file in your project: @@ -160,7 +165,60 @@ export default createServerEntry( ); ``` - +##### Moving the Sentry server config file for production usage + +For production monitoring, you need to move the Sentry server config file 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). + +For example, when using [Nitro](https://nitro.build/), copy the instrumentation file to `".output/server"`: + +```json {diff} {filename:package.json} +{ + "scripts": { +- "build": "vite build", ++ "build": "vite build && cp instrument.server.mjs .output/server", + } +} +``` + +##### Load Instrumentation on Startup + +Add a `--import` flag directly or to the `NODE_OPTIONS` environment variable wherever you run your application to import `instrument.server.mjs`. + +```json {diff} {filename:package.json} +{ + "scripts": { + "build": "vite build && cp instrument.server.mjs .output/server", +- "dev": "vite dev --port 3000", +- "start": "node .output/server/index.mjs", ++ "dev": "NODE_OPTIONS='--import ./instrument.server.mjs' vite dev --port 3000", ++ "start": "node --import ./.output/server/instrument.server.mjs .output/server/index.mjs", + } +} +``` + +#### Serverless (e.g. Vercel, Netlify) + +Use this setup when deploying to a serverless platform. Instead of using the `--import` flag, import the server instrumentation file directly at the top of your server entry point. + +Create a `src/server.ts` file in your project: + +```typescript {filename:src/server.ts} +import "../instrument.server.mjs"; +import { wrapFetchWithSentry } from "@sentry/tanstackstart-react"; +import handler, { createServerEntry } from "@tanstack/react-start/server-entry"; + +export default createServerEntry( + wrapFetchWithSentry({ + fetch(request: Request) { + return handler.fetch(request); + }, + }) +); +``` + + + This setup does not currently work for Cloudflare deployments. + #### Add the sentryTanstackStart Vite Plugin @@ -196,37 +254,6 @@ export default defineConfig({ By default, this plugin manages source map uploads. When tracing is enabled, it also automatically instruments middlewares for tracing. For all available options, see the [Vite Plugin documentation](/platforms/javascript/guides/tanstackstart-react/features/sentryTanstackStart/). -#### Moving the Sentry server config file for production usage - -For production monitoring, you need to move the Sentry server config file 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). - -For example, when using [Nitro](https://nitro.build/), copy the instrumentation file to `".output/server"`: - -```json {diff} {filename:package.json} -{ - "scripts": { -- "build": "vite build", -+ "build": "vite build && cp instrument.server.mjs .output/server", - } -} -``` - -#### Load Instrumentation on Startup - -Add a `--import` flag directly or to the `NODE_OPTIONS` environment variable wherever you run your application to import `instrument.server.mjs`. - -```json {diff} {filename:package.json} -{ - "scripts": { - "build": "vite build && cp instrument.server.mjs .output/server", -- "dev": "vite dev --port 3000", -- "start": "node .output/server/index.mjs", -+ "dev": "NODE_OPTIONS='--import ./instrument.server.mjs' vite dev --port 3000", -+ "start": "node --import ./.output/server/instrument.server.mjs .output/server/index.mjs", - } -} -``` - ## Step 3: Capture TanStack Start React Errors ### Capturing Server-Side Errors From 2c5368fdb3ea28b67424ec3f4e32123ca51ac404 Mon Sep 17 00:00:00 2001 From: Nicolas Hrubec Date: Thu, 26 Feb 2026 10:15:42 +0100 Subject: [PATCH 2/4] move vite plugin section up --- .../guides/tanstackstart-react/index.mdx | 68 +++++++++---------- 1 file changed, 34 insertions(+), 34 deletions(-) diff --git a/docs/platforms/javascript/guides/tanstackstart-react/index.mdx b/docs/platforms/javascript/guides/tanstackstart-react/index.mdx index 9b7899b39e560..9ee3e59a9d607 100644 --- a/docs/platforms/javascript/guides/tanstackstart-react/index.mdx +++ b/docs/platforms/javascript/guides/tanstackstart-react/index.mdx @@ -140,6 +140,40 @@ Sentry.init({ }); ``` +#### Add the sentryTanstackStart Vite Plugin + + + +**Make sure you add your auth token to your CI, if you are using one to deploy your application.** + +Add your auth token to your environment: + +```bash {filename:.env} +SENTRY_AUTH_TOKEN=___ORG_AUTH_TOKEN___ +``` + +and configure `sentryTanstackStart` in your `vite.config.ts`: + +```typescript {filename:vite.config.ts} +import { defineConfig } from "vite"; +import { sentryTanstackStart } from "@sentry/tanstackstart-react/vite"; +import { tanstackStart } from "@tanstack/react-start/plugin/vite"; + +export default defineConfig({ + plugins: [ + tanstackStart(), + // other plugins - sentryTanstackStart should be last + sentryTanstackStart({ + org: "___ORG_SLUG___", + project: "___PROJECT_SLUG___", + authToken: process.env.SENTRY_AUTH_TOKEN, + }), + ], +}); +``` + +By default, this plugin manages source map uploads. When tracing is enabled, it also automatically instruments middlewares for tracing. For all available options, see the [Vite Plugin documentation](/platforms/javascript/guides/tanstackstart-react/features/sentryTanstackStart/). + #### Instrument the Server Entry Point To capture server-side errors and tracing data, you need to explicitly define a [server entry point](https://tanstack.com/start/latest/docs/framework/react/guide/server-entry-point) in your application and wrap your request handler with `wrapFetchWithSentry`. @@ -220,40 +254,6 @@ export default createServerEntry( This setup does not currently work for Cloudflare deployments. -#### Add the sentryTanstackStart Vite Plugin - - - -**Make sure you add your auth token to your CI, if you are using one to deploy your application.** - -Add your auth token to your environment: - -```bash {filename:.env} -SENTRY_AUTH_TOKEN=___ORG_AUTH_TOKEN___ -``` - -and configure `sentryTanstackStart` in your `vite.config.ts`: - -```typescript {filename:vite.config.ts} -import { defineConfig } from "vite"; -import { sentryTanstackStart } from "@sentry/tanstackstart-react/vite"; -import { tanstackStart } from "@tanstack/react-start/plugin/vite"; - -export default defineConfig({ - plugins: [ - tanstackStart(), - // other plugins - sentryTanstackStart should be last - sentryTanstackStart({ - org: "___ORG_SLUG___", - project: "___PROJECT_SLUG___", - authToken: process.env.SENTRY_AUTH_TOKEN, - }), - ], -}); -``` - -By default, this plugin manages source map uploads. When tracing is enabled, it also automatically instruments middlewares for tracing. For all available options, see the [Vite Plugin documentation](/platforms/javascript/guides/tanstackstart-react/features/sentryTanstackStart/). - ## Step 3: Capture TanStack Start React Errors ### Capturing Server-Side Errors From 308cf13019c60829ea2477bb76bac3120d3a6280 Mon Sep 17 00:00:00 2001 From: Nicolas Hrubec Date: Thu, 26 Feb 2026 12:58:21 +0100 Subject: [PATCH 3/4] document limitations --- .../javascript/guides/tanstackstart-react/index.mdx | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/platforms/javascript/guides/tanstackstart-react/index.mdx b/docs/platforms/javascript/guides/tanstackstart-react/index.mdx index 9ee3e59a9d607..6ed049dfb1b82 100644 --- a/docs/platforms/javascript/guides/tanstackstart-react/index.mdx +++ b/docs/platforms/javascript/guides/tanstackstart-react/index.mdx @@ -250,6 +250,16 @@ export default createServerEntry( ); ``` + + +This installation method has the fundamental restriction that only native Node.js APIs can be instrumented (such as `fetch` and the `http` module). + +As a result, the Sentry SDK will not capture data from database calls, queues, ORMs, third-party libraries, or other framework-specific data. + +We recommend using the [Node.js Server setup](#nodejs-server) if the `--import` flag is an option for you. + + + This setup does not currently work for Cloudflare deployments. From d7d7f6b77db9a8c67cceaab4bea8aae00a0dbe66 Mon Sep 17 00:00:00 2001 From: Nicolas Hrubec Date: Fri, 27 Feb 2026 14:08:42 +0100 Subject: [PATCH 4/4] split sections as with and without --import --- .../javascript/guides/tanstackstart-react/index.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/platforms/javascript/guides/tanstackstart-react/index.mdx b/docs/platforms/javascript/guides/tanstackstart-react/index.mdx index 6ed049dfb1b82..d76f1067c9fd1 100644 --- a/docs/platforms/javascript/guides/tanstackstart-react/index.mdx +++ b/docs/platforms/javascript/guides/tanstackstart-react/index.mdx @@ -180,9 +180,9 @@ To capture server-side errors and tracing data, you need to explicitly define a Follow the section below that matches your deployment setup: -#### Node.js Server +#### With `--import` Flag (e.g. Node.js Server) -Use this setup when running your application as a long-lived Node.js process (e.g. a traditional server or container). +Use this setup when you can configure Node.js CLI flags. Create a `src/server.ts` file in your project: @@ -230,9 +230,9 @@ Add a `--import` flag directly or to the `NODE_OPTIONS` environment variable whe } ``` -#### Serverless (e.g. Vercel, Netlify) +#### Without `--import` Flag (e.g. Vercel, Netlify) -Use this setup when deploying to a serverless platform. Instead of using the `--import` flag, import the server instrumentation file directly at the top of your server entry point. +If you can't configure Node.js CLI flags or environment variables at runtime (for example, when deploying to serverless platforms like Vercel or Netlify), you can import the server instrumentation file directly at the top of your server entry point instead. Create a `src/server.ts` file in your project: @@ -256,7 +256,7 @@ This installation method has the fundamental restriction that only native Node.j As a result, the Sentry SDK will not capture data from database calls, queues, ORMs, third-party libraries, or other framework-specific data. -We recommend using the [Node.js Server setup](#nodejs-server) if the `--import` flag is an option for you. +We recommend using the [setup with the `--import` flag](#with---import-flag-eg-nodejs-server) if possible.