Skip to content

docs(cloudflare): Add TanStack Start on Cloudflare docs #17595

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
JPeer264 wants to merge 2 commits into
base: master
Choose a base branch
from
+215 −1
Open

docs(cloudflare): Add TanStack Start on Cloudflare docs #17595

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
59007ca
docs(cloudflare): Add TanStack Start on Cloudflare docs
JPeer264 May 4, 2026
9e29162
fixup! docs(cloudflare): Add TanStack Start on Cloudflare docs
JPeer264 May 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
213 changes: 213 additions & 0 deletions docs/platforms/javascript/guides/cloudflare/frameworks/tanstack-start.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,213 @@
---
title: TanStack Start on Cloudflare
description: "Learn how to instrument your TanStack Start app on Cloudflare Workers and capture your first errors with Sentry."
---

<PlatformContent includePath="getting-started-primer" />

<Alert level="warning">

This guide is for TanStack Start deployed to **Cloudflare Workers** using the `@cloudflare/vite-plugin`. For Node.js-based deployments, see our [TanStack Start guide](/platforms/javascript/guides/tanstackstart-react/).

</Alert>

<StepConnector selector="h2" showNumbers={true}>

## Install

Choose the features you want to configure, and this guide will show you how:

<OnboardingOptionButtons
options={["error-monitoring", "performance", "logs"]}
Copy link
Copy Markdown
Contributor

@sfanahata sfanahata May 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we also include session replay and user feedback? They seem to be referenced in other Cloudflare frameworks.

/>

<Include name="quick-start-features-expandable" />
Copy link
Copy Markdown
Contributor

@sfanahata sfanahata May 4, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this be the cloudflare specific include? quick-start-features-expandable-cloudflare-frameworks


### Install the Sentry SDK

<SplitLayout>
<SplitSection>
<SplitSectionText>

Run the command for your preferred package manager to add the Sentry SDK to your application:

</SplitSectionText>
<SplitSectionCode>

<PlatformContent includePath="getting-started-install" />

</SplitSectionCode>
</SplitSection>
</SplitLayout>

## Configure

When deploying TanStack Start to Cloudflare Workers, you need to wrap the server entry point with `Sentry.withSentry` from `@sentry/cloudflare`. TanStack Start allows you to create a custom server entry file for this purpose.

### Wrangler Configuration

<PlatformContent
includePath="getting-started-config"
platform="javascript.cloudflare.splitlayout"
/>

### Create a Custom Server Entry

<SplitLayout>
<SplitSection>
<SplitSectionText>

Create a `src/server.ts` file that wraps the TanStack Start handler with Sentry:

</SplitSectionText>
<SplitSectionCode>

```typescript {filename:src/server.ts}
import * as Sentry from "@sentry/cloudflare";
import handler from "@tanstack/react-start/server-entry";

export default Sentry.withSentry(
(env) => ({
dsn: env.SENTRY_DSN,
Copy link
Copy Markdown
Contributor

@sfanahata sfanahata May 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we usually use "___PUBLIC_DSN___", yeah?

// Adds request headers and IP for users, for more info visit:
// https://docs.sentry.io/platforms/javascript/guides/cloudflare/configuration/options/#sendDefaultPii
sendDefaultPii: true,
// ___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 spans for tracing.
tracesSampleRate: 1.0,
// ___PRODUCT_OPTION_END___ performance
}),
handler
);
```

</SplitSectionCode>
</SplitSection>
</SplitLayout>

### Update Wrangler Configuration

<SplitLayout>
<SplitSection>
<SplitSectionText>

Update your `wrangler.jsonc` (or `wrangler.toml`) to use your custom server entry:

</SplitSectionText>
<SplitSectionCode>

```json {diff} {filename:wrangler.jsonc}
{
"name": "my-tanstack-app",
+ "main": "src/server.ts",
// ... rest of config
}
```

</SplitSectionCode>
</SplitSection>
</SplitLayout>

### Configure Client-Side Sentry

<SplitLayout>
<SplitSection>
<SplitSectionText>

Initialize Sentry in your `src/router.tsx` file for client-side error tracking:

</SplitSectionText>
<SplitSectionCode>

