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:
Add nanolytics to this project by following https://nanolytics.dev/AGENTS.mdYour agent handles the rest. You only need to approve it once:
- Your agent asks nanolytics for a connect link for your site's domain.
- 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.
- 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. - 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.
Install manually
Sign up, add your site, and copy its script tag. It contains only your site's public key, so it's safe to commit:
<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.
Where the line goes depends on your framework.
Plain HTML
Add the script to the <head> of every page:
<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:
<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:
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:
<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%:
<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, adddata-localto 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 toolinstall_statusshows 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:
curl -s -H "Authorization: Bearer $NANOLYTICS_KEY" https://api.nanolytics.dev/v1/sites/{site}/healthExclude your own visits
To stop counting your own visits, open the developer console on one of your site's pages and run:
localStorage.nl_ignore = '1'Visits from that browser are no longer counted. Remove the key to start counting them again.
Next steps
- Tracking options: page speed, errors, session replay and outbound links.
- Custom events: track signups, purchases and events from your server.
- MCP: ask your agent about your traffic.