Why InsightFlare?

Go beyond pageview counts without outsourcing your analytics. InsightFlare runs on your own Cloudflare account and brings website traffic, user behavior, and operational visibility together in one dashboard.

• Your infrastructure, your data. Self-host on Cloudflare Workers with D1 and Durable Objects. No third-party analytics dashboard account required.
• Understand what visitors do. Inspect sessions, journeys, funnels, custom events, UTM campaigns, and traffic-source quality.
• See what's happening now. Follow real-time activity, site performance, geography, browsers, and devices.
• Filter out the noise. Investigate bots, abnormal requests, and the difference between traffic volume and useful visits.
• Bring your AI agent. Connect through the published Skills endpoint and scoped APIs to ask questions about your analytics.
• Start small, grow as needed. One-click deployment, multiple sites and teams, optional R2 archiving, and flexible configuration.

Privacy & pricing: The tracker is designed to be cookieless and does not store raw IP addresses. Regulatory requirements and Cloudflare usage costs depend on your deployment, settings, traffic, and jurisdiction.

Explore the dashboard

Real-time activity	Visitor sessions	Event funnels
Traffic sources	Geography	Bot observability

Feature gallery

Traffic overview & acquisition

Events, sessions & visitor journeys

Audience, devices & geography

Configuration, teams & sharing

Deep event analysis & funnels

Operations, alerts & bot protection

---

Quick Start

Just click the button below:

Cloudflare will automatically clone this repository and create and bind the required resources. You need to fill in the following two secrets:

Name	Purpose
MAIN_SECRET	Root secret used to derive visitor salts, session keys, and API key hash keys
BOOTSTRAP_ADMIN_PASSWORD	Initial administrator password

MAIN_SECRET is used for security-related features and must be a random string longer than 16 characters. You can generate one at https://random.ravelloh.com/str/32. Refresh the page to get a new random string.

BOOTSTRAP_ADMIN_PASSWORD is the default administrator password. Sign in to the dashboard with the admin account and this password. You can change the username and password later on the personal settings page.

After filling in the variables, wait about 3 minutes for the deployment to finish. You can then sign in to the dashboard and start tracking traffic data. You can also customize the domain name on the project settings page. The default URL is https://insightflare.<your-cloudflare-username>.workers.dev.

---

Advanced Configuration

Enable Analytics Engine for Deep Analysis

Analytics Engine is InsightFlare's optional high-throughput analytical layer. It keeps request observability and future traffic/event projections separate from the primary database:

• REQUEST_ANALYTICS → request observation and abnormal traffic
• TRAFFIC_ANALYTICS → sampled traffic facts
• EVENT_ANALYTICS → sampled custom-event facts

This requires enabling Analytics Engine manually. Open the Cloudflare Dashboard and click the "Enable" button on the right. After that, InsightFlare will automatically bind Analytics Engine to your Cloudflare account during deployment.

Once enabled, InsightFlare writes the three datasets above. The current version uses the new REQUEST_ANALYTICS dataset for the Request Observation page; the Traffic and Event datasets are accumulated for future Analytics Engine providers. Reading the datasets requires an API Token. In system settings, enter your Cloudflare Account ID and an API Token with the "Account Analytics" read permission. Reader configuration remains in the primary D1 database. See the "Guide" button in the InsightFlare dashboard settings page for details.

Connect AI Agents for Analysis

InsightFlare exposes Skills for AI Agents. You can connect your InsightFlare deployment to agents such as OpenClaw, Codex, Claude Code, and others, so they can access InsightFlare data directly for analysis and report generation.
Send the following instruction to your Agent, replacing the domain with your deployed InsightFlare instance. Your Agent will guide you to the dashboard to create a dedicated API key for accessing InsightFlare data.

Read https://<your InsightFlare domain>/.well-known/skills.json, connect to this web analytics system, and guide me through authorization.

Then you can ask your Agent questions in natural language, for example:

"How did my site perform last month? Where did most visitors come from among the highest-traffic sites? Which pages were the most popular?"

Override Wrangler Configuration with Cloudflare Variables

In Cloudflare build environments, you can use project variables and secrets to override deployment-specific values from wrangler.toml. build:pre reads these values before deployment, writes them into the active Wrangler config, and the following wrangler deploy uses the resolved config.