```tsx {diff} {filename:src/router.tsx}
+import * as Sentry from "@sentry/tanstackstart-react";
import { createRouter } from '@tanstack/react-router'

export const getRouter = () => {
const router = createRouter();

+ if (!router.isServer) {
+ Sentry.init({
+ dsn: "___PUBLIC_DSN___",
+ integrations: [
+ // ___PRODUCT_OPTION_START___ performance
+ Sentry.browserTracingIntegration(),
Copy link
Copy Markdown

@sentry sentry Bot May 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Bug: The guide uses the generic Sentry.browserTracingIntegration() instead of the required Sentry.tanstackRouterBrowserTracingIntegration(router), leading to incorrect performance tracing for navigation.
Severity: MEDIUM

Suggested Fix

Replace Sentry.browserTracingIntegration() with Sentry.tanstackRouterBrowserTracingIntegration(router), passing the router instance to the function. This will correctly instrument TanStack Router's navigation events.

Prompt for AI Agent 
Review the code at the location below. A potential bug has been identified by an AI
agent. Verify if this is a real issue. If it is, propose a fix; if not, explain why it's
not valid.

Location: docs/platforms/javascript/guides/cloudflare/frameworks/tanstack-start.mdx#L140

Potential issue: The TanStack Start on Cloudflare guide incorrectly uses the generic
`Sentry.browserTracingIntegration()` for client-side performance tracing. The correct
integration for this framework is
`Sentry.tanstackRouterBrowserTracingIntegration(router)`, which is necessary to properly
instrument TanStack Router's navigation lifecycle events. Using the generic integration
will result in missing or incorrectly named `pageload/navigation` transactions for
client-side route changes, leading to degraded performance monitoring for users
following this guide.

Did we get this right? 👍 / 👎 to inform future reviews.

Copy link
Copy Markdown
Contributor

@sfanahata sfanahata May 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@JPeer264 - is this correct?

+ // ___PRODUCT_OPTION_END___ performance
+ ],
+ // ___PRODUCT_OPTION_START___ performance
+ tracesSampleRate: 1.0,
+ // ___PRODUCT_OPTION_END___ performance
+ });
+ }
Comment on lines +136 to +147
Copy link
Copy Markdown
Contributor

@sfanahata sfanahata May 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we include any of: sendDefaultPii: true, enableLogs: true (under logs option), Sentry.replayIntegration() (under session-replay option), Sentry.feedbackIntegration() (under user-feedback option), replaysSessionSampleRate/replaysOnErrorSampleRate.

Looks like other Cloudflare guides include them.


return router;
}
```

</SplitSectionCode>
</SplitSection>
</SplitLayout>

Copy link
Copy Markdown
Member

@nicohrubec nicohrubec May 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

m: I think we should also put in here how to set up server side error capturing with the sentry middlewares?

### Add Readable Stack Traces With Source Maps (Optional)

<PlatformContent
includePath="getting-started-sourcemaps-short-version-splitlayout"
platform="javascript"
/>

## Verify Your Setup

<SplitLayout>
<SplitSection>
<SplitSectionText>

To verify Sentry is capturing errors, add a test button to one of your pages:

</SplitSectionText>
<SplitSectionCode>

```tsx
<button
type="button"
onClick={() => {
throw new Error("Sentry Test Error");
}}
>
Break the world
</button>
```

</SplitSectionCode>
</SplitSection>
</SplitLayout>

Run your app with `wrangler dev` (or through your Vite build with Cloudflare plugin), click the button, and check your Sentry project for the error.

<Include name="quick-start-locate-data-expandable" />

## Next Steps

At this point, you should have integrated Sentry and should already be sending data to your Sentry project.

Now's a good time to customize your setup and look into more advanced topics. Our next recommended steps for you are:

- Learn how to [manually capture errors](/platforms/javascript/guides/cloudflare/usage/)
- Continue to [customize your configuration](/platforms/javascript/guides/cloudflare/configuration/)
- Make use of [Cloudflare-specific features](/platforms/javascript/guides/cloudflare/features)
- Get familiar with [Sentry's product features](/product) like tracing, insights, and alerts

<Expandable permalink={false} title="Are you having problems setting up the SDK?">

- Check out setup instructions for other popular [frameworks on Cloudflare](/platforms/javascript/guides/cloudflare/frameworks/)
- Find various support topics in <PlatformLink to="/troubleshooting">troubleshooting</PlatformLink>
- [Get support](https://sentry.zendesk.com/hc/en-us/)

</Expandable>

</StepConnector>
1 change: 1 addition & 0 deletions docs/platforms/javascript/guides/cloudflare/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ Use this guide for general instructions on using the Sentry SDK with Cloudflare.
- **[Nuxt](/platforms/javascript/guides/cloudflare/frameworks/nuxt/)**
- **[Remix](/platforms/javascript/guides/cloudflare/frameworks/remix/)**
- **[SvelteKit](/platforms/javascript/guides/cloudflare/frameworks/sveltekit/)**
- **[TanStack Start](/platforms/javascript/guides/cloudflare/frameworks/tanstack-start/)**

<Alert>
The Cloudflare Workers runtime has some platform-specific limitations that
Expand Down
2 changes: 1 addition & 1 deletion docs/platforms/javascript/guides/tanstackstart-react/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -332,7 +332,7 @@ You can only instrument native Node.js APIs (such as `fetch` and the `http` modu
This means that the Sentry SDK will not capture data from database calls, queues, ORMs, third-party libraries, or other framework-specific data.
Thus, we recommend you follow the [`--import` flag setup instructions](#with---import-flag-eg-nodejs-server) if possible.

This setup doesn't work for Cloudflare deployments.
For Cloudflare Workers deployments, see our [TanStack Start on Cloudflare](/platforms/javascript/guides/cloudflare/frameworks/tanstack-start/) guide.

</Alert>

Expand Down
Loading