Guía de integración del sistema de comentarios CWD

Inicialicé con éxito un proyecto de Astro e integré el sistema de comentarios CWD.

Cambios principales

1. Inicialización del proyecto: Creación de un nuevo proyecto Astro utilizando la plantilla basics.
2. Creación del componente: Construcción de un componente Astro reutilizable [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. Contenedor: Usar atributos de datos para pasar parámetros al 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: Mantener is:inline para cargar en cualquier momento -->
<script is:inline src="https://unpkg.com/cwd-widget@latest/dist/cwd.js"></script>
<!-- 3. Script de inicialización: Usar módulo para importar funciones de utilidad -->
<script>
  import { registerPageInit } from '@/utils/page-init';
  // Definir lógica de inicialización
  const initComments = () => {
    const containers = document.querySelectorAll('.cwd-comments-container');

    containers.forEach((container) => {
      const el = container as HTMLElement;
      // Prevenir inicialización 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 si la biblioteca ha cargado
      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] Fallo de inicialización:', e);
        }
      } else {
        // Si el script aún está cargando, sondear brevemente
        const checkTimer = setInterval(() => {
          if ((window as any).CWDComments) {
            clearInterval(checkTimer);
            // Re-disparar
            initComments();
          }
        }, 100);
        // Detener después de 5 segundos
        setTimeout(() => clearInterval(checkTimer), 5000);
      }
    });
    // Devolver función de limpieza (opcional)
    return () => {
      // CWD puede no proporcionar método destroy, solo vaciar contenedor
    };
  };
  // 4. Registrar con PageInitManager
  registerPageInit('init-cwd-comments', initComments, { immediate: true });
</script>

3. Integración de página: Se agregó el componente de comentarios a la página de inicio [src/pages/index.astro].

Configuración

El sistema de comentarios requiere una URL de API para conectarse al backend. Actualice el atributo apiBaseUrl en [src/pages/index.astro] (o dondequiera que use este componente).

Archivo: [src/pages/index.astro]

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

Asegúrese de reemplazar https://cmt-api.xxx.com con la URL real de su Worker desplegado.

Uso del componente

Puede usar el componente CwdComments en cualquier página o diseño de Astro:

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

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

Verificación

El proyecto se construye con éxito. Ejecute el servidor de desarrollo para ver el componente de comentarios (asegúrese de que la URL de la API esté configurada correctamente):

npm run dev

Reutilización en otros proyectos Astro

Para usar este sistema de comentarios en otros proyectos Astro, no es necesario volver a desplegar el backend o el panel de administración. Simplemente copie el componente frontend.

1. Copiar componente: Copie [src/components/CwdComments.astro] al directorio src/components/ de su nuevo proyecto. Nota: Si su proyecto usa View Transitions, asegúrese de mantener la lógica registerPageInit.

2. Agregar a la página: Importe y use en su página:

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

3. Identificación única: El sistema distingue automáticamente los comentarios por URL de página (ruta). Mientras que el dominio o la ruta del nuevo proyecto difieran, los comentarios se aislarán automáticamente.

Mantenerse actualizado

Dado que CWD está en desarrollo temprano con actualizaciones frecuentes, siga esta estrategia de actualización:

1. Backend (API):

   • Ejecute git fetch upstream y git merge upstream/main en el directorio cwd para sincronizar el código.
   • Ejecute npm install para actualizar las dependencias.
   • Ejecute npx wrangler d1 migrations apply CWD_DB (si existen cambios en la base de datos).
   • Ejecute npm run deploy para desplegar la nueva versión del Worker.

2. Componente Frontend:

   • Actualice la versión de la URL del script en src/components/widgets/CwdComments.astro:

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

   • Use @latest para obtener la última versión (recomendado para desarrollo), o especifique un número de versión (por ejemplo, @0.0.5) para estabilidad.

3. Panel de administración:

   • Obtenga el código más reciente (mismos pasos que el backend).
   • Ejecute npm install y npm run build.
   • Vuelva a desplegar en Cloudflare Pages: npx wrangler pages deploy dist --project-name cwd-admin.

Publicado el: 6 de feb de 2026 · Modificado el: 6 de feb de 2026

RR

Construir