Getting Started

Deploy Flarelytics on Cloudflare in about 5 minutes. You'll need a Cloudflare account and Node.js.

Prerequisites

A Cloudflare account (free tier works)
Node.js 20 or later
Wrangler CLI — npm install -g wrangler
Cloudflare Analytics Engine enabled (available on all plans)

wrangler login

Clone & configure

git clone https://github.com/kalle-works/flarelytics
cd flarelytics
npm install
 
cp packages/worker/wrangler.toml.example packages/worker/wrangler.toml

Edit packages/worker/wrangler.toml with your values:

wrangler.toml
name = "my-site-analytics"
account_id = "your-cf-account-id"
 
[[analytics_engine_datasets]]
binding = "ANALYTICS"
dataset = "my-site"
 
[vars]
ALLOWED_ORIGINS = "https://mysite.com"
DATASET_NAME = "my-site"

Tip
Find your account_id on the Cloudflare dashboard under Workers & Pages — it's in the right sidebar on the overview page.

Deploy worker

cd packages/worker
npm run deploy

After deploy, set the three required secrets:

# Random string — used to authenticate the dashboard and /query API
npx wrangler secret put QUERY_API_KEY
 
# Cloudflare API token (Account > Account Analytics > Read)
npx wrangler secret put CF_API_TOKEN
 
# Your Cloudflare account ID (same as in wrangler.toml)
npx wrangler secret put CF_ACCOUNT_ID

Create the CF_API_TOKEN at dash.cloudflare.com/profile/api-tokens. Permissions required: Account > Account Analytics > Read.

Add tracking script

Add one script tag to your site's <head>. The script is auto-configured — no parameters needed.

HTML
<script defer src="https://my-site-analytics.workers.dev/tracker.js"></script>

Replace my-site-analytics with your worker name. If you prefer npm:

npm
npm install @flarelytics/tracker

Enable scroll depth tracking (opt-in, uses IntersectionObserver):

HTML
<script defer src="https://my-site-analytics.workers.dev/tracker.js"
 data-scroll-depth="true"></script>

Pageviews, outbound link clicks, and time-on-page are tracked automatically — including client-side navigation in single-page apps, where a route change fires a pageview without a full reload. The tracker also skips sending anything on localhost/127.0.0.1/file:// by default, so local dev doesn't pollute production data. Both are opt-out/opt-in via attributes:

HTML
<!-- disable automatic SPA pageview tracking -->
<script defer src="https://my-site-analytics.workers.dev/tracker.js" data-no-spa></script>
 
<!-- send events even on localhost -->
<script defer src="https://my-site-analytics.workers.dev/tracker.js" data-allow-localhost></script>

Verify it works

# Health check
curl https://my-site-analytics.workers.dev/health
# { "status": "ok" }
 
# Query top pages (last 7 days)
curl -H "X-API-Key: your-query-api-key" \
 "https://my-site-analytics.workers.dev/query?q=top-pages&period=7d&site=mysite.com"

Visit any page on your site, wait a few seconds, then run the query. You should see your path in the results.

View dashboard

Deploy the dashboard alongside your worker:

cd packages/dashboard
npm run build
npx wrangler pages deploy dist

Open the dashboard URL from the deploy output and enter your QUERY_API_KEY when prompted. The dashboard works with multiple sites — use the site switcher to toggle between them.

Data retention

Event data lives entirely in Cloudflare Analytics Engine — Flarelytics has no database of its own and applies no additional retention logic on top. Analytics Engine keeps written data for three months, after which it's automatically removed. If you need longer retention, export query results on a schedule (the email reports worker is one way to do this) and store them yourself.

Was this page helpful?

Next: API Reference →

Edit this page on GitHub