From f23491b3f27e0be96f522b5cfed37e78b3558b02 Mon Sep 17 00:00:00 2001 From: Nicolas Hrubec Date: Fri, 27 Feb 2026 09:10:08 +0100 Subject: [PATCH 1/5] feat(onboarding): Add serverless setup guide to tanstack start --- .../javascript-tanstackstart-react/index.tsx | 5 +- .../onboarding.tsx | 195 ++++++++++++------ 2 files changed, 138 insertions(+), 62 deletions(-) diff --git a/static/app/gettingStartedDocs/javascript-tanstackstart-react/index.tsx b/static/app/gettingStartedDocs/javascript-tanstackstart-react/index.tsx index 1b933bd2d56084..da38760c94547e 100644 --- a/static/app/gettingStartedDocs/javascript-tanstackstart-react/index.tsx +++ b/static/app/gettingStartedDocs/javascript-tanstackstart-react/index.tsx @@ -5,10 +5,11 @@ import {metricsFullStack} from 'sentry/gettingStartedDocs/javascript/metrics'; import {profilingFullStack} from 'sentry/gettingStartedDocs/javascript/profiling'; import {mcp} from './mcp'; -import {onboarding} from './onboarding'; +import {onboarding, platformOptions, type PlatformOptions} from './onboarding'; -const docs: Docs = { +const docs: Docs = { onboarding, + platformOptions, profilingOnboarding: profilingFullStack({ packageName: '@sentry/tanstackstart-react', browserProfilingLink: diff --git a/static/app/gettingStartedDocs/javascript-tanstackstart-react/onboarding.tsx b/static/app/gettingStartedDocs/javascript-tanstackstart-react/onboarding.tsx index 5a62c2732ed4ad..98f11d4c25fd43 100644 --- a/static/app/gettingStartedDocs/javascript-tanstackstart-react/onboarding.tsx +++ b/static/app/gettingStartedDocs/javascript-tanstackstart-react/onboarding.tsx @@ -1,10 +1,31 @@ import {ExternalLink} from '@sentry/scraps/link'; -import type {OnboardingConfig} from 'sentry/components/onboarding/gettingStartedDoc/types'; +import type { + BasePlatformOptions, + OnboardingConfig, +} from 'sentry/components/onboarding/gettingStartedDoc/types'; import {StepType} from 'sentry/components/onboarding/gettingStartedDoc/types'; import {t, tct} from 'sentry/locale'; -export const onboarding: OnboardingConfig = { +export enum ServerPlatform { + NODE = 'node', + SERVERLESS = 'serverless', +} + +export const platformOptions = { + serverPlatform: { + label: t('Server Platform'), + items: [ + {label: t('Node.js Server'), value: ServerPlatform.NODE}, + {label: t('Serverless'), value: ServerPlatform.SERVERLESS}, + ], + defaultValue: ServerPlatform.NODE, + }, +} satisfies BasePlatformOptions; + +export type PlatformOptions = typeof platformOptions; + +export const onboarding: OnboardingConfig = { introduction: () => t("In this guide you'll set up the Sentry TanStack Start React SDK"), install: () => [ @@ -159,28 +180,57 @@ Sentry.init({ }, ], }, + { + type: 'text', + text: tct( + 'To capture server-side errors and traces, explicitly define a [serverEntryLink:server entry point] in your application and wrap your request handler with [code:wrapFetchWithSentry].', + { + code: , + serverEntryLink: ( + + ), + } + ), + }, + { + type: 'text', + text: tct('Create a [code:src/server.ts] file in your project:', { + code: , + }), + }, { type: 'conditional', - condition: params.isPerformanceSelected, + condition: + params.platformOptions.serverPlatform === ServerPlatform.NODE, content: [ { - type: 'text', - text: tct( - 'To enable tracing for server-side requests, you need to explicitly define a [serverEntryLink:server entry point] in your application and wrap your request handler with [code:wrapFetchWithSentry].', + type: 'code', + tabs: [ { - code: , - serverEntryLink: ( - - ), - } - ), - }, - { - type: 'text', - text: tct('Create a [code:src/server.ts] file in your project:', { - code: , - }), + label: 'TypeScript', + language: 'typescript', + filename: 'src/server.ts', + code: `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); + }, + }) +);`, + }, + ], }, + ], + }, + { + type: 'conditional', + condition: + params.platformOptions.serverPlatform === + ServerPlatform.SERVERLESS, + content: [ { type: 'code', tabs: [ @@ -188,7 +238,9 @@ Sentry.init({ label: 'TypeScript', language: 'typescript', filename: 'src/server.ts', - code: `import { wrapFetchWithSentry } from "@sentry/tanstackstart-react"; + code: `import "../instrument.server.mjs"; + +import { wrapFetchWithSentry } from "@sentry/tanstackstart-react"; import handler, { createServerEntry } from "@tanstack/react-start/server-entry"; export default createServerEntry( @@ -201,6 +253,22 @@ export default createServerEntry( }, ], }, + { + type: 'alert', + alertType: 'warning', + showIcon: true, + text: t( + 'When using the serverless setup, only native Node.js APIs will be instrumented (e.g. http, fetch). Database calls, queues, ORMs, and other third-party library instrumentation will not work.' + ), + }, + { + type: 'alert', + alertType: 'warning', + showIcon: true, + text: t( + 'Cloudflare is currently not supported by the Sentry TanStack Start SDK.' + ), + }, ], }, { @@ -235,63 +303,70 @@ export default defineConfig({ ], }, { - type: 'text', - text: tct( - 'For production monitoring, you need to move the Sentry server config file to your build output. Since [hostingLink:TanStack Start is designed to work with any hosting provider], the exact location will depend on where your build artifacts are deployed (for example, [code:/dist], [code:.output/server] or a platform-specific directory).', + type: 'conditional', + condition: + params.platformOptions.serverPlatform === ServerPlatform.NODE, + content: [ { - code: , - hostingLink: ( - + type: 'text', + text: tct( + 'For production monitoring, you need to move the Sentry server config file to your build output. Since [hostingLink:TanStack Start is designed to work with any hosting provider], the exact location will depend on where your build artifacts are deployed (for example, [code:/dist], [code:.output/server] or a platform-specific directory).', + { + code: , + hostingLink: ( + + ), + } ), - } - ), - }, - { - type: 'text', - text: tct( - 'For example, when using [nitroLink:Nitro], copy the instrumentation file to [code:.output/server]:', + }, { - code: , - nitroLink: , - } - ), - }, - { - type: 'code', - tabs: [ + type: 'text', + text: tct( + 'For example, when using [nitroLink:Nitro], copy the instrumentation file to [code:.output/server]:', + { + code: , + nitroLink: , + } + ), + }, { - label: 'JSON', - language: 'json', - filename: 'package.json', - code: `{ + type: 'code', + tabs: [ + { + label: 'JSON', + language: 'json', + filename: 'package.json', + code: `{ "scripts": { "build": "vite build && cp instrument.server.mjs .output/server", } }`, + }, + ], + }, + { + type: 'text', + text: tct( + 'Add a [code:--import] flag directly or to the [code:NODE_OPTIONS] environment variable wherever you run your application to import [code:instrument.server.mjs]:', + {code: } + ), }, - ], - }, - { - type: 'text', - text: tct( - 'Add a [code:--import] flag directly or to the [code:NODE_OPTIONS] environment variable wherever you run your application to import [code:instrument.server.mjs]:', - {code: } - ), - }, - { - type: 'code', - tabs: [ { - label: 'JSON', - language: 'json', - filename: 'package.json', - code: `{ + type: 'code', + tabs: [ + { + label: 'JSON', + language: 'json', + filename: 'package.json', + code: `{ "scripts": { "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", } }`, + }, + ], }, ], }, From 8723da1324043496398eb10ccf3ac81fd2740061 Mon Sep 17 00:00:00 2001 From: "getsantry[bot]" <66042841+getsantry[bot]@users.noreply.github.com> Date: Fri, 27 Feb 2026 08:14:13 +0000 Subject: [PATCH 2/5] :hammer_and_wrench: apply pre-commit fixes --- .../javascript-tanstackstart-react/onboarding.tsx | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/static/app/gettingStartedDocs/javascript-tanstackstart-react/onboarding.tsx b/static/app/gettingStartedDocs/javascript-tanstackstart-react/onboarding.tsx index 98f11d4c25fd43..a2e43ecbd7895e 100644 --- a/static/app/gettingStartedDocs/javascript-tanstackstart-react/onboarding.tsx +++ b/static/app/gettingStartedDocs/javascript-tanstackstart-react/onboarding.tsx @@ -200,8 +200,7 @@ Sentry.init({ }, { type: 'conditional', - condition: - params.platformOptions.serverPlatform === ServerPlatform.NODE, + condition: params.platformOptions.serverPlatform === ServerPlatform.NODE, content: [ { type: 'code', @@ -227,9 +226,7 @@ export default createServerEntry( }, { type: 'conditional', - condition: - params.platformOptions.serverPlatform === - ServerPlatform.SERVERLESS, + condition: params.platformOptions.serverPlatform === ServerPlatform.SERVERLESS, content: [ { type: 'code', @@ -304,8 +301,7 @@ export default defineConfig({ }, { type: 'conditional', - condition: - params.platformOptions.serverPlatform === ServerPlatform.NODE, + condition: params.platformOptions.serverPlatform === ServerPlatform.NODE, content: [ { type: 'text', From b2b0efd0b2463a0afc2e3ff195fb0702884f9d4a Mon Sep 17 00:00:00 2001 From: Nicolas Hrubec Date: Fri, 27 Feb 2026 14:15:49 +0100 Subject: [PATCH 3/5] no guide just pointer to docs --- .../javascript-tanstackstart-react/index.tsx | 5 +- .../onboarding.tsx | 189 ++++++------------ 2 files changed, 68 insertions(+), 126 deletions(-) diff --git a/static/app/gettingStartedDocs/javascript-tanstackstart-react/index.tsx b/static/app/gettingStartedDocs/javascript-tanstackstart-react/index.tsx index da38760c94547e..1b933bd2d56084 100644 --- a/static/app/gettingStartedDocs/javascript-tanstackstart-react/index.tsx +++ b/static/app/gettingStartedDocs/javascript-tanstackstart-react/index.tsx @@ -5,11 +5,10 @@ import {metricsFullStack} from 'sentry/gettingStartedDocs/javascript/metrics'; import {profilingFullStack} from 'sentry/gettingStartedDocs/javascript/profiling'; import {mcp} from './mcp'; -import {onboarding, platformOptions, type PlatformOptions} from './onboarding'; +import {onboarding} from './onboarding'; -const docs: Docs = { +const docs: Docs = { onboarding, - platformOptions, profilingOnboarding: profilingFullStack({ packageName: '@sentry/tanstackstart-react', browserProfilingLink: diff --git a/static/app/gettingStartedDocs/javascript-tanstackstart-react/onboarding.tsx b/static/app/gettingStartedDocs/javascript-tanstackstart-react/onboarding.tsx index a2e43ecbd7895e..c0490b2b2a0a09 100644 --- a/static/app/gettingStartedDocs/javascript-tanstackstart-react/onboarding.tsx +++ b/static/app/gettingStartedDocs/javascript-tanstackstart-react/onboarding.tsx @@ -1,31 +1,10 @@ import {ExternalLink} from '@sentry/scraps/link'; -import type { - BasePlatformOptions, - OnboardingConfig, -} from 'sentry/components/onboarding/gettingStartedDoc/types'; +import type {OnboardingConfig} from 'sentry/components/onboarding/gettingStartedDoc/types'; import {StepType} from 'sentry/components/onboarding/gettingStartedDoc/types'; import {t, tct} from 'sentry/locale'; -export enum ServerPlatform { - NODE = 'node', - SERVERLESS = 'serverless', -} - -export const platformOptions = { - serverPlatform: { - label: t('Server Platform'), - items: [ - {label: t('Node.js Server'), value: ServerPlatform.NODE}, - {label: t('Serverless'), value: ServerPlatform.SERVERLESS}, - ], - defaultValue: ServerPlatform.NODE, - }, -} satisfies BasePlatformOptions; - -export type PlatformOptions = typeof platformOptions; - -export const onboarding: OnboardingConfig = { +export const onboarding: OnboardingConfig = { introduction: () => t("In this guide you'll set up the Sentry TanStack Start React SDK"), install: () => [ @@ -181,53 +160,41 @@ Sentry.init({ ], }, { - type: 'text', + type: 'alert', + alertType: 'warning', + showIcon: true, text: tct( - 'To capture server-side errors and traces, explicitly define a [serverEntryLink:server entry point] in your application and wrap your request handler with [code:wrapFetchWithSentry].', + "If you can't use the [code:--import] flag (e.g. in serverless environments like Vercel or Netlify), follow the [link:TanStack Start React guide] for alternative setup instructions.", { code: , - serverEntryLink: ( - + link: ( + ), } ), }, - { - type: 'text', - text: tct('Create a [code:src/server.ts] file in your project:', { - code: , - }), - }, { type: 'conditional', - condition: params.platformOptions.serverPlatform === ServerPlatform.NODE, + condition: params.isPerformanceSelected, content: [ { - type: 'code', - tabs: [ + type: 'text', + text: tct( + 'To enable tracing for server-side requests, you need to explicitly define a [serverEntryLink:server entry point] in your application and wrap your request handler with [code:wrapFetchWithSentry].', { - label: 'TypeScript', - language: 'typescript', - filename: 'src/server.ts', - code: `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); - }, - }) -);`, - }, - ], + code: , + serverEntryLink: ( + + ), + } + ), + }, + { + type: 'text', + text: tct('Create a [code:src/server.ts] file in your project:', { + code: , + }), }, - ], - }, - { - type: 'conditional', - condition: params.platformOptions.serverPlatform === ServerPlatform.SERVERLESS, - content: [ { type: 'code', tabs: [ @@ -235,9 +202,7 @@ export default createServerEntry( label: 'TypeScript', language: 'typescript', filename: 'src/server.ts', - code: `import "../instrument.server.mjs"; - -import { wrapFetchWithSentry } from "@sentry/tanstackstart-react"; + code: `import { wrapFetchWithSentry } from "@sentry/tanstackstart-react"; import handler, { createServerEntry } from "@tanstack/react-start/server-entry"; export default createServerEntry( @@ -250,22 +215,6 @@ export default createServerEntry( }, ], }, - { - type: 'alert', - alertType: 'warning', - showIcon: true, - text: t( - 'When using the serverless setup, only native Node.js APIs will be instrumented (e.g. http, fetch). Database calls, queues, ORMs, and other third-party library instrumentation will not work.' - ), - }, - { - type: 'alert', - alertType: 'warning', - showIcon: true, - text: t( - 'Cloudflare is currently not supported by the Sentry TanStack Start SDK.' - ), - }, ], }, { @@ -300,69 +249,63 @@ export default defineConfig({ ], }, { - type: 'conditional', - condition: params.platformOptions.serverPlatform === ServerPlatform.NODE, - content: [ + type: 'text', + text: tct( + 'For production monitoring, you need to move the Sentry server config file to your build output. Since [hostingLink:TanStack Start is designed to work with any hosting provider], the exact location will depend on where your build artifacts are deployed (for example, [code:/dist], [code:.output/server] or a platform-specific directory).', { - type: 'text', - text: tct( - 'For production monitoring, you need to move the Sentry server config file to your build output. Since [hostingLink:TanStack Start is designed to work with any hosting provider], the exact location will depend on where your build artifacts are deployed (for example, [code:/dist], [code:.output/server] or a platform-specific directory).', - { - code: , - hostingLink: ( - - ), - } + code: , + hostingLink: ( + ), - }, + } + ), + }, + { + type: 'text', + text: tct( + 'For example, when using [nitroLink:Nitro], copy the instrumentation file to [code:.output/server]:', { - type: 'text', - text: tct( - 'For example, when using [nitroLink:Nitro], copy the instrumentation file to [code:.output/server]:', - { - code: , - nitroLink: , - } - ), - }, + code: , + nitroLink: , + } + ), + }, + { + type: 'code', + tabs: [ { - type: 'code', - tabs: [ - { - label: 'JSON', - language: 'json', - filename: 'package.json', - code: `{ + label: 'JSON', + language: 'json', + filename: 'package.json', + code: `{ "scripts": { "build": "vite build && cp instrument.server.mjs .output/server", } }`, - }, - ], - }, - { - type: 'text', - text: tct( - 'Add a [code:--import] flag directly or to the [code:NODE_OPTIONS] environment variable wherever you run your application to import [code:instrument.server.mjs]:', - {code: } - ), }, + ], + }, + { + type: 'text', + text: tct( + 'Add a [code:--import] flag directly or to the [code:NODE_OPTIONS] environment variable wherever you run your application to import [code:instrument.server.mjs]:', + {code: } + ), + }, + { + type: 'code', + tabs: [ { - type: 'code', - tabs: [ - { - label: 'JSON', - language: 'json', - filename: 'package.json', - code: `{ + label: 'JSON', + language: 'json', + filename: 'package.json', + code: `{ "scripts": { "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", } }`, - }, - ], }, ], }, From 45f126b9b8f89e16f08151e38a0585e6a3d55fbb Mon Sep 17 00:00:00 2001 From: Nicolas Hrubec Date: Fri, 27 Feb 2026 14:19:23 +0100 Subject: [PATCH 4/5] always add server entry point --- .../onboarding.tsx | 50 ++++++++----------- 1 file changed, 22 insertions(+), 28 deletions(-) diff --git a/static/app/gettingStartedDocs/javascript-tanstackstart-react/onboarding.tsx b/static/app/gettingStartedDocs/javascript-tanstackstart-react/onboarding.tsx index c0490b2b2a0a09..3e3dbd3f30c2eb 100644 --- a/static/app/gettingStartedDocs/javascript-tanstackstart-react/onboarding.tsx +++ b/static/app/gettingStartedDocs/javascript-tanstackstart-react/onboarding.tsx @@ -174,35 +174,31 @@ Sentry.init({ ), }, { - type: 'conditional', - condition: params.isPerformanceSelected, - content: [ + type: 'text', + text: tct( + 'To capture server-side errors and traces, explicitly define a [serverEntryLink:server entry point] in your application and wrap your request handler with [code:wrapFetchWithSentry].', { - type: 'text', - text: tct( - 'To enable tracing for server-side requests, you need to explicitly define a [serverEntryLink:server entry point] in your application and wrap your request handler with [code:wrapFetchWithSentry].', - { - code: , - serverEntryLink: ( - - ), - } + code: , + serverEntryLink: ( + ), - }, - { - type: 'text', - text: tct('Create a [code:src/server.ts] file in your project:', { - code: , - }), - }, + } + ), + }, + { + type: 'text', + text: tct('Create a [code:src/server.ts] file in your project:', { + code: , + }), + }, + { + type: 'code', + tabs: [ { - type: 'code', - tabs: [ - { - label: 'TypeScript', - language: 'typescript', - filename: 'src/server.ts', - code: `import { wrapFetchWithSentry } from "@sentry/tanstackstart-react"; + label: 'TypeScript', + language: 'typescript', + filename: 'src/server.ts', + code: `import { wrapFetchWithSentry } from "@sentry/tanstackstart-react"; import handler, { createServerEntry } from "@tanstack/react-start/server-entry"; export default createServerEntry( @@ -212,8 +208,6 @@ export default createServerEntry( }, }) );`, - }, - ], }, ], }, From 656c2f1d0df8c9609cc7e3923c3a4e74976853b7 Mon Sep 17 00:00:00 2001 From: Nicolas Hrubec Date: Fri, 27 Feb 2026 14:44:54 +0100 Subject: [PATCH 5/5] update link --- .../javascript-tanstackstart-react/onboarding.tsx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/static/app/gettingStartedDocs/javascript-tanstackstart-react/onboarding.tsx b/static/app/gettingStartedDocs/javascript-tanstackstart-react/onboarding.tsx index 3e3dbd3f30c2eb..15aecf6be93113 100644 --- a/static/app/gettingStartedDocs/javascript-tanstackstart-react/onboarding.tsx +++ b/static/app/gettingStartedDocs/javascript-tanstackstart-react/onboarding.tsx @@ -168,7 +168,7 @@ Sentry.init({ { code: , link: ( - + ), } ),