Adding our script

Choose the installation method that fits your site. Pinned SRI installation is available only for teams where cside has enabled it.

Option 1: CLI tool (recommended for static sites)

The CLI works with any framework that outputs static HTML files, including:

• Astro (static mode)
• Next.js (static export)
• Gatsby
• Nuxt (static mode)
• SvelteKit (static adapter)
• Eleventy (11ty)
• Hugo
• VitePress / VuePress
• Docusaurus

Any other framework that outputs static HTML files will also work. The CLI automatically detects .next and dist output folders, or you can specify a custom directory with --dir.

Install the CLI

npm install @cside.dev/cli

Or run directly without installing:

npx @cside.dev/cli@latest

Add to your build process

Add the CLI to your build script in package.json:

{
  "scripts": {
    "build": "your-build-command && npx @cside.dev/cli@latest"
  }
}

What the CLI does

When you run the CLI, it automatically:

1. Removes any existing cside script tag, so re-running it after each build never adds a duplicate
2. Injects the cside script as the first script in all HTML files, skipping node_modules and vendor
3. Adds referrerpolicy="origin" to the script tag for license verification

Common options

# Process a specific directory
npx @cside.dev/cli --dir ./out

# Inject a team-scoped script host (recommended)
npx @cside.dev/cli@latest --team-id [your-team-id]

See the CLI Integration guide for all options.

Option 2: Manual script installation

Use this method for SSR applications or if you need more control over the integration.

The manual script runs in the browser’s JavaScript engine, making it compatible with any framework or platform, regardless of your tech stack.

<!DOCTYPE html>
<html lang="en">
  <head>
    <script src="https://[your-team-id].csidetm.com/client.js" referrerpolicy="origin"></script>
    ...
  </head>
  <body>
  ...
  </body>
</html>

# With NPM
npm install @cside.dev/next

# With Yarn
yarn add @cside.dev/next

# With PNPM
pnpm add @cside.dev/next

// pages/_document.tsx
import Document, { Html, Head, Main, NextScript } from 'next/document';
import { CSideScript } from '@cside.dev/next';

export default function Document() {
  return (
    <Html lang="en">
      <Head>
        <CSideScript teamId="[your-team-id]" /> {/* <- Here */}
      </Head>
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  );
}

// layout.tsx
import { CSideScript } from '@cside.dev/next';

export default function Layout({ children }) {
  return (
    <>
      <CSideScript teamId="[your-team-id]" /> {/* <- Here */}
      {children}
    </>
  );
}

<!-- cside script -->
<script src="https://[your-team-id].csidetm.com/client.js" referrerpolicy="origin"></script>
<!-- the rest of your head code/scripts -->

Option 3: Pinned script with Subresource Integrity (SRI)

If pinned scripts are available for your team, you can install a fixed version of the cside script with a Subresource Integrity (SRI) hash, so the browser verifies the exact script bytes before running it. The filename is the SHA-256 hash of the complete script, including your team’s configuration. Publishing a new configuration or script version gets a new URL; existing pinned URLs keep working.

Open Setup > Security in the dashboard and copy the complete script tag under Latest published version. Place it synchronously near the beginning of <head>, before other scripts, keeping the URL and integrity value from the same publication:

<script
  src="https://[your-team-id].csidetm.com/[sha256].js"
  integrity="sha384-[base64-digest]"
  crossorigin="anonymous"
  referrerpolicy="origin"
></script>

The displayed version is always the latest published one. It doesn’t indicate which version is installed on your site. If the script is still preparing, return to this page and select Refresh; this checks for the publication and doesn’t rebuild the script. Settings changes can take time to appear in a new publication.

A pinned script keeps its original code and settings. To pick up new settings or script fixes, replace the complete tag with the latest one. Turning Developer Mode on or off also requires replacing or removing an already pinned script, and old pinned URLs keep working even if pinned installation is later disabled for your team.

If a publication fails to load, use Retry.

Next steps

Once you’ve added cside to your website , you’ll see your script traffic in real-time on the dashboard.

Verify it is working: Open the dashboard and open Health in the left sidebar. Script traffic appears within seconds of your first page view. There is no activation step. Your domains are listed on the team Home page and under Team Settings > Domains.