diff --git a/docs/platforms/javascript/guides/tanstackstart-react/index.mdx b/docs/platforms/javascript/guides/tanstackstart-react/index.mdx index 288bd66381a1b..d76f1067c9fd1 100644 --- a/docs/platforms/javascript/guides/tanstackstart-react/index.mdx +++ b/docs/platforms/javascript/guides/tanstackstart-react/index.mdx @@ -140,28 +140,6 @@ 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`. - -Create a `src/server.ts` file in your project: - -```typescript {filename:src/server.ts} -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); - }, - }) -); -``` - - - #### Add the sentryTanstackStart Vite Plugin @@ -196,7 +174,32 @@ 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 +#### 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`. + +Follow the section below that matches your deployment setup: + +#### With `--import` Flag (e.g. Node.js Server) + +Use this setup when you can configure Node.js CLI flags. + +Create a `src/server.ts` file in your project: + +```typescript {filename:src/server.ts} +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); + }, + }) +); +``` + +##### 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). @@ -211,7 +214,7 @@ For example, when using [Nitro](https://nitro.build/), copy the instrumentation } ``` -#### Load Instrumentation on Startup +##### 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`. @@ -227,6 +230,40 @@ Add a `--import` flag directly or to the `NODE_OPTIONS` environment variable whe } ``` +#### Without `--import` Flag (e.g. Vercel, Netlify) + +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: + +```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 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 [setup with the `--import` flag](#with---import-flag-eg-nodejs-server) if possible. + + + + + This setup does not currently work for Cloudflare deployments. + + ## Step 3: Capture TanStack Start React Errors ### Capturing Server-Side Errors