Ejecutar, previsualizar y probar la app

Un único scaffold para local y CloudflareCopy Anchor Link

wrangler.jsonc es la fuente de verdad para la entrada del Worker, los flags de compatibilidad, los bindings y la observabilidad. Vite genera dist/server/wrangler.json y .wrangler/deploy/config.json; no edites a mano ni hagas commit de ninguno de los dos archivos generados. Tanto la preview local como el deployment de Wrangler consumen la build de producción generada. El desarrollo usa el mismo código fuente del Worker y el mismo runtime de Cloudflare con hot reload.

Todos los comandos de la aplicación, sus comprobaciones y sus deployments, con lo que hace cada uno: Comandos. En resumen, la aplicación se ejecuta en local en el puerto 5173 con hot reload (vp run dev) y como build de producción en el 4173 (vp run preview), y las comprobaciones se ejecutan en ese mismo host local. Cada rama distinta de main obtiene una preview en Cloudflare: en Cloudflare, más abajo. El navegador propio del agente en un portátil (pnpm dlx chrome-devtools-mcp, Chrome DevTools) no es CI: las comprobaciones nunca lo usan.

vp run ci ejecuta toda la suite sobre la build de producción, aquí y en GitHub. Para ejecutarla contra una URL desplegada (la preview de una rama o producción):

pnpm remy test remote https://your-worker.your-subdomain.workers.dev

La URL debe ser un origin, sin path ni query. Las comprobaciones que necesitan una persona nueva leen su código de la captura de correo local, así que solo se ejecutan contra el destino local. El resto le preguntan al Worker qué entorno es (/healthz) y esperan lo que la tabla les dé: contra una preview las personas precargadas están presentes y una pulsación inicia sesión como una de ellas; contra producción nada de eso existe. La tarea de pruebas remotas también puede apuntar a una preview local ya en ejecución para comprobar la ruta del servidor externo.

Los comandos son los de remy-cli (remy), y cada uno lee lo que necesita donde se guarda (los origins: el .env de la app); los propios de este repositorio son sus tareas (el vite.config.ts de la raíz: ready, new-app, skills:build, publish) y sus scripts. La configuración de Playwright es el playwrightConfig() del paquete.

Existe una única configuración de Worker, wrangler.jsonc: producción, y su sección previews para la preview de cada rama (con sus propias bases de datos y secreto, ENVIRONMENT: "staging", de modo que el inicio de sesión de prueba está activo). No hay un Worker de staging aparte: una preview es eso (propietario, 2026-10-18). Mantén la implementación compartida; varía solo los identificadores de recursos, los secretos y demás valores de entorno. La sección previews no hereda los bindings ni las vars: cada uno se declara de nuevo ahí. No dupliques la aplicación ni uses bindings remotos para el desarrollo local habitual. Los secretos locales permanecen en .dev.vars, que está ignorado; los secretos desplegados se gestionan a través de Cloudflare. Los datos locales no se suben con el deployment.

Dos tipos de páginaCopy Anchor Link

packages/remy-ui/src/paths.js es la única lista de páginas y dice qué promete cada tipo; los dos nunca se mezclan.

• Las páginas de sitio (sitePaths: el home y los formatos) son para Google: completas en el HTML del servidor sin JavaScript, indexadas, en el sitemap con alternativas hreflang, y evaluadas por las auditorías de Google. Su marco es SiteShell en shell.tsx, construido con partes estáticas de shadcn.
• Las páginas de app (appPaths, bajo /app) necesitan JavaScript, llevan noindex (añadido por pageHead) y quedan fuera del sitemap. Su marco es AppShell en app-shell.tsx, el bloque sidebar-16 de shadcn, gestionado en blocks/sidebar-16.

Los docs no son páginas de esta app: son el Worker de docs (apps/remy-auth-docs/ aquí, el docs/ de una app; Fumadocs), con la guía en /docs, estos docs para desarrolladores en /dev y la referencia de la API en /reference, cada uno con búsqueda y Ask AI (escribir docs). El encabezado de la app enlaza allí, y sus antiguas direcciones /<locale>/docs/... redirigen allí de forma permanente.

El selector de idioma sigue el tipo: las páginas de sitio usan LanguageSwitcher, enlaces simples que no necesitan JavaScript; las páginas de app usan LanguageMenu, el DropdownMenu de shadcn que llama a setLocale de Paraglide (ambos en language.tsx).

Qué está implementadoCopy Anchor Link

Cada página existe en cada locale (13 prefijos como /en, /ar, /ja; las páginas de docs solo en inglés); la tabla las nombra sin él.

