@tanstack/start-client-core 1.166.11 → 1.166.12

package/bin/intent.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+// Auto-generated by @tanstack/intent setup
+// Exposes the intent end-user CLI for consumers of this library.
+// Commit this file, then add to your package.json:
+//   "bin": { "intent": "./bin/intent.js" }
+try {
+  await import('@tanstack/intent/intent-library')
+} catch (e) {
+  const isModuleNotFound =
+    e?.code === 'ERR_MODULE_NOT_FOUND' || e?.code === 'MODULE_NOT_FOUND'
+  const missingIntentLibrary =
+    typeof e?.message === 'string' && e.message.includes('@tanstack/intent')
+
+  if (isModuleNotFound && missingIntentLibrary) {
+    console.error('@tanstack/intent is not installed.')
+    console.error('')
+    console.error('Install it as a dev dependency:')
+    console.error('  npm add -D @tanstack/intent')
+    console.error('')
+    console.error('Or run directly:')
+    console.error('  npx @tanstack/intent@latest list')
+    process.exit(1)
+  }
+  throw e
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/start-client-core",
-  "version": "1.166.11",
+  "version": "1.166.12",
   "description": "Modern and scalable routing for React applications",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -57,7 +57,10 @@
   "sideEffects": false,
   "files": [
     "dist",
-    "src"
+    "src",
+    "skills",
+    "bin",
+    "!skills/_artifacts"
   ],
   "engines": {
     "node": ">=22.12.0"
@@ -66,13 +69,17 @@
     "seroval": "^1.4.2",
     "tiny-invariant": "^1.3.3",
     "tiny-warning": "^1.0.3",
-    "@tanstack/router-core": "1.167.3",
-    "@tanstack/start-storage-context": "1.166.11",
-    "@tanstack/start-fn-stubs": "1.161.6"
+    "@tanstack/start-fn-stubs": "1.161.6",
+    "@tanstack/router-core": "1.167.4",
+    "@tanstack/start-storage-context": "1.166.12"
   },
   "devDependencies": {
+    "@tanstack/intent": "^0.0.14",
     "vite": "*"
   },
+  "bin": {
+    "intent": "./bin/intent.js"
+  },
   "scripts": {
     "clean": "rimraf ./dist && rimraf ./coverage",
     "test": "pnpm test:eslint && pnpm test:types && pnpm test:build && pnpm test:unit",

package/skills/start-core/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: start-core
+description: >-
+  Core overview for TanStack Start: tanstackStart() Vite plugin,
+  getRouter() factory, root route document shell (HeadContent,
+  Scripts, Outlet), client/server entry points, routeTree.gen.ts,
+  tsconfig configuration. Entry point for all Start skills.
+type: core
+library: tanstack-start
+library_version: '1.166.2'
+sources:
+  - TanStack/router:docs/start/framework/react/build-from-scratch.md
+  - TanStack/router:docs/start/framework/react/quick-start.md
+  - TanStack/router:docs/start/framework/react/guide/routing.md
+---
+
+# TanStack Start Core
+
+TanStack Start is a full-stack React framework built on TanStack Router and Vite. It adds SSR, streaming, server functions (type-safe RPCs), middleware, server routes, and universal deployment.
+
+> **CRITICAL**: All code in TanStack Start is ISOMORPHIC by default — it runs in BOTH server and client environments. Loaders run on both server AND client. To run code exclusively on the server, use `createServerFn`. This is the #1 AI agent mistake.
+> **CRITICAL**: TanStack Start is NOT Next.js. Do not generate `getServerSideProps`, `"use server"` directives, `app/layout.tsx`, or any Next.js/Remix patterns. Use `createServerFn` for server-only code.
+> **CRITICAL**: Types are FULLY INFERRED. Never cast, never annotate inferred values.
+
+## Sub-Skills
+
+| Task                                         | Sub-Skill                                                           |
+| -------------------------------------------- | ------------------------------------------------------------------- |
+| Type-safe RPCs, data fetching, mutations     | [start-core/server-functions/SKILL.md](./server-functions/SKILL.md) |
+| Request/function middleware, context, auth   | [start-core/middleware/SKILL.md](./middleware/SKILL.md)             |
+| Isomorphic execution, environment boundaries | [start-core/execution-model/SKILL.md](./execution-model/SKILL.md)   |
+| REST API endpoints alongside app routes      | [start-core/server-routes/SKILL.md](./server-routes/SKILL.md)       |
+| Hosting, SSR modes, prerendering, SEO        | [start-core/deployment/SKILL.md](./deployment/SKILL.md)             |
+
+## Quick Decision Tree
+
+```text
+Need to run code exclusively on the server (DB, secrets)?
+  → start-core/server-functions
+
+Need auth checks, logging, or shared logic across server functions?
+  → start-core/middleware
+
+Need to understand where code runs (server vs client)?
+  → start-core/execution-model
+
+Need a REST API endpoint (GET/POST/PUT/DELETE)?
+  → start-core/server-routes
+
+Need to deploy, configure SSR, or prerender?
+  → start-core/deployment
+```
+
+## Project Setup
+
+### 1. Install Dependencies
+
+```bash
+npm i @tanstack/react-start @tanstack/react-router react react-dom
+npm i -D vite @vitejs/plugin-react typescript
+```
+
+### 2. Configure Vite
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite'
+import { tanstackStart } from '@tanstack/react-start/plugin/vite'
+import viteReact from '@vitejs/plugin-react'
+
+export default defineConfig({
+  plugins: [
+    // MUST come before react()
+    tanstackStart(),
+    viteReact(),
+  ],
+})
+```
+
+### 3. Create Router Factory
+
+```tsx
+// src/router.tsx
+import { createRouter } from '@tanstack/react-router'
+import { routeTree } from './routeTree.gen'
+
+export function getRouter() {
+  const router = createRouter({
+    routeTree,
+    scrollRestoration: true,
+  })
+
+  return router
+}
+```
+
+### 4. Create Root Route with Document Shell
+
+```tsx
+// src/routes/__root.tsx
+import type { ReactNode } from 'react'
+import {
+  Outlet,
+  createRootRoute,
+  HeadContent,
+  Scripts,
+} from '@tanstack/react-router'
+
+export const Route = createRootRoute({
+  head: () => ({
+    meta: [
+      { charSet: 'utf-8' },
+      { name: 'viewport', content: 'width=device-width, initial-scale=1' },
+      { title: 'My App' },
+    ],
+  }),
+  component: RootComponent,
+})
+
+function RootComponent() {
+  return (
+    <html>
+      <head>
+        <HeadContent />
+      </head>
+      <body>
+        <Outlet />
+        <Scripts />
+      </body>
+    </html>
+  )
+}
+```
+
+### 5. Create Index Route with Server Function
+
+```tsx
+// src/routes/index.tsx
+import { createFileRoute } from '@tanstack/react-router'
+import { createServerFn } from '@tanstack/react-start'
+
+const getGreeting = createServerFn({ method: 'GET' }).handler(async () => {
+  return { message: 'Hello from the server!' }
+})
+
+export const Route = createFileRoute('/')({
+  loader: () => getGreeting(),
+  component: HomePage,
+})
+
+function HomePage() {
+  const data = Route.useLoaderData()
+  return <h1>{data.message}</h1>
+}
+```
+
+## Common Mistakes
+
+### 1. CRITICAL: React plugin before Start plugin in Vite config
+
+```ts
+// WRONG — route generation and server function compilation fail
+plugins: [react(), tanstackStart()]
+
+// CORRECT — Start plugin must come first
+plugins: [tanstackStart(), react()]
+```
+
+### 2. HIGH: Enabling verbatimModuleSyntax in tsconfig
+
+`verbatimModuleSyntax` causes server bundles to leak into client bundles. Keep it disabled.
+
+### 3. HIGH: Missing Scripts component in root route
+
+The `<Scripts />` component must be rendered in the `<body>` of the root route. Without it, client-side JavaScript does not load and hydration fails.
+
+```tsx
+// WRONG — no Scripts
+function RootComponent() {
+  return (
+    <html>
+      <head>
+        <HeadContent />
+      </head>
+      <body>
+        <Outlet />
+      </body>
+    </html>
+  )
+}
+
+// CORRECT — Scripts in body
+function RootComponent() {
+  return (
+    <html>
+      <head>
+        <HeadContent />
+      </head>
+      <body>
+        <Outlet />
+        <Scripts />
+      </body>
+    </html>
+  )
+}
+```
+
+## Version Note
+
+This skill targets `@tanstack/react-start` v1.166.2 and `@tanstack/start-client-core` v1.166.2.

package/skills/start-core/deployment/SKILL.md

@@ -0,0 +1,306 @@
+---
+name: start-core/deployment
+description: >-
+  Deploy to Cloudflare Workers, Netlify, Vercel, Node.js/Docker,
+  Bun, Railway. Selective SSR (ssr option per route), SPA mode,
+  static prerendering, ISR with Cache-Control headers, SEO and
+  head management.
+type: sub-skill
+library: tanstack-start
+library_version: '1.166.2'
+requires:
+  - start-core
+sources:
+  - TanStack/router:docs/start/framework/react/guide/hosting.md
+  - TanStack/router:docs/start/framework/react/guide/selective-ssr.md
+  - TanStack/router:docs/start/framework/react/guide/static-prerendering.md
+  - TanStack/router:docs/start/framework/react/guide/seo.md
+---
+
+# Deployment and Rendering
+
+TanStack Start deploys to any hosting provider via Vite and Nitro. This skill covers hosting setup, SSR configuration, prerendering, and SEO.
+
+## Hosting Providers
+
+### Cloudflare Workers
+
+```bash
+pnpm add -D @cloudflare/vite-plugin wrangler
+```
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite'
+import { tanstackStart } from '@tanstack/react-start/plugin/vite'
+import { cloudflare } from '@cloudflare/vite-plugin'
+import viteReact from '@vitejs/plugin-react'
+
+export default defineConfig({
+  plugins: [
+    cloudflare({ viteEnvironment: { name: 'ssr' } }),
+    tanstackStart(),
+    viteReact(),
+  ],
+})
+```
+
+```jsonc
+// wrangler.jsonc
+{
+  "name": "my-app",
+  "compatibility_date": "2025-09-02",
+  "compatibility_flags": ["nodejs_compat"],
+  "main": "@tanstack/react-start/server-entry",
+}
+```
+
+Deploy: `npx wrangler login && pnpm run deploy`
+
+### Netlify
+
+```bash
+pnpm add -D @netlify/vite-plugin-tanstack-start
+```
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite'
+import { tanstackStart } from '@tanstack/react-start/plugin/vite'
+import netlify from '@netlify/vite-plugin-tanstack-start'
+import viteReact from '@vitejs/plugin-react'
+
+export default defineConfig({
+  plugins: [tanstackStart(), netlify(), viteReact()],
+})
+```
+
+Deploy: `npx netlify deploy`
+
+### Nitro (Vercel, Railway, Node.js, Docker)
+
+```bash
+npm install nitro@npm:nitro-nightly@latest
+```
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite'
+import { tanstackStart } from '@tanstack/react-start/plugin/vite'
+import { nitro } from 'nitro/vite'
+import viteReact from '@vitejs/plugin-react'
+
+export default defineConfig({
+  plugins: [tanstackStart(), nitro(), viteReact()],
+})
+```
+
+Build and start: `npm run build && node .output/server/index.mjs`
+
+### Bun
+
+Bun deployment requires React 19. For React 18, use Node.js deployment.
+
+```ts
+// vite.config.ts — add bun preset to nitro
+plugins: [tanstackStart(), nitro({ preset: 'bun' }), viteReact()]
+```
+
+## Selective SSR
+
+Control SSR per route with the `ssr` property.
+
+### `ssr: true` (default)
+
+Runs `beforeLoad` and `loader` on server, renders component on server:
+
+```tsx
+export const Route = createFileRoute('/posts/$postId')({
+  ssr: true, // default
+  loader: () => fetchPost(), // runs on server during SSR
+  component: PostPage, // rendered on server
+})
+```
+
+### `ssr: false`
+
+Disables server execution of `beforeLoad`/`loader` and server rendering:
+
+```tsx
+export const Route = createFileRoute('/dashboard')({
+  ssr: false,
+  loader: () => fetchDashboard(), // runs on client only
+  component: DashboardPage, // rendered on client only
+})
+```
+
+### `ssr: 'data-only'`
+
+Runs `beforeLoad`/`loader` on server but renders component on client only:
+
+```tsx
+export const Route = createFileRoute('/canvas')({
+  ssr: 'data-only',
+  loader: () => fetchCanvasData(), // runs on server
+  component: CanvasPage, // rendered on client only
+})
+```
+
+### Functional Form
+
+Decide SSR at runtime based on params/search:
+
+```tsx
+export const Route = createFileRoute('/docs/$docType/$docId')({
+  ssr: ({ params }) => {
+    if (params.status === 'success' && params.value.docType === 'sheet') {
+      return false
+    }
+  },
+})
+```
+
+### SSR Inheritance
+
+Children inherit parent SSR config and can only be MORE restrictive:
+
+- `true` → `data-only` or `false` (allowed)
+- `false` → `true` (NOT allowed — parent `false` wins)
+
+### Default SSR
+
+Change the default for all routes in `src/start.ts`:
+
+```tsx
+import { createStart } from '@tanstack/react-start'
+
+export const startInstance = createStart(() => ({
+  defaultSsr: false,
+}))
+```
+
+## Static Prerendering
+
+Generate static HTML at build time:
+
+```ts
+// vite.config.ts
+tanstackStart({
+  prerender: {
+    enabled: true,
+    crawlLinks: true,
+    concurrency: 14,
+    failOnError: true,
+  },
+})
+```
+
+Static routes are auto-discovered. Dynamic routes (e.g. `/users/$userId`) require `crawlLinks` or explicit `pages` config.
+
+## SEO and Head Management
+
+### Basic Meta Tags
+
+```tsx
+export const Route = createFileRoute('/')({
+  head: () => ({
+    meta: [
+      { title: 'My App - Home' },
+      { name: 'description', content: 'Welcome to My App' },
+    ],
+  }),
+})
+```
+
+### Dynamic Meta from Loader Data
+
+```tsx
+export const Route = createFileRoute('/posts/$postId')({
+  loader: async ({ params }) => fetchPost(params.postId),
+  head: ({ loaderData }) => ({
+    meta: [
+      { title: loaderData.title },
+      { name: 'description', content: loaderData.excerpt },
+      { property: 'og:title', content: loaderData.title },
+      { property: 'og:image', content: loaderData.coverImage },
+    ],
+  }),
+})
+```
+
+### Structured Data (JSON-LD)
+
+```tsx
+head: ({ loaderData }) => ({
+  scripts: [
+    {
+      type: 'application/ld+json',
+      children: JSON.stringify({
+        '@context': 'https://schema.org',
+        '@type': 'Article',
+        headline: loaderData.title,
+      }),
+    },
+  ],
+})
+```
+
+### Dynamic Sitemap via Server Route
+
+```ts
+// src/routes/sitemap[.]xml.ts
+export const Route = createFileRoute('/sitemap.xml')({
+  server: {
+    handlers: {
+      GET: async () => {
+        const posts = await fetchAllPosts()
+        const sitemap = `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+  ${posts.map((p) => `<url><loc>https://myapp.com/posts/${p.id}</loc></url>`).join('')}
+</urlset>`
+        return new Response(sitemap, {
+          headers: { 'Content-Type': 'application/xml' },
+        })
+      },
+    },
+  },
+})
+```
+
+## Common Mistakes
+
+### 1. HIGH: Missing nodejs_compat flag for Cloudflare Workers
+
+```jsonc
+// WRONG — Node.js APIs fail at runtime
+{ "compatibility_flags": [] }
+
+// CORRECT
+{ "compatibility_flags": ["nodejs_compat"] }
+```
+
+### 2. MEDIUM: Bun deployment with React 18
+
+Bun-specific deployment only works with React 19. Use Node.js deployment for React 18.
+
+### 3. MEDIUM: Child route loosening parent SSR config
+
+```tsx
+// Parent sets ssr: false
+// WRONG — child cannot upgrade to ssr: true
+const parentRoute = createFileRoute('/dashboard')({ ssr: false })
+const childRoute = createFileRoute('/dashboard/stats')({
+  ssr: true, // IGNORED — parent false wins
+})
+
+// CORRECT — children can only be MORE restrictive
+const parentRoute = createFileRoute('/dashboard')({ ssr: 'data-only' })
+const childRoute = createFileRoute('/dashboard/stats')({
+  ssr: false, // OK — more restrictive than parent
+})
+```
+
+## Cross-References
+
+- [start-core/server-routes](../server-routes/SKILL.md) — API endpoints for sitemaps, robots.txt
+- [start-core/execution-model](../execution-model/SKILL.md) — SSR affects where code runs