Communitygithub.com

five-angles-company/convex-starter

Trabaja en el sitio de marketing Astro en apps/landing. Úsalo al editar la página de inicio, agregar secciones/componentes, usar shadcn/@workspace/ui en Astro, tocar el estilo de Tailwind v4 allí o agregar datos dinámicos a la página de inicio. Captura el modelo cero-JS, la corrección @source de Tailwind para archivos .astro y el patrón Convex para sitios estáticos.

¿Qué es convex-starter?

Este skill define el sitio de aterrizaje (landing) estático basado en Astro para el proyecto, ubicado en `apps/landing`. Su objetivo principal es mantener una página de inicio ligera, sin JavaScript en el cliente por defecto (modelo zero-JS), utilizando componentes de shadcn (como Button, Card) que se renderizan como HTML estático. Solo se envía JS cuando se utiliza explícitamente una directiva `client:*`, y las piezas interactivas deben agruparse en una sola isla de Astro. El skill también documenta una corrección crítica para Tailwind v4: dado que el CSS global compartido solo escanea archivos `.ts/.tsx`, es necesario agregar un `@source` adicional para que las clases utilitarias escritas en archivos `.astro` se generen correctamente. Finalmente, para necesidades dinámicas como formularios o consultas a la base de datos, se recomienda el uso de `ConvexHttpClient` en lugar de `ConvexReactClient`, ya que la página de inicio carece de un proveedor de React y autenticación de WorkOS.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/five-angles-company/convex-starter/tree/HEAD/.claude/skills/astro-landing

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Landing (Astro)

apps/landing es un sitio estático de Astro que reutiliza @workspace/ui (shadcn / Tailwind v4) para mantener la coherencia visual, con ~cero JS en el cliente.

Cuándo usarlo

  • Cualquier cambio dentro de apps/landing: secciones, componentes, estilos o la adición de datos dinámicos.

Cuándo NO usarlo

  • Las aplicaciones de Next.js o móviles — diferentes entornos de ejecución.

Modelo cero-JS

  • Por defecto, Astro renderiza los componentes de React como HTML estático durante el build. Usar un componente shadcn (<Button>, <Card>, <Badge>) de forma presentacional no envía JS al cliente.
  • El JS solo se envía si se añade una directiva client:* (client:load, client:visible). Úsala solo para partes realmente interactivas y mantén ese grupo interactivo en una única isla .tsx — el contexto de React no se comparte entre islas separadas de Astro.
  • Para enlaces con estilo de botón, prefiere <a class={buttonVariants(...)}> en lugar de un botón hidratado.

Tailwind v4 + tokens compartidos (la corrección crucial)

  • Tailwind v4 se integra mediante @tailwindcss/vite en astro.config.mjs (la integración antigua @astrojs/tailwind está obsoleta).
  • src/styles/global.css importa el tema compartido y añade una fuente de contenido de Astro:
    @import "@workspace/ui/globals.css";
    @source "./**/*.{astro,ts,tsx}";
    
    El globals.css compartido solo escanea archivos .ts/.tsx, por lo que sin el @source adicional, las clases utilitarias escritas en el marcado .astro nunca se generan (se aplican en silencio).
  • Trampa con comentarios CSS: un comentario CSS que contenga un glob **/ (por ejemplo, al describir apps/**/*) cierra el comentario prematuramente (*/), corrompiendo la regla siguiente. Mantén los globs fuera de los comentarios.

Datos dinámicos (cuando sea necesario)

  • La página de inicio no tiene proveedor de React ni autenticación de WorkOS. Para un formulario o una llamada dinámica, usa un endpoint de servidor de Astro con ConvexHttpClient de convex/browser para una mutación/consulta única — no uses ConvexReactClient/ConvexProviderWithAuth.

Gotchas

  • Importar el @workspace/ui/globals.css completo trae variables de tema y animaciones adicionales — no importa (Tailwind elimina las utilidades no utilizadas).
  • No hay next-themes aquí, por lo que la página de inicio es solo modo claro a menos que añadas un pequeño script inline para alternar la clase .dark.
  • next/font no está disponible — usa @fontsource/* o un <link> para tener la misma fuente exacta.

Verificar

  • pnpm --filter landing build → dist/ estático; index.html no tiene etiquetas <script> para páginas sin client:*.
  • Una clase usada solo en .astro (por ejemplo, bg-primary) aparece en el CSS generado (la corrección @source funciona).
  • pnpm --filter landing typecheck (astro check) pasa.

Skills relacionados