@benjavicente/start-client-core 1.167.9

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 '@benjavicente/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": "@benjavicente/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 '@benjavicente/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 '@benjavicente/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 '@benjavicente/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

package/skills/start-core/execution-model/SKILL.md

@@ -0,0 +1,302 @@
+---
+name: start-core/execution-model
+description: >-
+  Isomorphic-by-default principle, environment boundary functions
+  (createServerFn, createServerOnlyFn, createClientOnlyFn,
+  createIsomorphicFn), ClientOnly component, useHydrated hook,
+  import protection, dead code elimination, environment variable
+  safety (VITE_ prefix, process.env).
+type: sub-skill
+library: tanstack-start
+library_version: '1.166.2'
+requires:
+  - start-core
+sources:
+  - TanStack/router:docs/start/framework/react/guide/execution-model.md
+  - TanStack/router:docs/start/framework/react/guide/environment-variables.md
+---
+
+# Execution Model
+
+Understanding where code runs is fundamental to TanStack Start. This skill covers the isomorphic execution model and how to control environment boundaries.
+
+> **CRITICAL**: ALL code in TanStack Start is isomorphic by default — it runs in BOTH server and client bundles. Route loaders run on BOTH server (during SSR) AND client (during navigation). Server-only operations MUST use `createServerFn`.
+> **CRITICAL**: Module-level `process.env` access runs in both environments. Secret values leak into the client bundle. Access secrets ONLY inside `createServerFn` or `createServerOnlyFn`.
+> **CRITICAL**: `VITE_` prefixed environment variables are exposed to the client bundle. Server secrets must NOT have the `VITE_` prefix.
+
+## Execution Control APIs
+
+| API                      | Use Case                  | Client Behavior           | Server Behavior       |
+| ------------------------ | ------------------------- | ------------------------- | --------------------- |
+| `createServerFn()`       | RPC calls, data mutations | Network request to server | Direct execution      |
+| `createServerOnlyFn(fn)` | Utility functions         | Throws error              | Direct execution      |
+| `createClientOnlyFn(fn)` | Browser utilities         | Direct execution          | Throws error          |
+| `createIsomorphicFn()`   | Different impl per env    | Uses `.client()` impl     | Uses `.server()` impl |
+| `<ClientOnly>`           | Browser-only components   | Renders children          | Renders fallback      |
+| `useHydrated()`          | Hydration-dependent logic | `true` after hydration    | `false`               |
+
+## Server-Only Execution
+
+### createServerFn (RPC pattern)
+
+The primary way to run server-only code. On the client, calls become fetch requests:
+
+```tsx
+// Use @tanstack/<framework>-start for your framework (react, solid, vue)
+import { createServerFn } from '@benjavicente/react-start'
+
+const fetchUser = createServerFn().handler(async () => {
+  const secret = process.env.API_SECRET // safe — server only
+  return await db.users.find()
+})
+
+// Client calls this via network request
+const user = await fetchUser()
+```
+
+### createServerOnlyFn (throws on client)
+
+For utility functions that must never run on client:
+
+```tsx
+// Use @tanstack/<framework>-start for your framework (react, solid, vue)
+import { createServerOnlyFn } from '@benjavicente/react-start'
+
+const getSecret = createServerOnlyFn(() => process.env.DATABASE_URL)
+
+// Server: returns the value
+// Client: THROWS an error
+```
+
+## Client-Only Execution
+
+### createClientOnlyFn
+
+```tsx
+// Use @tanstack/<framework>-start for your framework (react, solid, vue)
+import { createClientOnlyFn } from '@benjavicente/react-start'
+
+const saveToStorage = createClientOnlyFn((key: string, value: string) => {
+  localStorage.setItem(key, value)
+})
+```
+
+### ClientOnly Component
+
+```tsx
+// Use @tanstack/<framework>-router for your framework (react, solid, vue)
+import { ClientOnly } from '@benjavicente/react-router'
+
+function Analytics() {
+  return (
+    <ClientOnly fallback={null}>
+      <GoogleAnalyticsScript />
+    </ClientOnly>
+  )
+}
+```
+
+### useHydrated Hook
+
+```tsx
+// Use @tanstack/<framework>-router for your framework (react, solid, vue)
+import { useHydrated } from '@benjavicente/react-router'
+
+function TimeZoneDisplay() {
+  const hydrated = useHydrated()
+  const timeZone = hydrated
+    ? Intl.DateTimeFormat().resolvedOptions().timeZone
+    : 'UTC'
+
+  return <div>Your timezone: {timeZone}</div>
+}
+```
+
+Behavior: SSR → `false`, first client render → `false`, after hydration → `true` (stays `true`).
+
+## Environment-Specific Implementations
+
+```tsx
+// Use @tanstack/<framework>-start for your framework (react, solid, vue)
+import { createIsomorphicFn } from '@benjavicente/react-start'
+
+const getDeviceInfo = createIsomorphicFn()
+  .server(() => ({ type: 'server', platform: process.platform }))
+  .client(() => ({ type: 'client', userAgent: navigator.userAgent }))
+```
+
+## Environment Variables
+
+### Server-Side (inside createServerFn)
+
+Access any variable via `process.env`:
+
+```tsx
+const connectDb = createServerFn().handler(async () => {
+  const url = process.env.DATABASE_URL // no prefix needed
+  return createConnection(url)
+})
+```
+
+### Client-Side (components)
+
+Only `VITE_` prefixed variables are available:
+
+```tsx
+// Framework-specific component type (React.ReactNode, JSX.Element, etc.)
+function ApiProvider({ children }: { children: React.ReactNode }) {
+  const apiUrl = import.meta.env.VITE_API_URL // available
+  // import.meta.env.DATABASE_URL → undefined (security)
+  return (
+    <ApiContext.Provider value={{ apiUrl }}>{children}</ApiContext.Provider>
+  )
+}
+```
+
+### Runtime Client Variables
+
+If you need server-side variables on the client without `VITE_` prefix, pass them through a server function:
+
+```tsx
+const getRuntimeVar = createServerFn({ method: 'GET' }).handler(() => {
+  return process.env.MY_RUNTIME_VAR
+})
+
+export const Route = createFileRoute('/')({
+  loader: async () => {
+    const foo = await getRuntimeVar()
+    return { foo }
+  },
+  component: () => {
+    const { foo } = Route.useLoaderData()
+    return <div>{foo}</div>
+  },
+})
+```
+
+### Type Safety for Environment Variables
+
+```tsx
+// src/env.d.ts
+/// <reference types="vite/client" />
+
+interface ImportMetaEnv {
+  readonly VITE_APP_NAME: string
+  readonly VITE_API_URL: string
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv
+}
+
+declare global {
+  namespace NodeJS {
+    interface ProcessEnv {
+      readonly DATABASE_URL: string
+      readonly JWT_SECRET: string
+    }
+  }
+}
+
+export {}
+```
+
+## Common Mistakes
+
+### 1. CRITICAL: Assuming loaders are server-only
+
+```tsx
+// WRONG — loader runs on BOTH server and client
+export const Route = createFileRoute('/dashboard')({
+  loader: async () => {
+    const secret = process.env.API_SECRET // LEAKED to client
+    return fetch(`https://api.example.com/data`, {
+      headers: { Authorization: secret },
+    })
+  },
+})
+
+// CORRECT — use createServerFn
+const getData = createServerFn({ method: 'GET' }).handler(async () => {
+  const secret = process.env.API_SECRET
+  return fetch(`https://api.example.com/data`, {
+    headers: { Authorization: secret },
+  })
+})
+
+export const Route = createFileRoute('/dashboard')({
+  loader: () => getData(),
+})
+```
+
+### 2. CRITICAL: Exposing secrets via module-level process.env
+
+```tsx
+// WRONG — runs in both environments, value in client bundle
+const apiKey = process.env.SECRET_KEY
+export function fetchData() {
+  /* uses apiKey */
+}
+
+// CORRECT — access inside server function only
+const fetchData = createServerFn({ method: 'GET' }).handler(async () => {
+  const apiKey = process.env.SECRET_KEY
+  return fetch(url, { headers: { Authorization: apiKey } })
+})
+```
+
+### 3. CRITICAL: Using VITE\_ prefix for server secrets
+
+```bash
+# WRONG — exposed to client bundle
+VITE_SECRET_API_KEY=sk_live_xxx
+
+# CORRECT — no prefix for server secrets
+SECRET_API_KEY=sk_live_xxx
+
+# CORRECT — VITE_ only for public client values
+VITE_APP_NAME=My App
+```
+
+### 4. HIGH: Hydration mismatches
+
+```tsx
+// WRONG — different content server vs client
+function CurrentTime() {
+  return <div>{new Date().toLocaleString()}</div>
+}
+
+// CORRECT — consistent rendering
+function CurrentTime() {
+  const [time, setTime] = useState<string>()
+  useEffect(() => {
+    setTime(new Date().toLocaleString())
+  }, [])
+  return <div>{time || 'Loading...'}</div>
+}
+```
+
+## Architecture Decision Framework
+
+**Server-Only** (`createServerFn` / `createServerOnlyFn`):
+
+- Sensitive data (env vars, secrets)
+- Database connections, file system
+- External API keys
+
+**Client-Only** (`createClientOnlyFn` / `<ClientOnly>`):
+
+- DOM manipulation, browser APIs
+- localStorage, geolocation
+- Analytics/tracking
+
+**Isomorphic** (default / `createIsomorphicFn`):
+
+- Data formatting, business logic
+- Shared utilities
+- Route loaders (they're isomorphic by nature)
+
+## Cross-References
+
+- [start-core/server-functions](../server-functions/SKILL.md) — the primary server boundary
+- [start-core/deployment](../deployment/SKILL.md) — deployment target affects execution