Guia de integração do sistema de comentários CWD

Inicializei com sucesso um projeto Astro e integrei o sistema de comentários CWD.

Principais alterações

1. Inicialização do projeto: Criação de um novo projeto Astro usando o modelo basics.
2. Criação do componente: Construção de um componente Astro reutilizável [src/components/CwdComments.astro].

---
interface Props {
  apiBaseUrl: string;
  elId?: string;
  pageSize?: number;
  theme?: 'light' | 'dark';
}
const { apiBaseUrl, elId = 'comments', pageSize = 20, theme = 'light' } = Astro.props;
---

<!-- 1. Container: Usar atributos de dados para passar parâmetros ao script -->
<div
  id={elId}
  class="cwd-comments-container"
  data-el-id={elId}
  data-api-base-url={apiBaseUrl}
  data-page-size={pageSize}
  data-theme={theme}
>
</div>
<!-- 2. Importar biblioteca: Manter is:inline para carregamento a qualquer momento -->
<script is:inline src="https://unpkg.com/cwd-widget@latest/dist/cwd.js"></script>
<!-- 3. Script de inicialização: Usar módulo para importar funções utilitárias -->
<script>
  import { registerPageInit } from '@/utils/page-init';
  // Definir lógica de inicialização
  const initComments = () => {
    const containers = document.querySelectorAll('.cwd-comments-container');

    containers.forEach((container) => {
      const el = container as HTMLElement;
      // Prevenir inicialização duplicada
      if (el.children.length > 0 || el.dataset.cwdInitialized) return;
      const apiBaseUrl = el.dataset.apiBaseUrl;
      const theme = el.dataset.theme;
      const pageSize = Number(el.dataset.pageSize);

      // Verificar se biblioteca carregou
      if ((window as any).CWDComments && apiBaseUrl) {
        try {
          const comments = new (window as any).CWDComments({
            el: el,
            apiBaseUrl,
            pageSize,
            theme,
          });
          comments.mount();
          // Marcar como inicializado
          el.dataset.cwdInitialized = 'true';
        } catch (e) {
          console.error('[CWD] Falha na inicialização:', e);
        }
      } else {
        // Se script ainda carregando, fazer polling breve
        const checkTimer = setInterval(() => {
          if ((window as any).CWDComments) {
            clearInterval(checkTimer);
            // Re-acionar
            initComments();
          }
        }, 100);
        // Parar após 5 segundos
        setTimeout(() => clearInterval(checkTimer), 5000);
      }
    });
    // Retornar função de limpeza (opcional)
    return () => {
      // CWD pode não fornecer método destroy, apenas esvaziar container
    };
  };
  // 4. Registrar com PageInitManager
  registerPageInit('init-cwd-comments', initComments, { immediate: true });
</script>

3. Integração da página: Adicionado o componente de comentários à página inicial [src/pages/index.astro].

Configuração

O sistema de comentários requer uma URL de API para conectar ao backend. Atualize o atributo apiBaseUrl em [src/pages/index.astro] (ou onde quer que use este componente).

Arquivo: [src/pages/index.astro]

<CwdComments apiBaseUrl="https://cmt-api.xxx.com" />

Certifique-se de substituir https://cmt-api.xxx.com pela URL real do seu Worker implantado.

Uso do componente

Você pode usar o componente CwdComments em qualquer página ou layout Astro:

---
import CwdComments from '../components/CwdComments.astro';
---

<CwdComments
  apiBaseUrl="https://cmt-api.xxx.com"
  elId="comments"
  theme="light"
/>

Verificação

O projeto é construído com sucesso. Execute o servidor de desenvolvimento para visualizar o componente de comentários (certifique-se de que a URL da API esteja configurada corretamente):

npm run dev

Reutilização em outros projetos Astro

Para usar este sistema de comentários em outros projetos Astro, não há necessidade de reimplantar o backend ou o painel administrativo. Basta copiar o componente frontend.

1. Copiar componente: Copie [src/components/CwdComments.astro] para o diretório src/components/ do seu novo projeto. Nota: Se seu projeto usa View Transitions, certifique-se de manter a lógica registerPageInit.

2. Adicionar à página: Importe e use em sua página:

   ---
   import CwdComments from '../components/CwdComments.astro';
   ---
   
   <CwdComments apiBaseUrl="https://cmt-api.xxx.com" />

3. Identificação única: O sistema distingue automaticamente os comentários por URL da página (caminho). Desde que o domínio ou caminho do novo projeto seja diferente, os comentários serão automaticamente isolados.

Mantendo-se atualizado

Como o CWD está em desenvolvimento inicial com atualizações frequentes, siga esta estratégia de atualização:

1. Backend (API):

   • Execute git fetch upstream e git merge upstream/main no diretório cwd para sincronizar o código.
   • Execute npm install para atualizar as dependências.
   • Execute npx wrangler d1 migrations apply CWD_DB (se houver alterações no banco de dados).
   • Execute npm run deploy para implantar a nova versão do Worker.

2. Componente Frontend:

   • Atualize a versão da URL do script em src/components/widgets/CwdComments.astro:

     <script is:inline src="https://unpkg.com/cwd-widget@latest/dist/cwd.js"></script>

   • Use @latest para obter a versão mais recente (recomendado para desenvolvimento), ou especifique um número de versão (por exemplo, @0.0.5) para estabilidade.

3. Painel Administrativo:

   • Obtenha o código mais recente (mesmos passos do backend).
   • Execute npm install e npm run build.
   • Reimplante no Cloudflare Pages: npx wrangler pages deploy dist --project-name cwd-admin.

Publicado em: 6 de fev de 2026 · Modificado em: 6 de fev de 2026

RR

Construir