React y SSR para los que vienen de Blade, jQuery y React 15

Para quién y qué asume

Para quienes hoy mantienen el libro viejo (React 15 con clases, fbemitter, 48 claves de localStorage y una app jQuery embebida), las vistas Blade del marketplace y de los widgets (21.000 líneas de JavaScript inline con new Vue() dentro de plantillas PHP), y van a hacer PRs en m-f-libro o en el frontend nuevo del marketplace. Asume que sabes JavaScript, que has visto React alguna vez y que leíste Criterio Mesa247: los vicios 6, 8, 11, 17, 18 y 19 son de frontend y aquí solo se traducen.

Cambian tres cosas de fondo:

• El servidor vuelve a renderizar, pero de otra forma. Con Blade, PHP armaba el HTML y el JS lo "animaba" después. Con TanStack Start, el mismo componente se ejecuta en el servidor para producir HTML y otra vez en el navegador para hacerlo interactivo (hidratación). La pregunta nueva de cada línea es: ¿esto corre en el servidor, en el cliente o en los dos? (sección SSR).
• El estado tiene dueño. Nada de "lo guardo en localStorage y lo leo donde haga falta". Los datos del servidor los posee TanStack Query (con su caché, invalidación y refetch); el estado de interfaz lo posee Jotai. Está escrito en docs/state-management-methodology.md y aquí se explica por qué (sección Estado).
• Los tipos y las herramientas hacen cumplir el criterio. TypeScript estricto, Zod en los bordes, ESLint + Prettier (pnpm check), Vitest. Lo que en jQuery era "abrir la consola y ver qué llega", aquí es un tipo que no compila.

De Blade, jQuery y React 15 a la casa nueva: el mapa

Cambiar la cabeza: cinco ideas antes de la sintaxis

1. La interfaz es una función del estado.

   En jQuery cambias el DOM a mano ($('#x').show()); en React describes cómo se ve la interfaz para un estado y React actualiza el DOM. Si te encuentras "buscando el elemento para cambiarlo", estás peleando con el modelo. Cambia el estado.

2. Cada línea corre en algún lado.

   Servidor (loader, server function, primer render), cliente (eventos, efectos, hidratación) o los dos (el cuerpo del componente). window, localStorage, new Date() y "el ancho de la pantalla" solo existen en uno de ellos. La pregunta se hace antes de escribir la línea.

3. Los datos tienen dueño y los dueños son dos.

   Query para lo que viene del servidor; Jotai para lo que decide el usuario en la pantalla. Un dato con dos dueños se desincroniza; es lo que pasaba con Config + localStorage + fbemitter en el libro viejo.

4. Componentes pequeños, hooks para la lógica.

   Un componente pinta; un hook (useGetTables, useAssignTable, un useAtom) trae o cambia datos. ReservationInfo.jsx tenía 6.427 líneas y 74 claves de state: aquí eso son treinta componentes y diez hooks.

5. Los tipos son el contrato; Zod es la aduana.

   Lo que entra por la red o por un formulario se valida con Zod y sale tipado. Lo que viaja entre componentes va tipado por TypeScript. any es una deuda con nombre.

Sintaxis: lo que escribías antes → lo que se escribe ahora

Un componente típico, antes y ahora

class ReservationListItem extends React.Component {
  constructor(p){ super(p); this.state = { tables: [], loading: true } }
  componentDidMount(){
    new TablesApi().getTables(localStorage.localId, r => {
      this.setState({ tables: r.data, loading: false })
      localStorage.setItem('tablesAdvanceStates', JSON.stringify(r.data))
    })
    BusEvent.addListener('loadTable', this.reload)   // sin remove
  }
  render(){
    if (this.state.loading) return <div>Cargando…</div>
    return <div onClick={()=>this.assign()}>{this.state.tables.map(t => <span>{t.name}</span>)}</div>
  }
}

export function ReservationTables({ localId, zoneId, date }: Props) {
  const { data, isPending, isFetching } = useGetTables(localId, { zone_id: zoneId, reservation_date: date })
  const [selectedId, setSelectedId] = useAtom(selectedReservationIdAtom)   // estado de UI
  const assign = useAssignTable(localId, selectedId!)                       // mutación

  if (isPending) return <TablesSkeleton />
  return (
    <ul aria-busy={isFetching}>
      {data.tables.map((t) => (
        <li key={t.id}>
          <button type="button" onClick={() => assign.mutate({ table_id: t.id })}>{t.name}</button>
        </li>
      ))}
    </ul>
  )
}

