Frameworks suportados
Language

Integração CLI

Use a ferramenta CLI do cside para adicionar automaticamente o cside a arquivos HTML estáticos após o processo de build.

O CLI é um método de integração independente para sites estáticos. Ele injeta automaticamente o script do cside e prefixa as URLs dos seus scripts existentes. Nenhuma tag de script manual é necessária.

Não é necessário adicionar o script manualmente

Ao usar o CLI, não há necessidade de adicionar o script do cside ao seu site. O CLI o adiciona automaticamente. Use o CLI ou a instalação manual do script, não ambos.

Apenas HTML estático

O CLI suporta apenas arquivos HTML estáticos. Para aplicações SSR, use o script manual ou o pacote Next.js.

Frameworks suportados

O CLI funciona com qualquer framework que gere arquivos HTML estáticos:

  • Astro (modo estático)
  • Next.js (exportação estática)
  • Gatsby
  • Nuxt (modo estático)
  • SvelteKit (adaptador estático)
  • Eleventy (11ty)
  • Hugo
  • VitePress / VuePress
  • Docusaurus

Qualquer outro framework que gere arquivos HTML estáticos também funcionará. O CLI detecta automaticamente as pastas de saída .next e dist, ou especifique um diretório personalizado com --dir.

Instalação

npm i @cside.dev/cli

Ou execute diretamente sem instalar:

npx @cside.dev/cli your-domain.com

Uso

Execute o CLI após o processo de build para prefixar todas as URLs de scripts nós seus arquivos HTML:

// package.json
{
  "scripts": {
    "build": "next build && npx @cside.dev/cli your-domain.com"
  }
}
Substitua o domínio

Substitua your-domain.com pelo seu domínio real configurado no cside.

Opções do CLI

Usage: @cside.dev/cli <domain> [options]

Positionals:
  domain  The domain to process                                         [string]

Options:
      --version                        Show version number             [boolean]
  -d, --dir                            Directory containing HTML files to
                                       process. Defaults to .next and dist.
                                                                        [string]
  -f                                   Process a single file instead of a
                                       directory.                       [string]
  -s, --silent                         Disable output logging.
                                                      [boolean] [default: false]
      --enable-first-party-proxy       Enable first party edge infrastructure.
                                                      [boolean] [default: false]
      --enable-script-tracking         Enable script tracking.
                                                       [boolean] [default: true]
      --enable-security-headers-check  Enable security headers check.
                                                       [boolean] [default: true]
      --excluded-scripts               Scripts to exclude from prefixing.
                                                           [array] [default: []]
  -h, --help                           Show help                       [boolean]

Exemplos

Processar um diretório específico:

npx @cside.dev/cli your-domain.com --dir ./out

Processar um único arquivo:

npx @cside.dev/cli your-domain.com -f ./dist/index.html

Excluir scripts específicos:

npx @cside.dev/cli your-domain.com --excluded-scripts "https://example.com/script.js"

Quando usar o CLI

Use o CLI se:

  • Você tem um processo de build de site estático (SSG)
  • Você quer uma integração sem código
  • Você não quer modificar seu código-fonte

O CLI automaticamente:

  1. Injeta o script do cside no seu HTML
  2. Prefixa todas as URLs de scripts de terceiros com a infraestrutura de borda do cside
  3. Adiciona os atributos referrerpolicy necessários

Content Security Policy (CSP)

Se o seu site usa uma Content Security Policy, você ainda precisa atualizá-la ao usar o CLI. Adicione proxy.csidetm.com às suas diretivas script-src e connect-src. Isso só é necessário se você usar essas diretivas. Se connect-src não estiver presente, você não precisa adicionar connect-src:

Content-Security-Policy: script-src 'self' proxy.csidetm.com; connect-src 'self' proxy.csidetm.com
Apenas se você usar essas diretivas

Você só precisa atualizar sua CSP se já tiver as diretivas script-src ou connect-src definidas. Se você não usa CSP, ou não usa essas diretivas específicas, nenhuma alteração é necessária.

O que cada diretiva permite:

  • script-src: Se você usa esta diretiva, adicione proxy.csidetm.com para permitir que o script do cside e os scripts roteados pelo Gatekeeper sejam executados
  • connect-src: Se você usa esta diretiva, adicione proxy.csidetm.com para permitir que o script do cside se comunique com a infraestrutura de borda

Para mais detalhes sobre configuração de CSP, consulte Adicionando cside à sua CSP e Configuração de Relatórios CSP.

Métodos de integração alternativos