Adding our script

There are two ways to add cside to your site. Choose the method that fits your setup:

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 -->

Next steps

Once you’ve added cside to your website (via CLI or manual script), 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.