npm package for React and Next.js
Add analytics to Next.js and React with one npm package. The tracker is bundled into your own code, so there is no separate file for an ad blocker to match.
npm i trckableThe package is MIT licensed, has no dependencies, and adds 2,316 bytes gzipped to a React app. CI fails above 2,560.
React
Works in Vite, React Router, Remix or anything else that renders React.
import { Analytics } from 'trckable/react'
export default function App() {
return (
<>
<Analytics site="tkb_a1b2c3d4" host="https://stats.example.com" />
{/* your app */}
</>
)
}On trckable Cloud, the host is https://cloud.trckable.com.
It starts exactly one tracker, even under React's StrictMode double-render, and counts route changes automatically.
Next.js
(The same setup as a page of its own: Analytics for Next.js.)
The most accurate setup there is: events go through your own domain, so nothing recognises them as analytics and Safari keeps the visitor cookie for 400 days instead of seven.
// app/layout.tsx
import { Analytics } from 'trckable/next'
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>
{children}
<Analytics site="tkb_a1b2c3d4" />
</body>
</html>
)
}// app/api/e/route.ts — same-origin: past analytics blocklists, 400-day Safari visitors
// With this route, remove host="https://stats.example.com" from <Analytics>
export { POST } from 'trckable/next'Then set two environment variables (the proxy key is in Settings → General → For developers):
# .env
TRCKABLE_HOST=https://stats.example.com
TRCKABLE_PROXY_KEY=your-proxy-keyThe proxy key is what lets your server tell trckable the visitor's address. See the proxy for why that matters and how it is kept safe.
Any other framework
import { init } from 'trckable'
init({ site: 'tkb_a1b2c3d4', host: 'https://stats.example.com' })Call it once, as early as you can. Vue, Svelte, Astro, Solid, Qwik and plain JavaScript all work the same way.
Any other server
trckable/server gives you the same proxy for any runtime that speaks
(Request) => Response — Hono, SvelteKit, Astro, Remix, Workers, Bun, Deno:
import { proxy } from 'trckable/server'
const trckable = proxy({ host: 'https://stats.example.com', proxyKey: process.env.TRCKABLE_PROXY_KEY })
app.post('/api/e', (c) => trckable(c.req.raw))Robots and AI crawlers
Robots never run JavaScript, so the browser script never sees them. One call in your server middleware forwards them, and only them: a request whose user agent does not look like a robot costs nothing.
// Next.js — middleware.ts
import { reportCrawler } from 'trckable/server'
export function middleware(req) {
reportCrawler({
host: 'https://stats.example.com',
site: 'tkb_a1b2c3d4',
key: process.env.TRCKABLE_PROXY_KEY,
url: req.url,
ua: req.headers.get('user-agent'),
})
}It needs the site's proxy key, never waits for an answer, and never throws, so a robot report cannot slow down or break a page. Turn the AI assistants & crawlers module on first (Settings → General → What the script records): until then nothing is recorded.
Goals
import { track } from 'trckable'
track('signup', { plan: 'pro' })Or with no code at all:
<button data-trckable-goal="signup" data-trckable-goal-plan="pro">Start trial</button>
<section data-trckable-scroll="saw_pricing">…</section>More in Goals.
Options
| Option | |
|---|---|
site | Site id (tkb_…). Required |
host | Your trckable server. Leave it out to use the same-origin route /api/e |
api | The full events endpoint, if it is not ${host}/api/e |
cookieless | No cookie, nothing stored. Call consent(true) to switch after consent |
hash | Count #/routes as pages. Also switch on Settings → General → Reports → Pages after the # |
dev | Track on localhost, including automated browsers |
domain | Cookie domain, to share visitors across subdomains |
What the package cannot do
Modules are compiled into your bundle at your build time, not chosen by the server. Turning a module on in the dashboard changes the script-tag install within the hour; an app that bundles the tracker picks the change up on its next deploy. What the script records says so where it matters.
trckable's own cookie bar is not in the package build yet, for the same reason — it is a script-tag feature today.
The CLI
The same package carries a command line tool:
npx trckable init --host https://stats.example.com --site tkb_a1b2c3d4 # shows the diff; --yes writes it
npx trckable doctor --host https://stats.example.com --url https://example.com
npx trckable mcp # run the MCP server for your assistantinit looks at the project (Next.js, React, SvelteKit, Astro, Nuxt or plain
HTML) and prints exactly what would change. It writes only with --yes, never
touches a file it did not recognise, and never edits checkout or payment code.
doctor only reads; see Install.