Las páginas localizadas nunca redirigen. Cuando el idioma preferido del visitante difiere del de la página, una sugerencia descartable ofrece esa versión; elegirla o descartarla se recuerda en la cookie PARAGLIDE_LOCALE de Paraglide, sobre la que solo actúan las URLs de entrada. La detección de locale, la cookie, la localización de URLs y la redirección son las propias estrategias y el middleware de Paraglide (packages/remy-ui/paraglide.mjs contiene la única configuración del compilador), integrados como la integración oficial de Paraglide con TanStack Start: el middleware envuelve la entrada del Worker, y el rewrite del router elimina el locale antes de hacer el matching y lo añade a cada enlace, de modo que las rutas no llevan segmento de locale.

TanStack Start se ejecuta a través del plugin de Vite de Cloudflare (apps/remy-auth/vite.config.ts, el remyApp() del paquete). Todas las rutas se renderizan en servidor excepto la demo. Los enlaces dentro de la app precargan el código y los datos de su ruta según la intención; los cambios de idioma en las páginas de sitio son navegaciones completas.

shadcn, de fábricaCopy Anchor Link

Los componentes y el tema son lo que escribe la CLI de shadcn, en el diseño de monorepo de shadcn: el apps/remy-auth/components.json de esta app dirige shadcn add hacia el paquete (packages/remy-ui/components.json), y packages/remy-ui/src/styles/globals.css también lo escribe la CLI. Nadie edita ninguno de los dos a mano; los scripts de package.json son la única forma en que cambian:

vp run ui:components       # Re-add every shadcn component (extend the list there to add one)
vp run ui:theme            # Rewrite globals.css with shadcn's default theme
vp run ui:blocks           # Diff each owned block against upstream, in place
vp run ui:verify           # Re-run both and fail on any difference (runs before every release)

Los bloques son copias propias, tal como shadcn pretende; el README de sidebar-16 explica qué se cambió. El alias components del paquete (@joeblew999/remy-ui/blocks) es donde shadcn escribe los archivos propios de un bloque cuando se ejecuta desde el paquete (shadcn add <block> -c packages/remy-ui): blocks/<name>/components. Así, ui:blocks los compara en su sitio y los cambios de upstream se fusionan a mano.

Las fuentes viven en packages/remy-ui/src/fonts.css, importado después de globals.css (ver src/styles.css); el archivo explica sus reglas. fontaine, en la configuración de Vite de la app (remyApp()), genera las fuentes de respaldo ajustadas en tamaño que nombra. publicPageChecks falla ante cualquier familia nombrada que no esté cargada.

En CloudflareCopy Anchor Link

Hay una sola forma de desplegar: hacer push. Cloudflare compila y despliega este repositorio por sí mismo, desde GitHub; nada nuestro sube código, y nadie ejecuta wrangler deploy a mano (propietario, 2026-10-18: "you've got multiple ways to deploy. It's bloody confusing"). Las palabras, con un solo significado cada una:

• Dos Workers, uno por app, cada uno con su propia build de Git, ambos sobre el main del repositorio: remy-auth (raíz /apps/remy-auth) y remy-auth-docs (raíz /apps/remy-auth-docs), cada uno con su propio wrangler.jsonc. Cada build instala con pnpm (a partir de pnpm-lock.yaml, la variable de build PNPM_VERSION como en devEngines, NODE_VERSION como en .node-version), luego ejecuta pnpm vp run build, y después pnpm wrangler deploy en main o pnpm wrangler preview en cualquier otra rama. Estos ajustes viven en Cloudflare, no en el repositorio: se escriben aquí y solo se cambian a través del conector, para que coincidan.
• Desde el Mac del propietario (con sesión iniciada en Cloudflare): el propio Wrangler (pnpm wrangler deployments list, pnpm wrangler tail, solo lectura), pnpm remy docs publish después de que cambien los docs (el índice de Ask AI) y las migraciones de bases de datos remotas. Desde la nube de Claude (sin sesión de Cloudflare para Wrangler): push, y Cloudflare compila; el conector de Cloudflare muestra una build y su log, cambia los ajustes de build e inicia un rebuild. Después comprueba una preview: pnpm remy test remote https://<branch>-remy-auth.gedw99.workers.dev (solo nuestras comprobaciones: una preview se oculta a propósito de los buscadores, así que las auditorías de Google evalúan producción).
• Velocidad lejos de las bases de datos: el Worker se ejecuta con Smart Placement (wrangler.jsonc, comprobado por pnpm remy verify tooling), y cada petición lee a través de su propia sesión de D1, de modo que las lecturas vienen de la copia más cercana (@joeblew999/remy-ui/replicas; una comprobación unitaria rechaza el código de la app que use un binding de base de datos en bruto).
• Toda base de datos D1 mantiene copias de lectura y vive en la región de producción: la regla de la plataforma, que pnpm remy cloudflare provisioned consulta a Cloudflare, incluidas las bases de datos de las previews, nombrando la corrección. Ninguna de las dos es un ajuste que la configuración de Wrangler pueda contener.

