# Install

To install nanolytics, you add one script tag to the head of your pages. Your coding agent can do it for you, or you can add it yourself.

## Install with your agent

Open the project you want to track in Claude Code, Cursor, Codex or VS Code, and paste this into your agent:

```text
Add nanolytics to this project by following https://nanolytics.dev/AGENTS.md
```

Your agent handles the rest. You only need to approve it once:

1. Your agent asks nanolytics for a connect link for your site's domain.
2. It shows you the link and a short code. Open the link, sign in or sign up, check that the code matches, and choose your organization.
3. Your agent receives the site, its script, a secret key and the MCP config. It saves the key in `.env.local`, which stays out of your repository.
4. It adds the script to your pages, connects itself over MCP, and sends one test pageview so you know the install works before you deploy.

If your organization already has a site for that domain, your agent gets that site with a new key instead of creating a second one. You can read the exact steps your agent follows in [AGENTS.md](https://nanolytics.dev/AGENTS.md).

## Install manually

[Sign up](https://app.nanolytics.dev/api/auth/sign-in?up), add your site, and copy its script tag. It contains only your site's public key, so it's safe to commit:

```html
<script defer src="https://app.nanolytics.dev/s/pk_….js"></script>
```

You'll never need to change this line. Anything you want to track beyond pageviews and custom events is a setting you turn on later: see [Tracking options](/docs/collect).

Where the line goes depends on your framework.

### Plain HTML

Add the script to the `<head>` of every page:

```html
<head>
  <meta charset="utf-8" />
  <title>Example</title>
  <script defer src="https://app.nanolytics.dev/s/pk_….js"></script>
</head>
```

### Vite: React, Vue, Svelte

Add the script to the `<head>` of `index.html`, in your project's root:

```html
<head>
  <script defer src="https://app.nanolytics.dev/s/pk_….js"></script>
</head>
```

### Next.js

If you use the App Router, add the script inside `<body>` in `app/layout.tsx`, using `next/script`:

```tsx
import Script from 'next/script'

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script defer src="https://app.nanolytics.dev/s/pk_….js" />
      </body>
    </html>
  )
}
```

### Astro

Add the script to the `<head>` of your base layout, such as `src/layouts/Layout.astro`. The `is:inline` directive tells Astro to leave the script as it is instead of bundling it:

```html
<head>
  <script is:inline defer src="https://app.nanolytics.dev/s/pk_….js"></script>
</head>
```

### SvelteKit

Add the script to the `<head>` of `src/app.html`, before `%sveltekit.head%`:

```html
<head>
  <script defer src="https://app.nanolytics.dev/s/pk_….js"></script>
  %sveltekit.head%
</head>
```

## Single-page apps

You don't need any extra code to track route changes. The script listens for `history.pushState`, `history.replaceState` and the back and forward buttons, and records a pageview each time the page changes. Changing only the URL's fragment doesn't count as a new page.

If your app uses hash-based routing (`/#/users/1`), turn on **Hash routes** in your site's settings. Each route is then tracked as its own page and reported by its path (`/users/1`).

## Verify the installation

- **Before you deploy:** the script doesn't track anything on local dev servers (`localhost`, `127.0.0.1`, `[::1]` and `*.localhost`). To track visits while you test, add `data-local` to the script tag.
- **After you deploy:** open your site's dashboard at `https://app.nanolytics.dev`. Your first visit appears within seconds. If you're working with your agent, the MCP tool `install_status` shows when the first pageview arrived.
- **If nothing shows up:** nanolytics only accepts data from your site's allowed hosts and their subdomains. Data from any other host is dropped, and your site's health report lists it along with the host it came from. Add the missing host in Settings, or check the health report yourself:

```sh
curl -s -H "Authorization: Bearer $NANOLYTICS_KEY" https://api.nanolytics.dev/v1/sites/{site}/health
```

## Exclude your own visits

To stop counting your own visits, open the developer console on one of your site's pages and run:

```js
localStorage.nl_ignore = '1'
```

Visits from that browser are no longer counted. Remove the key to start counting them again.

## Next steps

- [Tracking options](/docs/collect): page speed, errors, session replay and outbound links.
- [Custom events](/docs/events): track signups, purchases and events from your server.
- [MCP](/docs/mcp): ask your agent about your traffic.