Fíjate en lo que no hay: this, localStorage, listeners a mano, HTML concatenado, div clickeable. Y en lo que sí: un hook por recurso, la clave de query decide cuándo refetchear, el estado de UI en un átomo con nombre, la mutación en su hook, key estable, button.

Las 14 trampas del que viene de jQuery, Blade y React 15

state.items.push(x); setState(state)        // React no ve el cambio (mismo objeto)
setItems([...items, x])                      // nuevo array → sí
setForm({ ...form, email })                  // nuevo objeto → sí

// NO: fetch → useEffect → atom → leer el atom en todas partes (dos fuentes de verdad)
useEffect(() => { setTablesAtom(data) }, [data])
// SÍ: renderiza data del query directamente; si otro componente lo necesita, usa el mismo hook (la caché es compartida)

const width = window.innerWidth               // ReferenceError en SSR
// SÍ: en un useEffect (solo cliente), o con typeof window !== 'undefined', o en una ruta ssr: false

<p>Hoy es {new Date().toLocaleDateString()}</p>    // servidor en UTC, cliente en Lima → mismatch
// SÍ: la fecha viene del loader/servidor (o del backend: dateServerAtom), con la zona del local, formateada con Luxon

{items.map((it, i) => <Row key={i} … />)}       // índice: al reordenar/borrar, el estado se pega a la fila equivocada
{items.map((it) => <Row key={it.id} … />)}       // id estable

useEffect(() => { const id = setInterval(() => console.log(count), 1000); return () => clearInterval(id) }, [])
// imprime siempre 0. Dependencias correctas ([count]) o setCount(c => c + 1) o useRef para el último valor.

useEffect(async () => { … }, [])                  // no: el efecto no puede devolver una promesa
useEffect(() => { let alive = true; load().then(d => alive && setD(d)); return () => { alive = false } }, [])
// mejor todavía: eso es un query, no un efecto

localStorage.setItem('token', t)                   // cualquier script del origen lo lee; XSS = sesión robada
'/configuration/#/' + TOKEN + '/…'                 // historial, Referer, logs
// Objetivo: cookie HttpOnly; Secure; SameSite emitida por el servidor (server function / backend), y el navegador nunca ve el token

// src/lib/constants/urls.ts (hoy)
localhost: 'https://mesa-backend-prod-…run.app/v1'    // localhost → PRODUCCIÓN, por URL cruda de Cloud Run
// SÍ: VITE_API_BASE_URL por entorno validada en env.ts, y en SSR una server function que lee la config del servidor

const r = (await api.get(url)).data as Reservation      // "confía en mí"
const r = ReservationSchema.parse((await api.get(url)).data)   // Zod valida y tipa

import _ from 'lodash'                    // todo lodash
import debounce from 'lodash/debounce'    // solo eso
// moment (con locales) pesa 10× Luxon; Konva solo en la ruta del mapa (import dinámico / code splitting por ruta)

// componente hijo pide sus datos cuando monta → waterfall de 3 saltos
// SÍ: loader de la ruta con queryClient.ensureQueryData de todo lo que la pantalla necesita, en paralelo (Promise.all)

SSR: dónde corre cada línea

TanStack Start renderiza en el servidor (Cloudflare Workers) y luego hidrata en el navegador. Así se ve un request a una página pública del marketplace con ssr: true:

Las tres opciones por ruta

export const Route = createFileRoute('/r/$slug')({
  ssr: true,          // default: loader + render en servidor (marketplace, SEO)
  // ssr: 'data-only' // loader en servidor, componente solo en cliente (datos rápidos, UI con window/Konva)
  // ssr: false       // todo en cliente (el libro: app detrás de login; así está en __root.tsx)
  loader: ({ params }) => getLocalPublic({ data: { slug: params.slug } }),
  component: LocalPage,
})

Las rutas hijas heredan y solo pueden ser más restrictivas (true → 'data-only' → false, nunca al revés). El <html> siempre se renderiza en servidor (shellComponent) aunque la raíz sea ssr: false. m-f-libro usa ssr: false en la raíz y prerender en el build (HTML estático por ruta): es una SPA con arranque rápido, no SSR; el marketplace nuevo sí necesitará ssr: true por SEO.

Server functions: código de servidor que se llama como una función

// src/server/locales.ts
import { createServerFn } from '@tanstack/react-start'
import { z } from 'zod'