Qué versión está desplegadaCopy Anchor Link

Nada registra qué está desplegado: cada deployment dice qué es cuando se le pregunta, de modo que la respuesta no puede quedar desactualizada (el diseño es de remy-sport, cuyo registro versionado de deployments estuvo equivocado durante semanas).

• El sello de build. remyApp() y remyDocs() lo calculan una vez por build a partir de las fuentes: el paquete de la app, el commit, un hash corto de cualquier cambio sin confirmar, y la versión instalada de cada paquete de la plataforma (build: { packages: [...] } en remyApp() enumera más). El mismo checkout produce el mismo sello; no incluye la hora de build, así que un bundle solo cambia cuando cambia su código.
• /healthz, en cada Worker construido sobre el paquete, responde con él: service, environment (lo que el Worker declara; producción cuando no declara ninguno), release y deployedAt (la versión de Cloudflare y cuándo se le asignó) y build. No nombra a nadie, y cualquier origin puede leerlo.
• BuildStamp (@joeblew999/remy-ui/versions) está en el pie del marco de la app, así que toda página de app de toda app lo tiene: el entorno salvo que sea producción, el nombre del producto, el commit. La página lleva el sello con el que se construyó; cuando su deployment responde con otro, la página es una pestaña que quedó abierta a través de un deploy, y el sello ofrece el reload. Nunca se recarga por sí sola.
• Versions, para una página de ajustes o acerca de: esta app, su Worker de docs (docs en defineRemyApp) y los deployments que la app enumera ahí (un servicio al que llama), cada uno respondiendo por sí mismo, y luego los paquetes con los que se hizo este build. La página de Settings de remy-auth lo muestra.
• pnpm remy cloudflare versions imprime una fila por deployment (los origins del .env de la app, o los origins dados), situando cada commit respecto a este checkout: = HEAD, 3 behind HEAD. Úsalo antes de decir qué está en producción.

Los conjuntos de comprobaciones compartidos lo demuestran en cada app: /healthz nombra el commit de este checkout en una ejecución local (un sello que quedó de un build anterior falla), y el marco ofrece el reload solo cuando el deployment ha avanzado.

El nombre del productoCopy Anchor Link

Remy es el nombre de este prototipo. Un proyecto construido sobre el mismo código tiene el suyo propio, y lo escribe una sola vez:

// docs/docs.config.ts: los docs lo dicen, y la app lo toma de aquí
const product = 'Harbor';
export const docsConfig = defineDocsConfig({ product, ... });

// src/remy-app.tsx
export const remyApp = defineRemyApp({ brand: docsConfig.product, ... });

Una app sin docs escribe brand directamente. Todo lo que una persona lee toma el nombre de ahí: el marco, el título de cada página, los datos estructurados de la página de inicio, y todo mensaje que diga el nombre, que lo recibe como parámetro:

m.home_title({ product: useRemyApp().brand }, { locale })                       // en una página
pageHead({ ..., description: (locale, product) => m.home_description({ product }, { locale }) })   // en un head
codeMail({ otp, product }, locale)                                              // el correo de inicio de sesión

Un mensaje que nombra al producto se escribe con {product}, nunca con un nombre fijo, de modo que los tipos de Paraglide rechazan a quien lo omita. La página de Settings de remy-auth muestra dónde se usa el nombre, y cómo se leería cada lugar con otro nombre.

Lo que no es el nombre del producto, y permanece: los paquetes (@joeblew999/remy-ui), la skill remy, los nombres de tareas, el nombre de servicio de un Worker y el nombre de un servidor MCP. Son identificadores que ve un desarrollador.

Comprobaciones: el título de cada página termina con el nombre de la app, y una app con otro nombre nunca muestra «Remy» (productNameChecks, en el conjunto compartido de cada app; el fixture consumidor, llamado «My app», es donde esto se nota); el catálogo de la plataforma no nombra a ningún producto (tests/product.spec.ts).

Estructura y reutilizaciónCopy Anchor Link

