Skip to content

docs: update TanStack Start guide for RC APIs #1275

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
juliusmarminge wants to merge 3 commits into
base: main
Choose a base branch
from
+29 −26
Open

docs: update TanStack Start guide for RC APIs #1275

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
c67b423
docs: update TanStack Start guide for RC APIs
cursoragent Apr 12, 2026
4d858db
docs: format TanStack Start guide update
cursoragent Apr 12, 2026
edea732
docs: remove redundant TanStack Start note
cursoragent Apr 12, 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
55 changes: 29 additions & 26 deletions docs/src/app/(docs)/getting-started/tanstack-start/page.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
import { docsMetadata } from "@/lib/utils";

export const metadata = docsMetadata({
title: "Tanstack/Start Setup",
description: "Learn how to set up a Tanstack/Start project with UploadThing",
title: "TanStack Start Setup",
description: "Learn how to set up a TanStack Start project with UploadThing",
category: "Getting Started",
});

# Getting Started with Tanstack/Start
# Getting Started with TanStack Start

## Package Setup

Expand All @@ -29,9 +29,9 @@ UPLOADTHING_TOKEN=... # A token for interacting with the SDK
</Warning>

<Note>
Tanstack Start is currently in beta, this guide works at the time of writing
(`v1.95.0`) but there might be some breaking changes introduced in the
framework that we have not kept up to date with.
TanStack Start is currently in release candidate (RC). The APIs in this guide
match the current v1 RC server-route conventions, but may still change before
1.0.
</Note>

## Set Up A FileRouter
Expand All @@ -52,7 +52,7 @@ of a FileRoute similar to an endpoint, it has:
To get full insight into what you can do with the FileRoutes, please refer to
the [File Router API](/file-routes).

```ts {{ title: "app/server/uploadthing.ts" }}
```ts {{ title: "src/server/uploadthing.ts" }}
import { createUploadthing, UploadThingError } from "uploadthing/server";
import type { FileRouter } from "uploadthing/server";

Expand Down Expand Up @@ -101,28 +101,31 @@ export type UploadRouter = typeof uploadRouter;
### Create an API route using the FileRouter

<Note>
File path here doesn't matter, you can serve this from any route. We recommend
serving it from `/api/uploadthing`.
TanStack Start server routes can live anywhere under `src/routes`, but this
guide uses `src/routes/api/uploadthing.ts` so the endpoint is served from
`/api/uploadthing`.
</Note>