Common variables:

Name	Overrides
INSIGHTFLARE_WORKER_NAME	Worker name
INSIGHTFLARE_D1_DATABASE	D1 database name
INSIGHTFLARE_D1_DATABASE_ID	D1 database ID for the DB binding
INSIGHTFLARE_SITE_SETTINGS_KV_ID	KV namespace ID for SITE_SETTINGS_KV
INSIGHTFLARE_ARCHIVE_BUCKET_NAME	R2 bucket for ARCHIVE_BUCKET
INSIGHTFLARE_ARCHIVE_PREVIEW_BUCKET_NAME	R2 preview bucket
SESSION_WINDOW_MINUTES	Session window in minutes
SCRIPT_CACHE_TTL_SECONDS	/script.js CDN cache TTL
PARQUET_WASM_URL	Parquet wasm URL
INSIGHTFLARE_EDGE_URL	InsightFlare service base URL

You can also write arbitrary [vars] entries with INSIGHTFLARE_VAR_<NAME>. For example, INSIGHTFLARE_VAR_FEATURE_FLAG=1 becomes FEATURE_FLAG = "1". When deploying with --env production, environment-specific names such as INSIGHTFLARE_PRODUCTION_D1_DATABASE_ID and INSIGHTFLARE_PRODUCTION_VAR_INSIGHTFLARE_EDGE_URL target [env.production].

Configure an R2 Bucket for Cold Archive

You only need to manually create an R2 bucket if you want to enable cold archive to R2. By default, traffic data is retained for 1 year. Expired data is compressed and retained so trends and data can still be viewed, but it cannot be filtered. R2 is optional, and the Deploy Button does not require an R2 binding by default. After R2 is enabled, you can run detailed queries on data older than 1 year.

Create a bucket named insightflare-archive in Cloudflare. Then uncomment [[r2_buckets]] in wrangler.toml as shown below:

[[r2_buckets]]
binding = "ARCHIVE_BUCKET"
bucket_name = "insightflare-archive"
preview_bucket_name = "insightflare-archive-preview"

Stay Updated

InsightFlare includes a pioneering GitHub App based automatic update system to provide the simplest update experience.

Keeping your deployment updated only takes two steps:

1. Install the GitHub App for your repository. This is only required once. Only select the repository where you deployed InsightFlare: Install InsightFlare Sync
2. When upstream updates are available, a PR will be submitted to your repository automatically. You only need to merge that request.

