# Analytics

Enable web analytics for your application with Plausible, Google Analytics or PostHog.

### Syntax

```
$ vela enable analytics [--provider <plausible|google|posthog>]
```

Without `--provider` you're prompted to pick one. Outside a terminal (CI, scripts) the flag is required. You're then asked for the provider's configuration values, and any already present in your `.env` are kept without asking.

Analytics has no dependencies. It only touches the root layout and `.env`, so it works on static sites with no backend.

### What you get

- A component at `src/lib/components/analytics/analytics.svelte` that loads the provider's script and tracks page views, including client-side navigations.
- `<Analytics />` mounted at the top level of `src/routes/+layout.svelte`, above `{@render children()}`.
- The provider's `PUBLIC_*` variables added to `.env`.

The component reads its configuration from `$env/dynamic/public` and renders nothing until the variables are set, so a local checkout with a blank `.env` sends no data. Set the same variables on each deploy target with [`vela env set`](/env/set).

### Providers

#### Plausible

```
$ vela enable analytics --provider plausible
```

| Variable | Description |
| --- | --- |
| `PUBLIC_PLAUSIBLE_DOMAIN` | The site as registered in Plausible, e.g. `example.com`. |

Loads `plausible.io/js/script.js`, which tracks client-side navigations on its own. If you self-host Plausible, change the script `src` in the component to point at your instance.

#### Google Analytics

```
$ vela enable analytics --provider google
```

| Variable | Description |
| --- | --- |
| `PUBLIC_GA_MEASUREMENT_ID` | The measurement ID, e.g. `G-XXXXXXXXXX`. |

Loads gtag.js with automatic page views turned off, then sends a `page_view` event from `afterNavigate` so each route change is counted exactly once. A `gtag` helper in `src/lib/components/analytics/gtag.ts` is available for custom events:

```ts
import { gtag } from '$lib/components/analytics/gtag';

gtag('event', 'sign_up', { method: 'email' });
```

#### PostHog

```
$ vela enable analytics --provider posthog
```

| Variable | Description |
| --- | --- |
| `PUBLIC_POSTHOG_KEY` | The project API key, e.g. `phc_...`. |
| `PUBLIC_POSTHOG_HOST` | The ingestion host. Defaults to `https://us.i.posthog.com`; use `https://eu.i.posthog.com` for EU projects or your own instance. |

Installs `posthog-js` and initialises it on mount with the `2025-05-24` defaults, which capture a pageview on every history change. Import `posthog` anywhere for custom events:

```ts
import posthog from 'posthog-js';

posthog.capture('sign_up');
```

### Switching providers

Run the command again with a different `--provider`. The component is overwritten with the new provider's implementation, the new variables are appended to `.env` and the layout is left alone, since `<Analytics />` is already mounted. Remove the old provider's variables from `.env` yourself.

### Customising

The generated component is yours to edit. Common changes are gating it behind a cookie consent banner, skipping it for signed-in admins, or adding custom events with the helpers above.

To remove analytics entirely, run [`vela disable analytics`](/disable/analytics).