Communitygithub.com

five-angles-company/convex-starter

Trabalhe no site de marketing Astro em apps/landing. Use ao editar a landing page, adicionar seções/componentes, usar shadcn/@workspace/ui no Astro, ajustar o estilo Tailwind v4 ou adicionar dados dinâmicos à landing. Captura o modelo zero-JS, a correção do Tailwind @source para arquivos .astro e o padrão Convex para sites estáticos.

O que é convex-starter?

Esta skill define o contexto e as regras para trabalhar com o site estático de marketing (Astro) localizado em apps/landing. Ela descreve o modelo zero-JS onde componentes React (como shadcn) são renderizados como HTML estático sem JavaScript do lado do cliente, a menos que diretivas client:* sejam explicitamente adicionadas. A skill documenta a correção essencial do Tailwind v4, onde o arquivo global.css precisa incluir `@source "./**/*.{astro,ts,tsx}"` para que classes utilitárias usadas em templates .astro sejam geradas, evitando um erro silencioso. Para dados dinâmicos, recomenda o uso de endpoints de servidor Astro com ConvexHttpClient (em vez de ConvexReactClient), mantendo o site leve. Também adverte sobre comentários CSS com globs como `**/` que podem interromper prematuramente o comentário e sobre a ausência de next-themes. A skill suporta as plataformas Claude Code, Cursor e Codex, e seu conteúdo é essencial para qualquer desenvolvedor que editar a landing page sem introduzir JavaScript desnecessário ou quebrar a geração de estilos.

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

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Landing (Astro)

apps/landing é um site estático Astro que reutiliza @workspace/ui (shadcn / Tailwind v4) para manter a identidade visual, com ~zero JS do lado do cliente.

Quando usar

  • Qualquer alteração em apps/landing: seções, componentes, estilos ou adição de dados dinâmicos.

Quando NÃO usar

  • Os aplicativos Next.js ou mobile — runtimes diferentes.

Modelo zero-JS

  • O Astro renderiza componentes React como HTML estático em tempo de build por padrão. Usar um componente shadcn (<Button>, <Card>, <Badge>) de forma apresentacional não envia JS ao cliente.
  • JS só é enviado se você adicionar uma diretiva client:* (client:load, client:visible). Use-a apenas para peças genuinamente interativas e mantenha esse grupo interativo em uma única ilha .tsx — o contexto React não é compartilhado entre ilhas Astro separadas.
  • Para links estilizados como botões, prefira <a class={buttonVariants(...)}> em vez de um botão hidratado.

Tailwind v4 + tokens compartilhados (a correção essencial)

  • O Tailwind v4 é integrado via @tailwindcss/vite em astro.config.mjs (a integração antiga @astrojs/tailwind está obsoleta).
  • src/styles/global.css importa o tema compartilhado e adiciona uma fonte de conteúdo Astro:
    @import "@workspace/ui/globals.css";
    @source "./**/*.{astro,ts,tsx}";
    
    O globals.css compartilhado escaneia apenas .ts/.tsx, então sem o @source adicionado, classes utilitárias escritas em markup .astro nunca são geradas (silenciosamente não se aplicam).
  • Armadilha de comentário CSS: um comentário CSS que contenha um glob **/ (ex.: descrevendo apps/**/*) fecha o comentário prematuramente (*/), corrompendo a regra seguinte. Mantenha globs fora de comentários.

Dados dinâmicos (quando necessário)

  • A landing não tem provider React nem autenticação WorkOS. Para um formulário/chamada dinâmica, use um endpoint de servidor Astro com ConvexHttpClient de convex/browser para uma mutação/consulta única — não ConvexReactClient/ConvexProviderWithAuth.

Pegadinhas

  • Importar o @workspace/ui/globals.css completo puxa variáveis/animações extras do tema — ok (Tailwind elimina utilitários não usados).
  • Não há next-themes aqui, então a landing é apenas modo claro, a menos que você adicione um pequeno script inline de alternância .dark.
  • next/font não está disponível — use @fontsource/* ou um <link> para paridade exata de fontes.

Verificar

  • pnpm --filter landing build → dist/ estático; index.html não tem tags <script> para páginas sem client:*.
  • Uma classe usada apenas em .astro (ex.: bg-primary) aparece no CSS compilado (a correção @source funciona).
  • pnpm --filter landing typecheck (astro check) passa.

Habilidades Relacionadas