Ultra-lightweight serverless view counter optimized for headless telemetry across multiple projects.
If you're an automated agent or integrating programmatically, start with the machine-friendly integration guide at the project root:
INTEGRATION.md— agentic checklist, endpoints, CI examples, and step-by-step automation instructions. --docs/— human-friendly guides and deeper reference material (seedocs/README.md). --INTEGRATION.md— root machine-friendly guide (preferred for agents).
Agents should read INTEGRATION.md first; it contains a deterministic checklist the agent can follow to configure wrangler.toml, bind D1, run a build, deploy, and verify endpoints.
Headless Telemetry System - Send a single POST request from any project to track usage automatically.
// In any of your projects - just one line!
fetch('https://your-domain.com/api/views/project-name', {method: 'POST'});Your App → POST webhook → Cloudflare Worker → D1 Database
↓
Admin Interface (when needed)
| Usage | Monthly Cost |
|---|---|
| 1K webhooks | $0.00 (free) |
| 100K webhooks | ~$0.50 |
| 1M webhooks | ~$1.30-$3.40 |
npm run deploy
npm run db:create
npm run db:init# In Cloudflare Dashboard
ADMIN_PASSWORD=your-secure-password
ENABLE_ANALYTICS=false # Saves 50% DB rows// Webhook telemetry - works headless
fetch('/api/views/my-project', {method: 'POST'});Access admin panel at / when you need to:
- View project statistics
- Manage projects
- Monitor usage
| Variable | Purpose | Default |
|---|---|---|
ADMIN_PASSWORD |
Secure admin access | dal-login" |
ENABLE_ANALYTICS |
Track unique visitors | false |
ENABLE_ADMIN |
Enable admin panel | true |
MAX_PROJECTS |
Limit projects | 100 |
| Endpoint | Method | Purpose |
|---|---|---|
/api/views/{project} |
GET | Get statistics |
/api/views/{project} |
POST | Webhook telemetry |
/api/views/{project}/badge |
GET | SVG badge |
/api/stats |
GET | Global stats |
- ✅ Environment-based admin password
- ✅ No secrets in source code
- ✅ Optional admin panel
- ✅ Usage monitoring
Apache 2.0 - see LICENSE.md
|
|
|
|
|
|
CFlairCounter/
├── 📄 Documentation
│ ├── README.md
│ ├── USAGE.md
│ ├── DEPLOYMENT.md
│ ├── CONTRIBUTING.md
│ ├── CHANGELOG.md
│ └── LICENSE.md
├── ⚙️ Configuration
│ ├── package.json
│ ├── tsconfig.json
│ ├── wrangler.toml
│ ├── schema.sql
│ └── .gitignore (new)
├── 🌐 Frontend
│ ├── public/
│ │ ├── index.html (modern animated UI)
│ │ └── sw.js (enhanced service worker v2.0)
└── 🔧 Backend
└── functions/api/[[path]].ts (TypeScript API with admin features)
CFlairCounter now includes a password-protected admin panel for managing your projects:
- 📊 Enhanced Analytics - Detailed statistics and visitor insights
- 🛠️ Project Management - Create, edit, and delete projects
- 👥 Visitor Tracking - Monitor unique visitors and their behavior
- 🔒 Secure Access - Password-protected interface
- Click the "Admin" button on the homepage
- Enter your admin password (default:
dal-login") - Manage your projects with full control
All admin endpoints require authentication via X-Admin-Password header or password query parameter:
# Get enhanced statistics
curl -H "X-Admin-Password: dal-login"" https://your-domain.com/api/admin/stats
# Get all projects with details
curl -H "X-Admin-Password: dal-login"" https://your-domain.com/api/admin/projects
# Create a new project
curl -X POST -H "X-Admin-Password: dal-login"" \
-H "Content-Type: application/json" \
-d '{"name": "my-project", "description": "My awesome project", "initialViews": 100}' \
https://your-domain.com/api/admin/projects
# Update project view count
curl -X PUT -H "X-Admin-Password: dal-login"" \
-H "Content-Type: application/json" \
-d '{"viewCount": 500, "uniqueViews": 250}' \
https://your-domain.com/api/admin/projects/my-project/views
# Delete a project
curl -X DELETE -H "X-Admin-Password: dal-login"" \
https://your-domain.com/api/admin/projects/my-project
# Get project analytics
curl -H "X-Admin-Password: dal-login"" \
https://your-domain.com/api/admin/projects/my-project/analytics
⚠️ Security Note: Change the default password in production! Edit theADMIN_PASSWORDconstant in the API code.
Add this to your HTML or README:
<!-- Simple badge -->
<img src="https://cflaircounter.pages.dev/api/views/YOUR_PROJECT_NAME/badge" alt="Views">
<!-- Increment counter via JavaScript -->
<script>
fetch('https://cflaircounter.pages.dev/api/views/YOUR_PROJECT_NAME', { method: 'POST' });
</script>🔧 One-Click Deploy to Cloudflare Pages
-
Fork this repository
gh repo fork VKrishna04/CFlairCounter
-
Connect to Cloudflare Pages
- Go to Cloudflare Pages
- Connect your GitHub account
- Select your forked repository
- Use these settings:
- Build command:
npm run build - Build output directory:
public - Root directory:
/
- Build command:
-
Set up D1 Database
# Install Wrangler CLI npm install -g wrangler # Login to Cloudflare wrangler login # Create database wrangler d1 create cflaircounter-db # Copy the database ID to wrangler.toml # Initialize database wrangler d1 execute cflaircounter-db --file=./schema.sql
-
Deploy
wrangler pages deploy public
https://cflaircounter.pages.dev
📈 GET /api/views/{projectName}
Get view statistics for a project.
Response:
{
"projectName": "my-awesome-project",
"view_count": 1337,
"unique_views": 256,
"description": "My awesome project description",
"created_at": "2024-01-01T00:00:00.000Z"
}Example:
curl https://cflaircounter.pages.dev/api/views/my-project📊 POST /api/views/{projectName}
Increment view count for a project.
Response:
{
"projectName": "my-awesome-project",
"view_count": 1338,
"unique_views": 256,
"success": true
}Example:
curl -X POST https://cflaircounter.pages.dev/api/views/my-project🎨 GET /api/views/{projectName}/badge
Generate an SVG badge for the project.
Query Parameters:
style: Badge style (default:flat)color: Badge color (default:blue)label: Custom label (default:views)
Example:
<img src="https://cflaircounter.pages.dev/api/views/my-project/badge?color=green&label=hits" alt="Project Views">Available Colors:
blue,green,red,orange,yellow,purple,pink,gray- Hex colors:
#ff0000
📊 GET /api/stats
Get global statistics across all projects.
Response:
{
"statistics": {
"total_projects": 42,
"total_views": 12345,
"total_unique_views": 3456,
"avg_views": 294,
"max_views": 1337
},
"top_projects": [
{
"project_name": "awesome-project",
"view_count": 1337,
"unique_views": 256,
"description": "An awesome project"
}
],
"timestamp": "2024-01-01T00:00:00.000Z"
}📋 GET /api/projects
List all projects with pagination.
Query Parameters:
page: Page number (default:1)limit: Results per page (default:50, max:100)
Response:
{
"projects": [...],
"pagination": {
"page": 1,
"limit": 50,
"total": 142,
"pages": 3
}
}Showcase your project views with beautiful, customizable badges:
| Style | Example | Code |
|---|---|---|
| Default |  |
|
| Green |  |
|
| Custom Label |  |
- Node.js 18+
- npm or yarn
- Wrangler CLI
- Cloudflare account
# Clone the repository
git clone https://github.com/VKrishna04/CFlairCounter.git
cd CFlairCounter
# Install dependencies
npm install
# Set up local database
wrangler d1 create cflaircounter-db-local
wrangler d1 execute cflaircounter-db-local --file=./schema.sql
# Start development server
npm run devCFlairCounter/
├── 📁 functions/
│ └── 📁 api/
│ └── 📄 [[path]].ts # Main API handler
├── 📁 public/
│ ├── 📄 index.html # Landing page
│ └── 📄 sw.js # Service worker
├── 📄 schema.sql # Database schema
├── 📄 wrangler.toml # Cloudflare configuration
├── 📄 package.json # Dependencies
└── 📄 tsconfig.json # TypeScript config
npm run dev # Start development server
npm run deploy # Deploy to Cloudflare Pages
npm run build # Build TypeScript
npm run type-check # Type checking
npm run db:create # Create D1 database
npm run db:init # Initialize database schema- Visitor Tracking: Anonymous hash based on IP + User Agent
- No Personal Data: No names, emails, or identifiable information
- No Cookies: Client-side tracking is cookie-free
- GDPR Compliant: Minimal data collection by design
- Rate Limiting: Built-in protection against abuse
- Input Validation: Sanitized project names and parameters
- CORS Protection: Configurable origin restrictions
- SQL Injection: Prepared statements for all queries
| Metric | Value | Description |
|---|---|---|
| Response Time | <100ms | P95 globally via Cloudflare Edge |
| Uptime | 99.9% | Cloudflare's SLA guarantee |
| Cold Start | <50ms | Optimized TypeScript bundle |
| Database | <10ms | D1 query performance |
- Edge Caching: 5-minute cache for badges
- Database Indexing: Optimized queries with proper indexes
- Batch Operations: Efficient bulk database operations
- Service Worker: Client-side caching for static assets
We love contributions! Here's how you can help:
Found a bug? Open an issue with:
- Clear description
- Steps to reproduce
- Expected vs actual behavior
- Environment details
Have an idea? Start a discussion or open a feature request.
-
Fork & Clone
git clone https://github.com/YOUR_USERNAME/CFlairCounter.git
-
Create Branch
git checkout -b feature/amazing-feature
-
Make Changes
- Follow TypeScript best practices
- Add tests for new features
- Update documentation
-
Test Locally
npm run dev npm run type-check
-
Submit PR
- Clear description of changes
- Link related issues
- Add screenshots if UI changes
Real usage statistics for CFlairCounter:
Projects using CFlairCounter:
|
Awesome Project 1 github.com/user/project1 |
Cool Library github.com/user/library |
Amazing Tool github.com/user/tool |
Want your project featured? Submit a PR or open an issue!
- Enhanced Analytics Dashboard
- Referrer Tracking (optional, privacy-focused)
- API Rate Limiting Improvements
- Custom Badge Themes
- Webhooks for View Milestones
- Geographic Analytics (country-level)
- API Keys for Private Projects
- Slack/Discord Integrations
- GraphQL API Option
- Real-time WebSocket Updates
- Advanced Caching Strategies
- Multi-region Database Replication
| Feature | CFlairCounter | Google Analytics | Simple Analytics | Plausible |
|---|---|---|---|---|
| Setup Time | < 1 minute | 15+ minutes | 5 minutes | 10 minutes |
| Privacy | ✅ Anonymous | ❌ Tracks users | ✅ Privacy-focused | ✅ Privacy-focused |
| Cost | 🆓 Free | 🆓 Free* | 💰 Paid | 💰 Paid |
| Performance | ⚡ <100ms | 🐌 Varies | ⚡ Fast | ⚡ Fast |
| Complexity | 🟢 Simple | 🔴 Complex | 🟡 Medium | 🟡 Medium |
| Self-hosted | ✅ Yes | ❌ No | ❌ No | ✅ Yes |
*Google Analytics is free but has data limits and privacy concerns
Is CFlairCounter really free?
Yes! CFlairCounter is completely free and open-source. You can use our hosted version or deploy your own instance. The only costs would be if you exceed Cloudflare's generous free tier limits (which is unlikely for most projects).
How accurate are the view counts?
CFlairCounter tracks both total views and unique visitors. Unique visitors are identified by a privacy-friendly hash of IP + User Agent, which provides good accuracy while maintaining privacy.
Can I migrate from other analytics platforms?
While CFlairCounter doesn't have automatic migration tools, you can manually set initial view counts by making POST requests to the API. Contact us if you need help with large-scale migrations.
What's the rate limit?
Currently, there are soft rate limits based on Cloudflare's standard protections. For normal usage, you shouldn't hit any limits. If you need higher limits, consider deploying your own instance.
How do I delete a project?
Project deletion is not currently available through the public API for security reasons. If you need to delete project data, please open an issue on GitHub.
This project is licensed under the Apache License 2.0 - see the LICENSE.md file for details.
- ✅ Commercial use allowed
- ✅ Modification allowed
- ✅ Distribution allowed
- ✅ Patent protection
- ✅ Private use allowed
Special thanks to:
- Cloudflare - For providing amazing free infrastructure
- Hono - Lightweight web framework for the edge
- TypeScript - Making JavaScript development enjoyable
- Tailwind CSS - Utility-first CSS framework
- All contributors - Making this project better every day
Made with ❤️ by VKrishna04
A --> E A --> F A --> G A --> H
---
## 🚀 Deploy in Minutes (No Coding Required!)
### 1. Create a Free PostgreSQL Database
- [](https://filess.io/)
- Go to [Filess.io Free Cloud DB Plans](https://filess.io/) and sign up for a free account.
- Create a new PostgreSQL database (choose the latest version if possible).
- Copy your database credentials (host, port, db name, user, password).
- **Or see [this gist for more free cloud DB options](https://gist.github.com/bmaupin/0ce79806467804fdbbf8761970511b8c).**
### 2. Deploy to Render
- Click this button:
[](https://render.com/deploy?repo=https://github.com/Life-Experimentalist/CounterAPI)
- Render will detect `render.yaml` and prompt you for environment variables:
- `DB_HOST` (e.g. `your-db-host.filess.io`)
- `DB_PORT` (e.g. `5432` or as given by Filess.io)
- `DB_NAME` (your database name)
- `DB_USER` (your database user)
- `DB_PASS` (your database password)
- Fill in these values from your Filess.io dashboard.
- Choose a service name and region (pick one close to your DB for best speed).
- Click **Create Web Service** and wait for deployment.
That's it! Your API is live and ready to use. No code changes or manual setup required.
---
## 🗄️ Initializing Your Database on Filess.io
> If you are using Filess.io (or similar) for your PostgreSQL database, you must manually create the schema and table before deploying:
> Please refer to [this](https://support.filess.io/hc/wiki/articles/1710108465-how-to-create-a-table-in-postgre_sql-with-web-client) for detailed instructions.
1. **Create your PostgreSQL database** on Filess.io.
2. **Access the web client** from your Filess.io dashboard.
3. **Open a new query tab** (click the `+` at the top right).
4. **Paste and run the following SQL** (click the `>` beside the line numbers to execute):
```sql
CREATE SCHEMA myschema; -- create the schema first (replace 'myschema' with your schema name if desired)
CREATE TABLE myschema.projects (
name TEXT PRIMARY KEY,
description TEXT,
count INTEGER DEFAULT 0
);
- Refresh the tables list in the web client to confirm your table is created.
- Set the
DB_SCHEMAenvironment variable in Render to match your schema name (e.g.,myschema).
GET /projects— List all projects with their counts and descriptionsPOST /projects— Add a new project (name and optional description)PUT /projects?name={name}— Update a project's name and/or descriptionDELETE /projects/{name}— Delete a project by namePOST /projects/ping— Increment a project's count by 1GET /health— Check API and database connectivity statusGET /meta— View detailed deployment and database info (tables, columns, row counts)GET /— Serve the interactive dashboard (index.html)
- FastAPI - backend framework
- PostgreSQL - free cloud database
- Render - free cloud hosting
- GitHub Pages - static site hosting
Apache 2.0 – Free for personal, educational, and commercial use.
Want to run locally or contribute?
- Clone the repo and install dependencies:
git clone https://github.com/Life-Experimentalist/CounterAPI.git cd CounterAPI pip install -r requirements.txt psycopg2-binary - Set up a local PostgreSQL database and configure the environment variables as in the deployment instructions.
- PRs and suggestions are welcome!