export const getLocalPublic = createServerFn({ method: 'GET' })
  .validator(z.object({ slug: z.string().min(1) }))
  .handler(async ({ data }) => {
    // Esto corre SOLO en el servidor: puede usar la URL interna de la API y una credencial de servidor.
    const r = await fetch(`${process.env.API_INTERNAL_URL}/v1/locales/${data.slug}`, {
      headers: { Authorization: `Bearer ${process.env.API_SERVER_TOKEN}` },
      signal: AbortSignal.timeout(5000),
    })
    if (r.status === 404) throw notFound()
    return LocalPublicSchema.parse(await r.json())
  })

En el bundle del cliente el cuerpo se reemplaza por un stub RPC: el código y los secretos no llegan al navegador. Es la respuesta correcta a "el JS necesita llamar a la API con un token": no necesita; llama a una server function y el servidor habla con la API (vicio 6). Con setResponseHeaders/setResponseStatus controlas caché y códigos desde el handler.

Estado: quién es dueño de qué

La regla central de docs/state-management-methodology.md, que se aplica en cada feature que toques:

// respuestas de la API, caché, staleTime, invalidación, refetch, mutaciones
const { data } = useGetReservations(localId, { date })
const create = useCreateReservation(localId, { onSuccess: () => qc.invalidateQueries({ queryKey: ['reservations', localId] }) })

// selección, pestañas, paneles, filtros, flags persistidos de UI
export const selectedReservationIdAtom = atom<number | null>(null)
export const sidebarOpenAtom = atomWithStorage('sidebarOpen', true)
export const currentLocalOptionsAtom = atom((get) => get(localsAtom).map(toOption))   // derivado, sin useEffect

• No espejes datos del query en un átomo. Render directo desde el query; pásalo por props o selectores.
• Tras una mutación, invalida las claves afectadas, no escribas el payload de vuelta en un átomo.
• Claves de query estables definidas en el archivo del hook del recurso (['tables', localId, zoneId, date]).
• Primera carga → Suspense/skeleton; refresco en segundo plano → isFetching.
• El arranque de auth vive en los loaders (beforeLoad/loader de __root.tsx y v1/auth.$token.tsx), no en componentes.
• Peculiaridades de la casa: enabled: false por defecto en el QueryClient (cada hook decide cuándo puede correr), staleTime 5 min, retry: 3 en queries y 0 en mutaciones, refetchOnWindowFocus: false. El MyRouterContext comparte el QueryClient y el store de Jotai para que los loaders lean/escriban átomos.

Capas de hooks: src/hooks/api/* (genéricos: useGet, usePost, usePut, usePatch, useDelete) → src/hooks/queries/use-get-*.ts (uno por recurso, exponen a veces un *Query para ensureQueryData en loaders) → src/hooks/mutations/use-*.ts (una por acción, invalidan en onSuccess). Nunca axios directo en un componente.

Los vicios que no se traen (y los dos que ya se colaron)

Cómo está armado el repo

m-f-libro/
├── src/
│   ├── routes/                  file-based: __root.tsx (shell, providers, auth bootstrap), index.tsx (3 paneles),
│   │                            reservation/, waitlist/, timeline.tsx, configuration.tsx, v1/auth.$token.tsx…
│   ├── routeTree.gen.ts         generado por el plugin del router (no se edita)
│   ├── components/              UI por dominio + ui/ (shadcn)
│   ├── hooks/api/               useGet/usePost/usePut/usePatch/useDelete (genéricos sobre axios + Query)
│   ├── hooks/queries/           un archivo por recurso: use-get-tables.ts, use-get-reservations.ts…
│   ├── hooks/mutations/         una por acción: use-assign-table.ts, use-create-reservation.ts…
│   ├── stores/                  átomos Jotai por dominio: auth-atoms.ts, app-config-atoms.ts, reservations-atoms.ts…
│   ├── lib/api/client.ts        axios singleton + setAuthToken()/setBaseUrl() (se llaman en el bootstrap)
│   ├── lib/constants/           endpoints.ts, urls.ts (mapa por host — a migrar)
│   ├── integrations/tanstack-query/  QueryClient con los defaults de la casa
│   ├── env.ts                   variables VITE_* validadas con Zod (@t3-oss/env-core)
│   ├── i18n.ts · locales/       i18next
│   ├── types/ · utils/ · styles.css
│   └── test/ · **/__tests__/    vitest + Testing Library (36 archivos hoy)
├── docs/                        state-management-methodology.md, api-hooks.md, atoms-dictionary.md, components-map.md,
│                                design-system.md, login-flow.md, path-aliases.md (mkdocs: docker compose up docs)
├── vite.config.ts · vitest.config.ts · tsconfig.json (aliases en los dos, a mano)
├── eslint.config.js · prettier.config.js · components.json (shadcn)
├── Dockerfile.dev · docker-compose.yml · Makefile
└── CLAUDE.md                    léelo primero, siempre

