tanstack-better-upload

name	tanstack-better-upload
description	Direct-to-S3 uploads in TanStack Start with @better-upload/server and @better-upload/client (presigned PUT, API route POST handlers, useUploadFiles/useUploadFile, S3 object helpers). Optional react-dropzone add-on only for multi-file drag-and-drop UX. Use for upload API routes, presigned S3, upload progress, post-upload DB persistence, or the dropzone component stack.

Better Upload (TanStack Start)

@better-upload/server + @better-upload/client — presigned direct-to-S3 uploads via TanStack Start POST handlers and useUploadFiles / useUploadFile.

react-dropzone — optional FMC add-on for drag-and-drop multi-file UX. Add it only when the product needs that interaction (multipleFiles, batch progress). Single-file button/picker flows use Better Upload hooks alone — no dropzone dependency.

Upstream (Better Upload): llms-full.txt · quickstart

When to apply

Better Upload (always relevant for uploads):

• New upload endpoint under routes/api/
• useUploadFiles / useUploadFile and upload progress
• S3 object helpers (getObject, deleteObject, presignGetObject, putObject) via Better Upload — not raw @aws-sdk/client-s3
• Post-upload DB records via createServerFn + TanStack Query

react-dropzone (only when UX needs it):

• Drag-and-drop multi-file dropzone with batch progress
• FMC UploadDropzone* component stack

Single-file pickers, plain <input>, and paste areas call upload() directly — no react-dropzone. Details: dropzone-ui.md.

Architecture (FMC)

Client                          Server API route                 S3
──────                          ────────────────                 ──
file picker / dropzone* onDrop
  → useUploadFiles.upload()  →  handleRequest(router)       →  PUT presigned
  → onUploadComplete         →  onBeforeUpload (auth, keys)
  → create*Fn (server fn)    →  (separate RPC, not Better Upload)
  → invalidate queries

* dropzone = optional react-dropzone layer (multi-file drag-and-drop only)

Two phases: bytes to S3, then app DB row via server function. See troubleshooting.md.

References (read as needed)

Situation	File
First-time setup — packages, env, CORS, API route, smoke test	first-time-setup.md
Server Router, route(), onBeforeUpload, metadata	server-router.md
useUploadFiles, events, DB payload after complete	client-hooks.md
Optional multi-file dropzone UI (react-dropzone)	dropzone-ui.md
getObject, deleteObject, presignGetObject, S3 client policy	s3-helpers.md
Serving uploads (GET proxy, <img> previews, dev Vite plugin)	serving-uploads.md
Errors, anti-patterns, debugging	troubleshooting.md

Related skills

• tanstack-router-conventions — routes, search params (when wiring upload UI to URL state)
• tanstack-start-conventions — layout, .server.ts / .functions.ts, API route boundaries, SSR

Usage rules (daily work)

Topic	Rule
Route name	Client route: 'upload' must match routes: { upload: route({...}) }
API path	Client defaults to /api/upload; set api when the TanStack route differs
Handler	return handleRequest(request, router) — no Next.js adapter
Auth	Enforce in handler or onBeforeUpload; endpointAuth.inherited(...) when auth lives in handler
DB after upload	useMutation({ mutationFn: createUploadFn }) in onUploadComplete
Boundaries	Post-upload persistence in *.functions.ts + createServerFn; never import @better-upload/server in client components
S3 access	getConfiguredS3Client() (aws()) + @better-upload/server/helpers — not @aws-sdk/client-s3 unless helpers lack the op (s3-helpers.md)
Serve via API	GET /api/ routes for <img> / <video> previews need forwardApiRequestsPastViteAssetMiddleware() in vite.config.ts (dev only) — serving-uploads.md

For setup steps and checklists, start with first-time-setup.md.