Integracion CLI | cside docs

El CLI es un metodo de integracion independiente para sitios estaticos. Inyecta automaticamente el script de monitoreo de cside en tus archivos HTML. No se necesita etiqueta de script manual.

No necesitas agregar el script manualmente

Al usar el CLI, no necesitas agregar el script de cside a tu sitio. El CLI lo agrega automaticamente. Usa el CLI o la instalacion manual del script, no ambos.

Solo HTML estatico

El CLI solo soporta archivos HTML estaticos. Para aplicaciones SSR, usa el script manual o el paquete Next.js en su lugar.

Frameworks compatibles

El CLI funciona con cualquier framework que genere archivos HTML estaticos:

Astro (modo estatico)
Next.js (exportacion estatica)
Gatsby
Nuxt (modo estatico)
SvelteKit (adaptador estatico)
Eleventy (11ty)
Hugo
VitePress / VuePress
Docusaurus

Cualquier otro framework que genere archivos HTML estaticos tambien funcionara. El CLI detecta automaticamente las carpetas de salida .next y dist, o especifica un directorio personalizado con --dir.

Instalacion

npm i @cside.dev/cli

O ejecuta directamente sin instalar:

npx @cside.dev/cli

Uso

Ejecuta el CLI despues de tu proceso de compilacion para inyectar el script de cside en tus archivos HTML:

// package.json
{
  "scripts": {
    "build": "next build && npx @cside.dev/cli"
  }
}

Opciones del CLI

Usage: @cside.dev/cli [options]

Options:
      --version  Show version number                                   [boolean]
  -d, -f, --dir  Directory which include html files to process. By default we'll
                 try to look for a `.next` and `dist` folder. Also a single file
                 can be used.                                           [string]
  -s, --silent   Disable outputting processed html files.
                                                      [boolean] [default: false]
  -t, --team, --team-id
                 Inject a team-scoped cside script host using the provided team
                 ID.                                                     [string]
      --fingerprint
                 Inject cside fingerprint hosts on csidefd.com instead of the
                 default csidetm.com domain.
                                                      [boolean] [default: false]
  -h, --help     Show help                                             [boolean]

Ejemplos

Procesar un directorio especifico:

npx @cside.dev/cli --dir ./out

Procesar un solo archivo:

npx @cside.dev/cli --dir ./dist/index.html

Inyectar un host de script con ambito de equipo:

npx @cside.dev/cli --team-id 345678765434567890

Cuando usar el CLI

Usa el CLI si:

Tienes un proceso de compilacion de sitio estatico (SSG)
Quieres una integracion sin codigo
No quieres modificar tu codigo fuente

El CLI automaticamente:

Inyecta el script de cside en tu HTML
Agrega los atributos referrerpolicy necesarios

Politica de Seguridad de Contenido (CSP)

Si tu sitio usa una Politica de Seguridad de Contenido, aun necesitas actualizarla al usar el CLI. Agrega *.csidetm.com a tus directivas script-src y connect-src. Esto solo es necesario si usas esas directivas. Si connect-src no esta presente, no necesitas agregar connect-src:

Content-Security-Policy: script-src 'self' *.csidetm.com; connect-src 'self' *.csidetm.com

Solo si usas estas directivas

Solo necesitas actualizar tu CSP si ya tienes directivas script-src o connect-src definidas. Si no usas CSP, o no usas estas directivas especificas, no se necesitan cambios.

Lo que permite cada directiva:

script-src: Si usas esta directiva, agrega *.csidetm.com para permitir que el script de cside se ejecute
connect-src: Si usas esta directiva, agrega *.csidetm.com para permitir que el script de cside se comunique con la infraestructura edge

Para mas detalles sobre la configuracion de CSP, consulta Agregar cside a tu CSP y Configuracion de informes CSP.

Metodos de integracion alternativos

Instalacion manual del script: Para cualquier sitio, agrega la etiqueta de script tu mismo
Paquete Next.js: Para aplicaciones Next.js con App Router o Pages Router