https://github.com/ravelloh/insightflare
A powerful, privacy-friendly open source web analytics tool that runs entirely on Cloudflare.
https://github.com/ravelloh/insightflare
analytics cloudflare cloudflare-workers cookieless durable-objects edge-computing gdpr-compliant nextjs privacy-first react serverless typescript web-analytics
Last synced: about 2 hours ago
JSON representation
A powerful, privacy-friendly open source web analytics tool that runs entirely on Cloudflare.
- Host: GitHub
- URL: https://github.com/ravelloh/insightflare
- Owner: RavelloH
- License: mit
- Created: 2026-02-28T17:21:17.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-07-03T05:26:27.000Z (about 7 hours ago)
- Last Synced: 2026-07-03T06:25:28.783Z (about 6 hours ago)
- Topics: analytics, cloudflare, cloudflare-workers, cookieless, durable-objects, edge-computing, gdpr-compliant, nextjs, privacy-first, react, serverless, typescript, web-analytics
- Language: TypeScript
- Homepage: https://demo.insightflare.net
- Size: 11 MB
- Stars: 195
- Watchers: 0
- Forks: 9
- Open Issues: 4
-
Metadata Files:
- Readme: .github/readme/README.en.md
- Changelog: changelog/v0.1.0.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
- Support: SUPPORT.md
Awesome Lists containing this project
README
# InsightFlare
| English | [中文](/.github/readme/README.zh.md) |
> A powerful, privacy-friendly open source web analytics tool that runs entirely on Cloudflare.
Demo: [http://insight-demo.ravelloh.com](http://insight-demo.ravelloh.com/)
Fully compliant with GDPR, with no cookies, so visits can be tracked legally without asking users for consent. Its original smart tracking intensity mechanism automatically adjusts visitor identifier persistence based on regional privacy regulations, balancing data integrity with privacy protection.
The frontend analytics SDK is only about 3 KB after gzip compression and is distributed through Cloudflare's global CDN for excellent performance. The SDK includes custom event tracking (`data-insightflare-event`) and performance metric tracking.
The multilingual dashboard uses unprecedented visualizations to give you a clear picture of traffic data. Its original multilingual place-name translation feature automatically translates more than 95% of place names worldwide, making it easy to understand where visitors come from.
Cloudflare's free quotas can support free tracking for 100,000 visits per day, with excellent performance from edge computing.
InsightFlare does not store raw IP information. It relies on Cloudflare for geolocation resolution, protecting user privacy while still providing highly accurate analytics.
---
## Quick Start
Just click the button below:
[](https://deploy.workers.cloudflare.com/?url=https%3A%2F%2Fgithub.com%2FRavelloH%2FInsightFlare)
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](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..workers.dev`.
## Features
### Comprehensive Traffic Dimension Tracking
### Real-Time Visitor Monitoring
### Page-Level Traffic Analytics
### Track Real Visitor Performance
### Compare Traffic Quality Across Sources
### Track UTM Campaign Performance
### Record and Analyze Custom Events
### Inspect Every Session
### Understand Every Visitor
### Track Return Visits
### Understand Geographic Distribution and Market Intelligence
### View Visitor Device Details
### Understand Browsers and Their Capabilities
### Adjust Tracking Settings Anytime, Without Changing the Frontend SDK
### Designed for Team Collaboration
### Understand System Health at a Glance
### Complete Multilingual Translation
### Public Sharing System
### Clearly Scoped API System
### Scheduled Tasks
### Deep Analysis for JSON Custom Events
### Analyze Visits and Events with Funnels
### Receive Scheduled or Conditional Email Notifications
---
## Advanced Configuration
### 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.
```txt
Read https:///.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:
```txt
"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_`. 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:
```toml
[[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](https://github.com/apps/insightflare-sync/installations/new)
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](https://github.com/RavelloH/upstream-sync-bot) (open source template) + [RavelloH/InsightFlare-Bot](https://github.com/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
```html
window.addEventListener("DOMContentLoaded", () => {
window.insightflare.track("signup_click", {
plan: "pro",
source: "pricing",
});
});
```
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.
#### Automatic Reporting via DOM Attributes
```html
Sign up now
Sign up now
Sign up now
...
...
```
## Tech Stack
| Layer | Technologies |
| -------- | ---------------------------------------------------------------------------------------------- |
| Frontend | Next.js 16, React 19, Tailwind CSS 4, Radix UI, shadcn, Recharts, deck.gl, maplibre-gl, Motion |
| Backend | Cloudflare Workers, Durable Objects, D1, R2, KV |
| Build | OpenNext for Cloudflare, 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: `npm install`
3. Create the local database: `npm run d1:migrate:local`
4. Set environment variables by referring to `.dev.vars.example`
5. Start the development server: `npm run dev`
Set `NEXT_PUBLIC_DEMO_MODE=1` to make the development server automatically enable Demo Mode and use frontend mock data for UI testing.
## Common Commands
| Command | Purpose |
| --------------------------------- | ------------------------------------------------------------------ |
| `npm run dev` | Local Worker + dashboard development (use `http://127.0.0.1:8787`) |
| `npm run dev:ui` | Start only the Next.js UI dev server in Demo Mode |
| `npm run check` | Run typecheck + lint + format + i18n + tests + spec checks |
| `npm run typecheck` | TypeScript type checking |
| `npm run lint` / `lint:fix` | ESLint |
| `npm run format` / `format:check` | Prettier |
| `npm run check:i18n` | Validate translation key completeness |
| `npm run d1:migrate:local` | Local D1 migration |
| `npm run d1:migrate:remote` | Remote D1 migration |
| `npm run d1:migration:create` | Create a new migration file |
| `npm run cf: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](/LICENSE) Copyright 2026 RavelloH