---
title: Add custom scripts
description: Load an external script on every documentation page and choose when it becomes interactive.
url: https://pr-6-a9c4e9fe1b6c.thally.app/guides/custom-scripts
---

# Add custom scripts

Load an external script on every documentation page and choose when it becomes interactive.

Add a `customScripts` array to `docs.json` when a widget or service provides an
external JavaScript URL. Thally reads that array in its root layout and renders
each entry with Next.js's `<Script>` component. This is an explicit Thally
configuration path built on Next.js; Next.js does not discover `docs.json` or
load these URLs on its own.

## Configuration

```json
{
  "customScripts": [
    {
      "src": "https://cdn.example.com/widget.js",
      "strategy": "afterInteractive"
    },
    {
      "src": "https://cdn.example.com/optional-widget.js",
      "strategy": "lazyOnload"
    }
  ]
}
```

Thally loads each configured URL on every route. The current setting accepts an
external `src`; it does not accept inline JavaScript or per-page targeting.

## Fields

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `src` | `string` | — | External script URL. Use HTTPS in production. |
| `strategy` | `string` | `"afterInteractive"` | One of the supported loading strategies below. |

## Loading strategies

| Strategy | When it runs | Use for |
| --- | --- | --- |
| `beforeInteractive` | Before page hydration | Critical scripts that must run first |
| `afterInteractive` | After hydration | Analytics, chat widgets, most third-party tools |
| `lazyOnload` | During browser idle time | Non-critical, decorative scripts |

Prefer `afterInteractive` for most tools. Use `beforeInteractive` only when the
provider must run before hydration, and measure the effect before shipping it.
Use `lazyOnload` for work that can wait until the browser is idle.

## Provider shortcuts for analytics

For Google Analytics, Plausible, or PostHog, you can use the typed
`siteConfig.analytics` field in `src/data/site.ts` instead. Thally's
`AnalyticsProvider` loads and initializes the selected provider scripts:

```ts
analytics: {
  googleAnalyticsId: 'G-XXXXXXXXXX',
  plausibleDomain: 'docs.example.com',
  posthogKey: 'phc_...',
}
```

Use `customScripts` for any provider not natively supported.

This shortcut initializes the providers. It is not a shared Thally event API,
and the open-source runtime does not add custom events for your product. Check
the selected provider's single-page application behavior and consent settings
before relying on its reports.

> **Warning:**
Only load scripts you trust. A third-party script can read page content, make
network requests, affect performance, and set cookies or similar identifiers.
If consent is required, block the script until consent is recorded; a banner
that appears after the script loads is not sufficient.

For Thally's server-side, cookie-free traffic collection, continue to
[Analytics and feedback](/guides/analytics-and-feedback).