import { createServerFn } from '@tanstack/react-start'
import { getServerAuth } from '@/lib/auth/serverAuth'
import { db, yourTable } from '@mysite/shared/db'

export const functionName = createServerFn({
  method: 'GET', // or 'POST'
})
  .inputValidator((params: YourParamsType) => params)
  .handler(async ({ data: params }) => {
    // 1. Auth context (if needed)
    const authContext = await getServerAuth(['admin', 'manager'])

    // 2. CRITICAL: Safe parameter handling
    const safeParams = params || {}

    // 3. Database operations
    const results = await db.select().from(yourTable)
      .where(/* conditions */)
      .limit(safeParams.limit || 50)
      .offset(safeParams.offset || 0)

    return results
  })

import { createFileRoute } from '@tanstack/react-router'
import { serverFunction } from '@/lib/serverFunctions/yourFn'

export const Route = createFileRoute('/your/route/')(({
  validateSearch: (search) => ({
    param1: search?.param1 || undefined,
    param2: search?.param2 || undefined,
  }),

  // loaderDeps: ONLY for search parameters (query strings)
  loaderDeps: ({ search }) => ({
    param1: search?.param1 || undefined,
    param2: search?.param2 || undefined,
  }),

  loader: async ({ deps }) => {
    const data = await serverFunction({ data: deps })
    return { data }
  },

  component: YourComponent,
}))

URL: /route?search=test&status=active
    ↓
1. validateSearch → { search: 'test', status: 'active' }
    ↓
2. loaderDeps → { search: 'test', status: 'active' }
    ↓
3. loader → serverFunction({ data: deps })
    ↓
4. handler → ({ data: params }) where params = { search: 'test', status: 'active' }

// PATH PARAMETERS: /users/$userId → automatically available
loader: async ({ params }) => {
  // params.userId is automatic - NO loaderDeps needed
  return getUserById({ data: { userId: params.userId } })
}

// SEARCH PARAMETERS: /users?search=test → requires loaderDeps
loaderDeps: ({ search }) => ({ search: search?.search }),
loader: async ({ deps }) => {
  return searchUsers({ data: deps })
}

apps/web/
├── src/
│   ├── lib/
│   │   ├── db.ts                    # Shared database connection
│   │   └── serverFunctions/
│   │       ├── prospectsFn.ts       # Server functions with Fn suffix
│   │       ├── authFn.ts
│   │       └── campaignFn.ts
│   ├── routes/
│   │   └── admin/prospects/
│   │       ├── prospects-pipeline.tsx    # Descriptive name (not index.tsx)
│   │       └── $prospectId/
│   │           └── prospect-details.tsx
│   └── hooks/
│       └── useProspects.ts
├── server.mjs                       # Hono production server wrapper
└── dist/                            # Build output (after vite build)
    ├── server/server.js             # TanStack fetch handler (NOT standalone!)
    └── client/                      # Static assets (JS, CSS, images)

// server.mjs - Hono wrapper for TanStack Start
import { Hono } from 'hono'
import { serve } from '@hono/node-server'
import { serveStatic } from '@hono/node-server/serve-static'
import handler from './dist/server/server.js'

const app = new Hono()

// Static files FIRST (TanStack doesn't serve these!)
app.use('/assets/*', serveStatic({ root: './dist/client' }))
app.use('/images/*', serveStatic({ root: './dist/client' }))

// TanStack Start handles everything else
app.all('*', (c) => handler.fetch(c.req.raw))

serve({ fetch: app.fetch, port: 3001 })

// ✅ CORRECT: Use server functions for cross-domain queries
const contact = await getContactFullProfile({ data: { contactid: input.contactid } })
const product = await getProductDetails({ data: { productid: input.productid } })

// ❌ WRONG: Direct database queries across domains
const contact = await db.query.contact.findFirst(...)  // Don't do this from invoiceFn

// ✅ CORRECT: Direct queries within same domain
export const updateSubscription = createServerFn({ method: 'PUT' })
  .handler(async ({ data: input }) => {
    // Same-domain lookup - OK to use direct query
    const existing = await db.query.subscription.findFirst({
      where: eq(subscription.subscriptionid, input.subscriptionid)
    })
    // ...
  })

// No authentication required
const authContext = undefined  // Skip getServerAuth

// Any authenticated user
const authContext = await getServerAuthAnyRole()

// Specific roles
const authContext = await getServerAuth(['admin'])
const authContext = await getServerAuth(['admin', 'manager'])

grep -i "optimistic" references/tanstack-query.md
grep -i "webhook" references/api-routes-webhooks.md
grep -i "hydration" references/debugging.md
grep -i "loaderDeps" references/routes-and-loaders.md