Want to make your own project easy to sync downstream? Implementation details: RavelloH/upstream-sync-bot (open source template) + RavelloH/InsightFlare-Bot (this project's bot instance).

Custom Event Reporting

The InsightFlare frontend SDK supports reporting custom events either through manual calls or automatically through DOM attributes.

Manual Calls

<script defer src="/script.js?siteId=YOUR_SITE_ID"></script>
<script>
  window.addEventListener("DOMContentLoaded", () => {
    window.insightflare.track("signup_click", {
      plan: "pro",
      source: "pricing",
    });
  });
</script>

Available methods:

• track(eventName, eventData?): Report a custom event.
• trackOnce(eventName, eventData?): Report the same event name only once during the current page lifecycle.
• setGlobalProperties(props): Add shared properties to subsequent events.
• clearGlobalProperties(): Clear shared properties.

Identify Users

Associate the current visit with a signed-in user without changing the anonymous visitor boundary:

<script>
  window.insightflare.identify("user-123", { name: "Alice" });
</script>

Call identify after sign-in so the current and subsequent visits can be analyzed together. Calling it before the first page view is also supported. On logout, call reset() to end the current identity, create a new anonymous visitor boundary, and prevent later events from inheriting the old account:

window.insightflare.reset();
window.insightflare.identify("user-456", { name: "Bob" });

Use reset() before switching accounts. Calling identify("user-456") alone does not create a new visitor boundary.

Automatic Reporting via DOM Attributes

<!-- 1. Default click trigger -->
<button data-insightflare-event="signup_click">Sign up now</button>
<!-- This reports: { eventName: "signup_click" } -->

<!-- 2. Click trigger with extra fields through data-insightflare-event-* -->
<button
  data-insightflare-event="signup_click"
  data-insightflare-event-plan="pro"
  data-insightflare-event-source="pricing"
>
  Sign up now
</button>
<!-- This reports: { eventName: "signup_click", eventData: { plan: "pro", source: "pricing" } } -->

<!-- 3. Click trigger with JSON extra fields -->
<button
  data-insightflare-event="signup_click"
  data-insightflare-event-data='{"plan":"pro","source":"pricing"}'
>
  Sign up now
</button>
<!-- This reports: { eventName: "signup_click", eventData: { plan: "pro", source: "pricing" } } -->

<!-- 4. Form submit trigger -->
<form
  data-insightflare-event="contact_submit"
  data-insightflare-event-trigger="submit"
  data-insightflare-event-data='{"plan":"pro","source":"landing"}'
>
  ...
</form>

Tech Stack

Layer	Technologies
Frontend	TanStack Start 1, TanStack Router, Vite 8, React 19, Tailwind CSS 4, Radix UI, shadcn, Recharts, deck.gl, maplibre-gl, Motion
Backend	Cloudflare Workers, Durable Objects, D1, R2, KV
Build	Cloudflare Vite Plugin, Wrangler 4, TypeScript 5

---

Manual Deployment

If you do not use the deploy button, deploy with the steps below:

1. Fork or clone this repository to your GitHub account
2. Create the following resources in Cloudflare:
   • D1 database
   • KV namespace
   • R2 bucket (optional, only required for cold archive to R2)
3. Edit wrangler.toml and bind the D1 and KV resources to the Worker
4. Fill in environment variables by referring to .dev.vars.example
5. Import this repository from the Worker page

Local Development

1. Clone this repository locally: git clone https://github.com/RavelloH/InsightFlare
2. Install dependencies: pnpm install
3. Create the local database: pnpm run db:migrate:local
4. Set environment variables by referring to .dev.vars.example
5. Start the development server: pnpm run dev

pnpm run dev:ui starts the Vite development server in Demo Mode and uses frontend mock data for UI testing. To enable Demo Mode with pnpm run dev, set DEMO_MODE=1.

Common Commands

Command	Purpose
pnpm run dev	Vite + Cloudflare Workers local development (use http://localhost:3000)
pnpm run dev:ui	Start the Vite dashboard development server in Demo Mode
pnpm run preview:local	Build with local resources and run Wrangler preview
pnpm run build	Cloudflare managed build entrypoint
pnpm run build:local	Local precheck + local D1 migration + build
pnpm run build:demo	Demo build without resource bindings
pnpm run deploy	Cloudflare managed deploy entrypoint
pnpm run publish	Build and publish from an allowed Cloudflare environment
pnpm run publish:demo	Build and publish the demo Worker
pnpm run check	Auto-fix format/lint, then run build + typecheck + i18n + tests + spec checks
pnpm run check:verify	Run the full check suite without automatic fixes
pnpm run typecheck	TypeScript type checking
pnpm run lint / lint:fix	ESLint
pnpm run format / format:check	Prettier
pnpm run check:i18n	Validate translation key completeness
pnpm run db:migrate:local	Local D1 migration
pnpm run db:migrate:cf	Cloudflare D1 migration
pnpm run db:migration:create	Create a new migration file
pnpm run ops:secret:main	Set the MAIN_SECRET Worker secret
pnpm run ops:secret:bootstrap-admin-password	Set the bootstrap admin password secret
pnpm run ops:tail	View online Worker logs

---

Key Configuration

Name	Meaning
SESSION_WINDOW_MINUTES	Session window in minutes (default 30)
SCRIPT_CACHE_TTL_SECONDS	CDN cache TTL for /script.js
PARQUET_WASM_URL	Parquet wasm download URL
INSIGHTFLARE_EDGE_URL	InsightFlare service base URL
MAIN_SECRET (Secret)	Root secret for derived security keys
BOOTSTRAP_ADMIN_PASSWORD (Secret)	Initial administrator password
DAILY_SALT_SECRET (Secret)	Legacy fallback for MAIN_SECRET
DASHBOARD_SESSION_SECRET (Secret)	Optional session signing override

---

License

MIT Copyright 2026 RavelloH