La app es apps/remy-auth/ (sus rutas de abajo parten de ahí); los paquetes junto a ella son packages/*, los docs apps/remy-auth-docs/, todo un único workspace de pnpm (pnpm-workspace.yaml) cuya raíz contiene las comprobaciones propias del repositorio.

• src/routes/: rutas de archivo de TanStack (loaders, head, renderizado por ruta) que renderizan las páginas del paquete, más las filas de formatos adicionales de esta app (src/formats-extras.tsx), mientras que robots.txt y sitemap.xml (la parte seo-routes) y /csp-report (app-routes) son las rutas de servidor del paquete, montadas junto a ellas; src/routeTree.gen.ts lo genera el plugin del router durante el dev y el build, y se versiona.
• src/server.ts: entrada del Worker a través del localizedWorker del paquete (IDs de petición, logs de estado estructurados, /healthz, el middleware de Paraglide, redirecciones de entrada). Start recibe la petición original, así que las funciones de servidor leen la geolocalización de Cloudflare a partir de las propiedades cf de la petición en un módulo exclusivo de servidor bajo la protección de imports de Start (packages/remy-showcase/src/parts/deferred-place/place.server.ts, la parte deferred-place del showcase). El wrapper pasa su ID de petición hacia dentro como X-Request-ID; el middleware de petición de Start lo expone como context.requestId, y un middleware de función registra una línea server_fn por cada llamada (el start del paquete, registrado en src/start.ts). Ahí mismo, un segundo middleware de petición genera el nonce de CSP por petición que el router compartido (router) entrega a TanStack Router, y la ruta de servidor /csp-report del paquete (app-routes) registra los reportes de la política (cabeceras de seguridad). El nombre del servicio tiene un único hogar, src/service.ts.
• src/api/: la implementación del contrato (router.ts, tras el guard; sin imports de Workers para que las comprobaciones puedan cargarlo en Node), el contexto de cada llamada, con la sesión de quien llama (context.server.ts), y el cliente isomórfico con sus utilidades de TanStack Query (client.ts). El contrato es packages/remy-auth-contract/; el mecanismo compartido son las exportaciones api/* del paquete; el plan de contratos es dueño del diseño.
• src/auth/: Better Auth en este Worker (el plan de autenticación): sus opciones, compartidas por el Worker y la CLI (options.ts), la instancia construida en el primer uso a partir del binding D1 (auth.server.ts), la configuración de la CLI (cli.ts), la tabla de entorno (environment.ts), las personas precargadas (seed.ts, people.server.ts), el envío de correo y el correo del código (mail.server.ts, code-mail.ts), la regla sobre los campos que una persona puede escribir (fields.ts), la función de servidor de la cuenta (account.ts) y el formulario de inicio de sesión, su selector y el cliente de navegador de Better Auth (sign-in.tsx, client.ts). migrations/ contiene las migraciones numeradas de D1 (los scripts de Better Auth).
• src/notes/: la demo de notas, que usa el motor de relaciones como lo haría cualquier app: sus datos en su propia D1 (DEMO_DB, migrations-demo/; ahí una persona es solo un ID de cuenta) a través de store.ts, la página (page.tsx) y la función de servidor que su loader consulta (state.ts). El vocabulario y las formas son los del contrato (packages/remy-auth-contract/src/notes.ts).
• src/router.tsx: el remyRouter del paquete, un router y un cliente de TanStack Query nuevos por petición, con la integración SSR de Query. src/routes/__root.tsx es el remyRoot del paquete con la configuración de esta app; TanStack Devtools (paneles de Router y Query) se pasa ahí, en el propio archivo de la app, porque su plugin de Vite devtools() lo elimina de las builds de producción solo fuera de node_modules; la comprobación de frontera de build demuestra que ni devtools ni código exclusivo de servidor llegan al navegador.
• src/parts.json: las partes del paquete que usa esta app, una por línea (@joeblew999/remy-showcase/time-zones, deferred-place y status-card del showcase, y seo-routes de la plataforma); remyApp() (en vite.config.ts) monta sus rutas y partChecks() en tests/gui.spec.ts ejecuta sus comprobaciones.
• packages/remy-ui/ (en la raíz): todo lo que comparten ambas apps; su README enumera las exportaciones.
• tests/: las comprobaciones de navegador de la app: las comprobaciones compartidas del paquete (@joeblew999/remy-ui/checks, el @joeblew999/remy-showcase/*.checks del showcase) más las comprobaciones que solo posee este repositorio (catálogos, renderizados concurrentes en servidor, hidratación, sus filas de formatos adicionales); lighthouse.spec.ts es la parte audits de vp run ci y performance.spec.ts los Core Web Vitals de la release.

El locale se pasa explícitamente a las funciones de mensaje compiladas; las peticiones concurrentes no comparten estado mutable de locale. Los catálogos son los locales en settings.json; todos salvo inglés y español fueron escritos por un agente y no están revisados. La dirección, los endónimos, las fechas, los números, la moneda y los plurales siguen las decisiones registradas en el plan de GUI.

El consumidor real del paquete es remy-auth-app, que instala el paquete publicado y ejecuta sus comprobaciones sobre páginas prerenderizadas, mientras que esta app las ejecuta sobre páginas renderizadas en servidor.

Evidencia y límitesCopy Anchor Link

vp run ci ejecuta todas las comprobaciones (vp run ready), luego las comprobaciones de navegador (test:browser), después las auditorías de Lighthouse de Google (test:audits) y, en remy-auth, una app nueva sobre el paquete de este commit (new-app), una tras otra: las auditorías miden la velocidad, así que nunca se ejecutan junto a otra ejecución de navegador. GitHub ejecuta las mismas tareas como jobs en paralelo (las comprobaciones de navegador en tres fragmentos, vp run test:browser --shard 1/3). Los Core Web Vitals sobre un deployment son cosa de la release (pnpm remy test cwv: producción, o el origin de una preview). No hay niveles que elegir y ninguna parte decide omitirse, y lo que nada ha tocado sale de la caché de Vite Plus en lugar de ejecutarse de nuevo. Qué se prueba se decide una sola vez, según lo que una comprobación puede demostrar (propietario, 2026-10-17: "you really need to decide what is tested and what isn't"):

• Una comprobación de cómo se dibuja el texto (fuentes y escrituras, separación silábica, dirección, ajuste a un teléfono, formatos) se ejecuta en un idioma por cada forma en que la app dibuja texto (checkedLocales): cada idioma al que fonts.css da su propia pila de fuentes, cada idioma han, y el inglés para la pila predeterminada compartida; hoy 9 de 13, calculados a partir de fonts.css. El español, el polaco, el turco y el alemán dibujan exactamente igual que el inglés.
• Una comprobación de un comportamiento que no depende del idioma (la política de seguridad, noindex, los parámetros de búsqueda, el formulario de demo, las páginas de error, las respuestas de la API) se ejecuta en inglés y en el primer idioma de derecha a izquierda (behaviourLocales).
• Lo que sí difiere en cada idioma se comprueba en todos: los catálogos y sus plurales (las comprobaciones unitarias), el sitemap, hreflang y el selector de idioma, y las muestras de mayúsculas/minúsculas y de separación silábica.
• Una release ejecuta todas las comprobaciones en todos los idiomas (CHECK_LOCALES=all, su script lo establece). A mano, CHECK_LOCALES acepta all, quick (inglés y árabe) o una lista separada por comas.

Lo que cubren las comprobaciones son las propias comprobaciones: tests/ y el @joeblew999/remy-ui/checks del paquete (el título de cada comprobación dice qué demuestra); los pasos del flujo que las ejecutan están en cómo trabajamos. En resumen: cada página en cada idioma sin JavaScript (idioma, dirección, metadatos, enlaces), catálogos y plurales, los valores de formatos frente a Intl, las redirecciones de entrada y la sugerencia de idioma, la hidratación, el formulario de demo y la API, los estados HTTP, el sitemap y hreflang, las cabeceras de seguridad y el nonce de CSP, las pantallas estrechas, y las páginas de docs, búsqueda y ask.

Lo de Google cubre solo las páginas de sitio (las páginas de app son noindex por diseño): Lighthouse audita /en (móvil y escritorio), /es, /ar y /en/formats (tests/lighthouse.spec.ts); Core Web Vitals, a partir del paquete lighthouse fijado de Google, evalúan /en (móvil y escritorio) y /en/formats (tests/performance.spec.ts) frente a los umbrales buenos de Google (LCP 2.5 s, CLS 0.1, TBT 200 ms, Performance de al menos 0.9), en un deployment (pnpm remy test cwv: producción salvo que se dé el origin de una preview), no en localhost.

Límites: todavía no hay organizaciones, tokens OAuth ni inicio de sesión entre apps, así que solo las páginas propias de remy-auth saben quién ha iniciado sesión (el plan de autenticación). El sitio se sirve desde su dirección de workers.dev (VITE_DEPLOY_ORIGIN en el .env de la app); el origin público de producción y Search Console son decisiones del propietario (now).

Avisos de herramientas conocidos: Node puede imprimir el aviso experimental de localStorage de Chrome DevTools; pnpm no ejecuta ningún script de instalación fuera de allowBuilds (pnpm-workspace.yaml) y puede nombrar los que ha omitido; la comprobación de paquete aislado de Vite puede informar de que las directivas use client de Base UI se ignoran en un bundle de cliente plano. Estos avisos no cambian los comportamientos probados.