<Warning>
Make sure to configure API entry handler in `app/api.ts`. For more
information, please refer to the [@tanstack/start
docs](https://tanstack.com/router/latest/docs/framework/react/start/api-routes#setting-up-the-entry-handler).
</Warning>

```ts {{ title: "app/routes/api/uploadthing.ts" }}
import { createAPIFileRoute } from "@tanstack/start/api";
```ts {{ title: "src/routes/api/uploadthing.ts" }}
import { createFileRoute } from "@tanstack/react-router";

import { createRouteHandler } from "uploadthing/server";

import { uploadRouter } from "../../server/uploadthing";
Comment on lines 103 to 114
Copy link
Copy Markdown

@greptile-apps greptile-apps Bot Apr 12, 2026

Choose a reason for hiding this comment

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

P2 Redundant consecutive <Note> blocks

Both notes explain the same thing: TanStack Start server routes live in src/routes and src/routes/api/uploadthing.ts maps to /api/uploadthing. The first is fully redundant once the second is present (the second adds the external docs link). Consider collapsing them into one:

Suggested change
<Note>
File path here doesn't matter, you can serve this from any route. We recommend
serving it from `/api/uploadthing`.
TanStack Start server routes can live anywhere under `src/routes`, but this
guide uses `src/routes/api/uploadthing.ts` so the endpoint is served from
`/api/uploadthing`.
</Note>
<Warning>
Make sure to configure API entry handler in `app/api.ts`. For more
information, please refer to the [@tanstack/start
docs](https://tanstack.com/router/latest/docs/framework/react/start/api-routes#setting-up-the-entry-handler).
</Warning>
```ts {{ title: "app/routes/api/uploadthing.ts" }}
import { createAPIFileRoute } from "@tanstack/start/api";
```ts {{ title: "src/routes/api/uploadthing.ts" }}
import { createFileRoute } from "@tanstack/react-router";
import { createRouteHandler } from "uploadthing/server";
import { uploadRouter } from "../../server/uploadthing";
<Note>
TanStack Start server routes live directly in your `src/routes` tree, so
`src/routes/api/uploadthing.ts` automatically serves `/api/uploadthing`. For
more information, please refer to the [TanStack Start server-routes
docs](https://tanstack.com/start/latest/docs/framework/react/guide/server-routes).
</Note>

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!


const handlers = createRouteHandler({ router: uploadRouter });

export const Route = createAPIFileRoute("/api/uploadthing")({
GET: handlers,
POST: handlers,
const handler = createRouteHandler({ router: uploadRouter });

export const Route = createFileRoute("/api/uploadthing")({
server: {
handlers: {
GET: async ({ request }) => {
return handler(request);
},
POST: async ({ request }) => {
return handler(request);
},
},
},
});
Comment on lines +116 to 136
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot Apr 12, 2026

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "== TanStack Start route API usage in docs/examples =="
rg -n -C2 --type=mdx --type=ts --type=tsx \
  'createServerFileRoute|createAPIFileRoute|createFileRoute\(|server:\s*\{|\.methods\(|export const ServerRoute|export const Route' \
  docs examples

echo
echo "== TanStack package references in repository manifests =="
rg -n --glob '**/package.json' \
  '"@tanstack/react-router"|"@tanstack/react-start"'

Repository: pingdotgg/uploadthing

Length of output: 163

🏁 Script executed:

# Search for TanStack route patterns in docs and examples with corrected approach
find docs examples -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.mdx" \) | head -20

Repository: pingdotgg/uploadthing

Length of output: 1024

🏁 Script executed:

# Look at the specific files mentioned in the review
echo "=== Docs file (page.mdx) ===" 
find docs -name "*tanstack*" -o -name "*page.mdx" | grep -i tanstack

echo -e "\n=== Examples file ===" 
find examples -path "*tanstack*" -name "*.ts"

Repository: pingdotgg/uploadthing

Length of output: 504

🏁 Script executed:

# Check TanStack Start package version
rg '"@tanstack/react-start"' --glob='**/package.json' -A 1 -B 1

Repository: pingdotgg/uploadthing

Length of output: 319

🏁 Script executed:

# Read the docs snippet mentioned in the review (lines 116-136)
sed -n '110,145p' docs/src/app/(docs)/getting-started/tanstack-start/page.mdx | cat -n

Repository: pingdotgg/uploadthing

Length of output: 238

🏁 Script executed:

# Read the examples file that's being compared
cat -n examples/minimal-tanstack-start/src/routes/api.uploadthing.ts

Repository: pingdotgg/uploadthing

Length of output: 514

🏁 Script executed:

# Read the docs file with proper escaping
cat -n "docs/src/app/(docs)/getting-started/tanstack-start/page.mdx" | sed -n '110,145p'

Repository: pingdotgg/uploadthing

Length of output: 1283

🏁 Script executed:

# Search for other TanStack Start route patterns in the codebase
rg -n "createServerFileRoute|createFileRoute.*server.*handlers" examples/minimal-tanstack-start/

Repository: pingdotgg/uploadthing

Length of output: 341

🏁 Script executed:

# Check if there's any documentation about the API differences or version requirements
find docs -name "*.mdx" -type f -exec grep -l "tanstack.*start\|react-start" {} \;

Repository: pingdotgg/uploadthing

Length of output: 47

🏁 Script executed:

# Look for any migration or compatibility notes in the tanstack-start example
find examples/minimal-tanstack-start -name "*.md" -o -name "README*"

Repository: pingdotgg/uploadthing

Length of output: 47

🏁 Script executed:

# Check all imports of createFileRoute and createServerFileRoute in the codebase
rg "import.*createFileRoute|import.*createServerFileRoute" --type ts --type tsx docs examples

Repository: pingdotgg/uploadthing

Length of output: 92

🏁 Script executed:

# Look for any other server route patterns in docs
rg "createServerFileRoute|ServerRoute" docs/ --type mdx

Repository: pingdotgg/uploadthing

Length of output: 92

🏁 Script executed:

# Check if there's a difference between `@tanstack/react-router` and `@tanstack/react-start` packages
rg "@tanstack/react-router|@tanstack/react-start" --glob="**/package.json" --context 2

Repository: pingdotgg/uploadthing

Length of output: 502

🏁 Script executed:

# Search without type filters for import patterns
rg "import.*createFileRoute|import.*createServerFileRoute" docs examples

Repository: pingdotgg/uploadthing

Length of output: 543

🏁 Script executed:

# Search for ServerRoute patterns
rg "ServerRoute" docs examples

Repository: pingdotgg/uploadthing

Length of output: 3079

🏁 Script executed:

# Check TanStack Start docs or example patterns in the example directory structure
ls -la "examples/minimal-tanstack-start/src/routes/" | head -20

Repository: pingdotgg/uploadthing

Length of output: 363

Align TanStack Start server route patterns across docs and examples.

The docs snippet uses createFileRoute from "@tanstack/react-router" with a server: { handlers } config object, while examples/minimal-tanstack-start/src/routes/api.uploadthing.ts uses createServerFileRoute from "@tanstack/react-start/server" with a .methods() chaining API. These are incompatible patterns from different packages. Align both or add explicit documentation clarifying which pattern is correct and when each should be used.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/src/app/`(docs)/getting-started/tanstack-start/page.mdx around lines 116
- 136, The docs example is using the wrong TanStack API pattern; replace the
createFileRoute + server.handlers pattern with the server route pattern used in
the example so it matches the examples/minimal-tanstack-start code: import and
use createServerFileRoute from "@tanstack/react-start/server", keep the same
createRouteHandler(handler) and uploadRouter, and expose Route via
createServerFileRoute("/api/uploadthing").methods({ GET: async ({ request }) =>
handler(request), POST: async ({ request }) => handler(request) }) so the
snippet uses createServerFileRoute, .methods(), Route, createRouteHandler, and
uploadRouter consistently with the example; alternatively add a short note above
the snippet explicitly stating the difference between createFileRoute
(client-side react-router) and createServerFileRoute (server-side react-start)
and when to use each.

```

Expand All @@ -135,7 +138,7 @@ We provide components to make uploading easier. We highly recommend re-exporting
them with the types assigned, but you CAN import the components individually
from `@uploadthing/react` instead.

```ts {{ title: "app/utils/uploadthing.ts" }}
```ts {{ title: "src/utils/uploadthing.ts" }}
import {
generateReactHelpers,
generateUploadButton,
Expand Down Expand Up @@ -189,7 +192,7 @@ export const { useUploadThing } = generateReactHelpers<UploadRouter>();
<Tab>
Include our CSS file in the root layout to make sure the components look right!

```tsx {{ title: "app/routes/__root.tsx" }}
```tsx {{ title: "src/routes/__root.tsx" }}
import uploadthingCss from "@uploadthing/react/styles.css?url";

export const Route = createRootRoute({
Expand All @@ -204,12 +207,12 @@ export const { useUploadThing } = generateReactHelpers<UploadRouter>();

## Mount A Button And Upload!

```tsx {{ title: "app/routes/index.tsx" }}
```tsx {{ title: "src/routes/index.tsx" }}
import { createFileRoute } from "@tanstack/react-router";

import { UploadButton } from "../utils/uploadthing";

export const APIRoute = createFileRoute("/")({
export const Route = createFileRoute("/")({
component: Home,
});

Expand Down
Loading