pnpm install                 # pnpm 8.15
pnpm dev                     # vite en :3000
pnpm test                    # vitest run (una vez); pnpm exec vitest <patrón> para uno
pnpm check                   # prettier --write . && eslint --fix   ← antes de cada commit (pnpm format NO formatea)
pnpm build                   # producción; pnpm build:pages emite dist/client/version.json con el SHA
pnpm dlx shadcn@latest add dialog     # agregar un componente (dentro del contenedor si usas Docker)

Dos features de punta a punta

A · En el libro (SPA): filtrar la lista de reservas por zona

Un átomo para la selección de zona (UI), el query existente de reservas, y una mutación que invalida. Sin useEffect.

import { atom } from 'jotai'
export const selectedZoneIdAtom = atom<number | null>(null)          // estado de UI, no persistido

export function useGetReservations(localId: Id | null, params: { date: string; zone_id?: number | null }) {
  const enabled = !!localId && !!params.date
  return useGet<ReservationsApiResponse>(
    ['reservations', localId, params.date, params.zone_id ?? null],   // clave estable: cambia → refetch solo
    enabled ? buildEndpointWithParams(LOCAL_ENDPOINTS.RESERVATIONS(localId!), params) : '',
    undefined,
    { enabled, placeholderData: keepPreviousData },
  )
}

export function ReservationList({ localId, date }: { localId: Id; date: string }) {
  const [zoneId, setZoneId] = useAtom(selectedZoneIdAtom)
  const zones = useGetAmbients(localId)
  const reservations = useGetReservations(localId, { date, zone_id: zoneId })
  const { t } = useTranslation()

  return (
    <section aria-labelledby="rl-title">
      <h2 id="rl-title">{t('reservations.title')}</h2>
      <Select value={zoneId ?? ''} onValueChange={(v) => setZoneId(v ? Number(v) : null)}>…</Select>
      {reservations.isPending ? <ListSkeleton /> : (
        <ul aria-busy={reservations.isFetching}>
          {reservations.data.items.map((r) => <ReservationRow key={r.id} reservation={r} />)}
        </ul>
      )}
    </section>
  )
}

import { render, screen } from '@testing-library/react'
import userEvent from '@testing-library/user-event'
import { http, HttpResponse } from 'msw'
import { server } from '@/test/msw'                       // MSW: la API simulada, no axios mockeado

it('filtra por zona y muestra las reservas de esa zona', async () => {
  server.use(
    http.get('*/locals/11/ambients', () => HttpResponse.json({ items: [{ id: 1, name: 'Terraza' }] })),
    http.get('*/locals/11/reservations', ({ request }) => {
      const zone = new URL(request.url).searchParams.get('zone_id')
      return HttpResponse.json({ items: zone === '1' ? [{ id: 9, name: 'Ana' }] : [] })
    }),
  )
  renderWithProviders(<ReservationList localId={11} date="2026-08-20" />)
  await userEvent.click(screen.getByRole('combobox'))
  await userEvent.click(screen.getByRole('option', { name: 'Terraza' }))
  expect(await screen.findByText('Ana')).toBeInTheDocument()
})

B · En el marketplace nuevo (SSR): la ficha pública de un restaurante

import { createFileRoute, notFound } from '@tanstack/react-router'
import { getLocalPublic } from '@/server/locales'          // server function del ejemplo de arriba

export const Route = createFileRoute('/r/$slug')({
  ssr: true,
  loader: ({ params }) => getLocalPublic({ data: { slug: params.slug } }),
  head: ({ loaderData }) => ({
    meta: [{ title: `${loaderData.nombre} · Mesa247` }, { name: 'description', content: loaderData.descripcion }],
  }),
  notFoundComponent: () => <LocalNoEncontrado />,
  component: LocalPage,
})

function LocalPage() {
  const local = Route.useLoaderData()                                   // tipado desde el loader
  return (
    <article>
      <h1>{local.nombre}</h1>
      <p>{local.descripcion}</p>
      <Disponibilidad localId={local.id} zona={local.zonaHoraria} />   {/* interactivo: Query en cliente */}
    </article>
  )
}

