You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 6fbbd73
Browse filesBrowse the repository at this point in the historyBrowse files
docs(skills): drop wrong-import-path mistakes — TS already catches them
Manuel pointed out that TypeScript catches both common wrong paths:
'@tanstack/react-router' has no exported member createServerFn /
createMiddleware, and '@tanstack/start' is "Cannot find module". Skill
space is precious; the items don't earn their slot if tsc handles them.
Removed:
- Common Mistake "Wrong import path" from server-functions and
middleware skills (renumbered the remaining mistakes)
- The matching top-of-file CRITICAL line in both skills
- The "Import path" callouts in the middleware and server-functions
docs
Copy file name to clipboardExpand all lines: docs/start/framework/react/guide/middleware.md
-2Lines changed: 0 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,8 +7,6 @@ title: Middleware
7
7
8
8
Middleware allows you to customize the behavior of both server routes like GET/POST/etc (including requests to SSR your application) and server functions created with `createServerFn`. Middleware is composable and can even depend on other middleware to create a chain of operations that are executed hierarchically and in order.
9
9
10
-
> **Import path**: `createMiddleware` (and `createStart`) are exported from `@tanstack/react-start`. They are **not** exported from `@tanstack/react-router`, and there is no `@tanstack/start` package — wrong paths fail at runtime with `createMiddleware is not a function`.
11
-
12
10
### What kinds of things can I do with Middleware?
13
11
14
12
-**Authentication**: Verify a user's identity before executing a server function.
Copy file name to clipboardExpand all lines: docs/start/framework/react/guide/server-functions.md
-2Lines changed: 0 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,8 +7,6 @@ title: Server Functions
7
7
8
8
Server functions let you define server-only logic that can be called from anywhere in your application - loaders, components, hooks, or other server functions. They run on the server but can be invoked from client code seamlessly.
9
9
10
-
> **Import path**: `createServerFn` is exported from `@tanstack/react-start`. It is **not** exported from `@tanstack/react-router`, and there is no `@tanstack/start` package — both common wrong paths fail at runtime with `createServerFn is not a function`.
Copy file name to clipboardExpand all lines: packages/start-client-core/skills/start-core/middleware/SKILL.md
+4-23Lines changed: 4 additions & 23 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -20,7 +20,6 @@ sources:
20
20
21
21
Middleware customizes the behavior of server functions and server routes. It is composable — middleware can depend on other middleware to form a chain.
22
22
23
-
> **CRITICAL**: Import `createMiddleware` from `@tanstack/<framework>-start` (e.g. `@tanstack/react-start`). NOT from `@tanstack/react-router` and NOT from `@tanstack/start` (no such package). Wrong path produces `createMiddleware is not a function`.
24
23
> **CRITICAL**: TypeScript enforces method order: `middleware()` → `inputValidator()` → `client()` → `server()`. Wrong order causes type errors.
25
24
> **CRITICAL**: Validating the _shape_ of `sendContext` (e.g. `z.string().uuid().parse(...)`) is NOT authorization. A parsed identifier is a well-formed identifier, not an authorized one. Always re-check access against the session principal before using a client-sent ID as a query key, filter, or path parameter.
26
25
@@ -304,25 +303,7 @@ Fetch precedence (highest to lowest): call site → later middleware → earlier
304
303
305
304
## Common Mistakes
306
305
307
-
### 1. HIGH: Wrong import path for `createMiddleware`
308
-
309
-
`createMiddleware` lives in the framework-scoped Start package, not in the router or a non-existent generic `@tanstack/start`. The wrong path looks plausible but throws `createMiddleware is not a function` at runtime.
Same applies to `createStart` and other Start runtime exports.
324
-
325
-
### 2. CRITICAL: Trusting client sendContext — shape check is not access check
306
+
### 1. CRITICAL: Trusting client sendContext — shape check is not access check
326
307
327
308
`sendContext` from a client middleware arrives on the server as untrusted client input. Most agents stop after parsing the shape with Zod and assume the value is safe. It isn't: a parsed UUID is _some_ workspace, not the requesting user's workspace. Without a membership check against the session principal, you've built a tenant-walking endpoint.
328
309
@@ -366,11 +347,11 @@ Same applies to `createStart` and other Start runtime exports.
366
347
367
348
The session itself must come from a server-trusted source (the cookie + DB lookup in `authMiddleware`), never from `sendContext` — anything the client can send, the client can lie about. See [start-core/auth-server-primitives](../auth-server-primitives/SKILL.md).
368
349
369
-
### 3. MEDIUM: Confusing request vs server function middleware
350
+
### 2. MEDIUM: Confusing request vs server function middleware
370
351
371
352
Request middleware runs on ALL requests (SSR, routes, functions). Server function middleware runs only for `createServerFn` calls and has `.client()` method.
372
353
373
-
### 4. HIGH: Browser APIs in .client() crash during SSR
354
+
### 3. HIGH: Browser APIs in .client() crash during SSR
374
355
375
356
During SSR, `.client()` callbacks run on the server. Browser-only APIs like `localStorage` or `window` will throw `ReferenceError`:
Copy file name to clipboardExpand all lines: packages/start-client-core/skills/start-core/server-functions/SKILL.md
+7-26Lines changed: 7 additions & 26 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -19,7 +19,6 @@ sources:
19
19
20
20
Server functions are type-safe RPCs created with `createServerFn`. They run exclusively on the server but can be called from anywhere — loaders, components, hooks, event handlers, or other server functions.
21
21
22
-
> **CRITICAL**: Import `createServerFn` from `@tanstack/<framework>-start` (e.g. `@tanstack/react-start`). NOT from `@tanstack/react-router` and NOT from `@tanstack/start` (no such package). Wrong path produces `createServerFn is not a function`.
23
22
> **CRITICAL**: Server functions are RPC endpoints. They are reachable by direct POST regardless of which route renders the calling UI. **Auth must be enforced inside the handler (or via middleware) — a route `beforeLoad` does NOT protect the RPC.** See [start-core/auth-server-primitives](../auth-server-primitives/SKILL.md) for the session/middleware pattern.
24
23
> **CRITICAL**: Loaders are ISOMORPHIC — they run on BOTH client and server. Database queries, file system access, and secret API keys MUST go inside `createServerFn`, NOT in loaders directly.
25
24
> **CRITICAL**: Do not use `"use server"` directives, `getServerSideProps`, or any Next.js/Remix server patterns. TanStack Start uses `createServerFn` exclusively.
@@ -269,25 +268,7 @@ Static imports of server functions are safe — the build replaces implementatio
269
268
270
269
## Common Mistakes
271
270
272
-
### 1. HIGH: Wrong import path for `createServerFn`
273
-
274
-
`createServerFn` lives in the framework-scoped Start package, not in the router or a non-existent generic `@tanstack/start`. The wrong path looks plausible but throws `createServerFn is not a function` at runtime.
Server-context utilities (`getRequest`, `getRequestHeader`, `setResponseHeader`, etc.) live at `@tanstack/<framework>-start/server` — same framework prefix.
289
-
290
-
### 2. CRITICAL: Relying on a route guard to protect a server function
271
+
### 1. CRITICAL: Relying on a route guard to protect a server function
291
272
292
273
A `beforeLoad` redirect protects the **route's UI**, not the **RPC**. `createServerFn` exposes a callable endpoint that an attacker can hit directly — no need to load the route at all. Auth on the route is necessary but not sufficient.
Apply `authMiddleware` (or an equivalent in-handler check) to **every**`createServerFn` that needs auth. See [start-core/auth-server-primitives](../auth-server-primitives/SKILL.md) for the full session/middleware pattern and [start-core/middleware](../middleware/SKILL.md) for composing the factory.
315
296
316
-
### 3. CRITICAL: Putting server-only code in loaders
297
+
### 2. CRITICAL: Putting server-only code in loaders
317
298
318
299
```tsx
319
300
// WRONG — loader is ISOMORPHIC, runs on BOTH client and server
### 4. CRITICAL: Using Next.js / Remix / React Router DOM patterns
319
+
### 3. CRITICAL: Using Next.js / Remix / React Router DOM patterns
339
320
340
321
If the file lives at `src/pages/`, `app/layout.tsx`, `_app/`, or imports anything from `react-router-dom` or `next/`, it is wrong-framework code. TanStack Start uses `src/routes/` + `createFileRoute` + `createServerFn`.
If you see `src/pages/`, `app/layout.tsx`, or `react-router-dom` in agent output, the agent is generating for the wrong framework. Build will fail or routes will conflict at runtime.
### 6. HIGH: Awaiting server function without calling it
369
+
### 5. HIGH: Awaiting server function without calling it
389
370
390
371
`createServerFn` returns a function — it must be invoked with `()`:
391
372
@@ -400,7 +381,7 @@ const data = await getItems()
400
381
const data =awaitgetItems({ data: { id: '1' } })
401
382
```
402
383
403
-
### 7. CRITICAL: Caching authenticated responses with `Cache-Control: public`
384
+
### 6. CRITICAL: Caching authenticated responses with `Cache-Control: public`
404
385
405
386
`Cache-Control: public, max-age=N` tells every CDN, proxy, and shared cache between you and the user that this response can be served to anyone. If the response depends on the session (user, tenant, role), the first user's response gets cached and replayed to the next user — a cross-tenant data leak.
Rule of thumb: if the handler reads a session/cookie/auth header or branches on identity, the response is **not**`public`. Default to `private` (or `no-store` for sensitive data); reach for `public` only on responses that are byte-for-byte identical regardless of who asks. See also [start-core/deployment](../deployment/SKILL.md) for ISR/Cache-Control on full pages.
430
411
431
-
### 8. MEDIUM: When to wrap with `useServerFn`
412
+
### 7. MEDIUM: When to wrap with `useServerFn`
432
413
433
414
`useServerFn` is **required** when the server function uses `throw redirect()` or `throw notFound()` — the hook wires the throw into the router so the redirect actually navigates. For server functions that just return data (call them directly or via `useMutation`/`useQuery`), the hook is optional.
0 commit comments