Skip to content

Commit 6fbbd73

Browse files
committed
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
1 parent 30c9f1d commit 6fbbd73

4 files changed

Lines changed: 11 additions & 53 deletions

File tree

‎docs/start/framework/react/guide/middleware.md‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,6 @@ title: Middleware
77

88
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.
99

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-
1210
### What kinds of things can I do with Middleware?
1311

1412
- **Authentication**: Verify a user's identity before executing a server function.

‎docs/start/framework/react/guide/server-functions.md‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,6 @@ title: Server Functions
77

88
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.
99

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`.
11-
1210
```tsx
1311
import { createServerFn } from '@tanstack/react-start'
1412

‎packages/start-client-core/skills/start-core/middleware/SKILL.md‎

Lines changed: 4 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,6 @@ sources:
2020

2121
Middleware customizes the behavior of server functions and server routes. It is composable — middleware can depend on other middleware to form a chain.
2222

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`.
2423
> **CRITICAL**: TypeScript enforces method order: `middleware()` → `inputValidator()` → `client()` → `server()`. Wrong order causes type errors.
2524
> **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.
2625
@@ -304,25 +303,7 @@ Fetch precedence (highest to lowest): call site → later middleware → earlier
304303

305304
## Common Mistakes
306305

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.
310-
311-
```tsx
312-
// WRONG — does not export createMiddleware
313-
import { createMiddleware } from '@tanstack/react-router'
314-
315-
// WRONG — package does not exist
316-
import { createMiddleware } from '@tanstack/start'
317-
318-
// CORRECT — framework-scoped start package
319-
import { createMiddleware } from '@tanstack/react-start'
320-
// (or @tanstack/solid-start, @tanstack/vue-start)
321-
```
322-
323-
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
326307

327308
`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.
328309

@@ -366,11 +347,11 @@ Same applies to `createStart` and other Start runtime exports.
366347

367348
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).
368349

369-
### 3. MEDIUM: Confusing request vs server function middleware
350+
### 2. MEDIUM: Confusing request vs server function middleware
370351

371352
Request middleware runs on ALL requests (SSR, routes, functions). Server function middleware runs only for `createServerFn` calls and has `.client()` method.
372353

373-
### 4. HIGH: Browser APIs in .client() crash during SSR
354+
### 3. HIGH: Browser APIs in .client() crash during SSR
374355

375356
During SSR, `.client()` callbacks run on the server. Browser-only APIs like `localStorage` or `window` will throw `ReferenceError`:
376357

@@ -393,7 +374,7 @@ const middleware = createMiddleware({ type: 'function' }).client(
393374
)
394375
```
395376

396-
### 5. MEDIUM: Wrong method order
377+
### 4. MEDIUM: Wrong method order
397378

398379
```tsx
399380
// WRONG — type error

‎packages/start-client-core/skills/start-core/server-functions/SKILL.md‎

Lines changed: 7 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,6 @@ sources:
1919

2020
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.
2121

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`.
2322
> **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.
2423
> **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.
2524
> **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
269268

270269
## Common Mistakes
271270

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.
275-
276-
```tsx
277-
// WRONG — does not export createServerFn
278-
import { createServerFn } from '@tanstack/react-router'
279-
280-
// WRONG — package does not exist
281-
import { createServerFn } from '@tanstack/start'
282-
283-
// CORRECT — framework-scoped start package
284-
import { createServerFn } from '@tanstack/react-start'
285-
// (or @tanstack/solid-start, @tanstack/vue-start)
286-
```
287-
288-
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
291272

292273
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.
293274

@@ -313,7 +294,7 @@ const getMyOrders = createServerFn({ method: 'GET' })
313294

314295
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.
315296

316-
### 3. CRITICAL: Putting server-only code in loaders
297+
### 2. CRITICAL: Putting server-only code in loaders
317298

318299
```tsx
319300
// WRONG — loader is ISOMORPHIC, runs on BOTH client and server
@@ -335,7 +316,7 @@ export const Route = createFileRoute('/posts')({
335316
})
336317
```
337318

338-
### 4. CRITICAL: Using Next.js / Remix / React Router DOM patterns
319+
### 3. CRITICAL: Using Next.js / Remix / React Router DOM patterns
339320

340321
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`.
341322

@@ -375,7 +356,7 @@ export const Route = createFileRoute('/users/$id')({
375356

376357
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.
377358

378-
### 5. HIGH: Dynamic imports for server functions
359+
### 4. HIGH: Dynamic imports for server functions
379360

380361
```tsx
381362
// WRONG — can cause bundler issues
@@ -385,7 +366,7 @@ const { getUser } = await import('~/utils/users.functions')
385366
import { getUser } from '~/utils/users.functions'
386367
```
387368

388-
### 6. HIGH: Awaiting server function without calling it
369+
### 5. HIGH: Awaiting server function without calling it
389370

390371
`createServerFn` returns a function — it must be invoked with `()`:
391372

@@ -400,7 +381,7 @@ const data = await getItems()
400381
const data = await getItems({ data: { id: '1' } })
401382
```
402383

403-
### 7. CRITICAL: Caching authenticated responses with `Cache-Control: public`
384+
### 6. CRITICAL: Caching authenticated responses with `Cache-Control: public`
404385

405386
`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.
406387

@@ -428,7 +409,7 @@ setResponseHeaders({ 'Cache-Control': 'no-store' })
428409

429410
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.
430411

431-
### 8. MEDIUM: When to wrap with `useServerFn`
412+
### 7. MEDIUM: When to wrap with `useServerFn`
432413

433414
`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.
434415

0 commit comments

Comments
 (0)