El HTML llega completo (Google lo indexa, el móvil lo pinta sin JS), el token de servidor nunca sale del Worker, y la parte interactiva (disponibilidad) es un componente normal con Query. Si el navegador necesita disponibilidad en vivo, llama a otra server function o a un endpoint público sin credenciales, nunca con el token del servidor.

Cómo se testea

• Vitest + Testing Library, por comportamiento: "el usuario hace X y ve Y". Consultas por rol y texto (getByRole('button', { name })), no por clase CSS ni por implementación.
• MSW para la red: se simula la API HTTP, no se mockea axios ni el hook. Es el "mock boundary" de la guía de Python: mockea el nivel más bajo, no la función bajo prueba.
• Un renderWithProviders en src/test/ que monta QueryClientProvider (con retry: false), Jotai Provider con store limpio, i18n y router de prueba. Cada test parte de cero.
• Hooks con renderHook; átomos derivados con createStore() y store.get(atom) (funciones puras: sin render).
• Server functions: probar el handler como función (inyectar fetch), y la ruta con un test de integración que renderice el árbol con datos del loader.
• E2E (Playwright) para dos o tres flujos críticos: crear reserva, asignar mesa, checkout público. Pocos, estables.
• Antes de escribir un test: la misma pregunta de TESTING.md del backend: ¿qué bug de producción atraparía?

Checklist de PR en m-f-libro

• pnpm check y pnpm test limpios; TypeScript sin any/as/! nuevos sin justificar.
• Datos del servidor en Query (hook en hooks/queries o mutations); ningún axios en componentes; ningún useEffect que espeje queries en átomos.
• Estado de UI en átomos con nombre en stores/; derivados con atom(get => …).
• Ningún token, credencial ni URL de servicio en el código, en localStorage nuevo ni en la URL; config por env.ts.
• Nada de window/document/new Date() en el cuerpo del render de una ruta con SSR; fechas con la zona del local (Luxon).
• Textos por t(); button/label/alt/key en su sitio; sin dangerouslySetInnerHTML sin sanitizado y justificación.
• Componente < 300 líneas; ruta delgada; sin copias de componentes.
• Tests del comportamiento nuevo con MSW; sin console.log.
• Sin dependencias nuevas (o justificadas y pesadas en el bundle).
• Commit type(scope): description; docs (docs/*.md, CLAUDE.md) actualizadas si cambia una convención.
• Puedo explicar cada línea, incluidas las que escribió la IA.

Tres semanas, de jQuery/Blade a un PR mergeado

Con Claude en m-f-libro

El repo ya tiene CLAUDE.md con la arquitectura, los comandos y la metodología de estado. Aplican las reglas de Criterio Mesa247 y estas tres:

1. Pide la traducción con el archivo viejo al lado.

   "Este es ReservationListItem.jsx del libro viejo. Rehazlo como componentes de función siguiendo docs/state-management-methodology.md: qué va a Query, qué a Jotai, qué se parte. Primero el plan, sin código."

2. Que te diga dónde corre cada línea.

   "En esta ruta con ssr: true, marca qué líneas corren en servidor, cuáles en cliente y cuáles en los dos, y qué puede producir hydration mismatch."

3. Test primero, con MSW.

   "Escribe el test de comportamiento (usuario filtra por zona y ve las reservas) con MSW; no lo hagas pasar todavía." Y luego la implementación.

Recursos, pocos y elegidos

• React · Aprende (español)La documentación nueva. "Escapar del paradigma" y "Manejo de estado" son las dos secciones que curan el jQuery.
• TanStack Start · Router · QuerySSR selectivo, server functions, loaders, claves y caché. Lo que corre en la casa.
• JotaiÁtomos, derivados, atomWithStorage, atomFamily. Corto.
• Zod · TanStack FormValidación en el borde y formularios tipados.
• Testing Library · Vitest · MSWTests por comportamiento con la red simulada.
• Tailwind v4 · shadcn/uiLos componentes vienen accesibles; no los envuelvas en div onClick.
• MDN · Accesibilidad (español) · web.dev · PerformanceLo mínimo de a11y y de rendimiento web (Core Web Vitals) para una app pública.
• Cloudflare Workers · WranglerDónde corre el SSR y cómo se despliega.
• En el repo: CLAUDE.md, docs/state-management-methodology.md, docs/api-hooks.md, docs/atoms-dictionary.md, docs/components-map.md, docs/login-flow.mdAntes que cualquier recurso externo. Es la casa.