CreepJS 2.0 - Educational Browser Fingerprinting Platform
Privacy-first browser fingerprinting platform built as a SaaS service for developers
Live Demo: https://creepjs.org | API Docs: https://creepjs.org/docs | Playground: https://creepjs.org/playground
🎯 What is CreepJS 2.0?
CreepJS 2.0 is an educational, privacy-first browser fingerprinting platform designed to help developers understand and implement browser fingerprinting technology responsibly. It provides:
- 🔍 Interactive Demo - Visualize how browser fingerprinting works in real-time
- ⚡ RESTful API - Production-ready API running on Cloudflare Workers (<50ms response time)
- 📦 JavaScript SDK - One-line integration with TypeScript support
- 📚 Educational Content - Comprehensive guides explaining 40+ fingerprinting techniques
- 🔒 Privacy-First - Transparent, minimal data collection, user-controlled
Core Value Proposition
"3-minute browser fingerprint API integration - Developer-friendly, privacy-first"
✨ Features
🌐 Web Application
- Landing Page - Modern, responsive design with dark mode support
- Live Demo - Real-time browser fingerprint analysis with detailed breakdowns
- Interactive Playground - Test API endpoints with live examples
- Documentation Center - Complete guides, API reference, and tutorials
- 40+ Fingerprint Types - Canvas, WebGL, Audio, Fonts, Navigator, WebRTC, storage APIs, PCM, Service Workers, and more
- Performance Controls - Adaptive concurrency & idle-delay knobs keep UX smooth (see
docs/PERFORMANCE.md)
🚀 API Service
- RESTful API -
POST /v1/fingerprint for fingerprint generation
- Edge Computing - Deployed on Cloudflare Workers with global coverage
- Token Authentication - Simple API token-based auth
- Rate Limiting - Built-in rate limiting with Cloudflare KV
- <50ms Response Time - Lightning-fast with 99.9% uptime
📦 JavaScript SDK
import { getFingerprint } from '@creepjs/sdk';
const result = await getFingerprint({
token: 'cfp_your_token',
});
console.log(result.fingerprintId); // "a1b2c3d4e5f6..."
Features:
- One-line integration
- TypeScript support
- UMD/ESM builds
- <15KB gzipped
- localStorage caching
Collector Coverage Snapshot
The core engine now exposes 40+ entropy sources, spanning:
- Graphics: Canvas, WebGL, SVG, DOMRect, TextMetrics
- Hardware & Device: Screen/ScreenFrame, Color Gamut/Depth, Audio, WebRTC, Service Workers, Media Devices
- Storage & Platform: localStorage/sessionStorage/indexedDB/WebSQL, Cookie availability, plugins, Apple Pay, Private Click Measurement
- Navigator & Locale: Languages, Intl/Timezone, Reduced Motion/Transparency, HDR, Forced Colors, Vendor flavors, Architecture hints
Each collector is optional in the final payload so you can consume only the signals you need.
Need deeper tuning? Check out docs/PERFORMANCE.md for concurrency, profiling, and troubleshooting tips.
🏗️ Architecture
Tech Stack
Frontend (apps/web)
├── Next.js 15 (App Router)
├── React 19
├── TypeScript 5.7
├── Tailwind CSS + shadcn/ui
└── Deployed on: Cloudflare Pages
Backend API (apps/api)
├── Hono.js (Lightweight framework)
├── Cloudflare Workers (V8 Isolates)
├── Cloudflare KV (Storage)
└── <50ms response time globally
Core Engine (packages/core)
├── 40+ fingerprint collectors
├── MurmurHash3 + Base62 encoding
├── TypeScript
└── Modular design
SDK (packages/sdk)
├── Vanilla JavaScript
├── TypeScript support
├── UMD/ESM builds
└── <15KB gzipped
Why Cloudflare?
| Benefit | Description |
|---|
| Zero Cold Start | V8 Isolates ensure instant response |
| Global Coverage | 300+ edge locations worldwide |
| Free Tier | 100K requests/day on Workers free plan |
| Low Latency | <50ms p95 response time |
| Easy Scaling | Seamlessly scales to millions of requests |
📂 Project Structure
creepjs/
├── apps/
│ ├── web/ # Next.js 15 web application
│ │ ├── app/
│ │ │ ├── page.tsx # Home page
│ │ │ ├── demo/ # Live demo
│ │ │ ├── docs/ # Documentation center
│ │ │ ├── playground/ # API playground
│ │ │ └── fingerprint/[type]/ # Individual fingerprint pages
│ │ ├── components/ # React components
│ │ │ └── ui/ # shadcn/ui components
│ │ └── public/ # Static assets
│ │
│ └── api/ # Cloudflare Workers API
│ ├── src/
│ │ ├── index.ts # Main entry point
│ │ ├── routes/ # API routes
│ │ ├── middleware/ # Auth, CORS, rate limiting
│ │ └── utils/ # Validation, helpers
│ └── wrangler.toml # Cloudflare configuration
│
├── packages/
│ ├── core/ # Core fingerprinting engine
│ │ ├── src/
│ │ │ ├── collectors/ # 40+ fingerprint collectors
│ │ │ └── utils/ # Hashing, async helpers
│ │ └── tests/ # Unit tests
│ │
│ └── sdk/ # JavaScript SDK
│ ├── src/
│ │ └── index.ts # SDK entry point
│ └── rollup.config.js # UMD/ESM build config
│
├── docs/ # Documentation
│ ├── ARCHITECTURE.md # Technical architecture
│ ├── API.md # API reference
│ ├── SDK.md # SDK guide
│ ├── DEPLOYMENT.md # Deployment instructions
│ └── SECURITY.md # Security and privacy
│
├── .github/
│ └── workflows/ # GitHub Actions CI/CD
│
├── package.json # Monorepo root config
├── turbo.json # Turborepo configuration
├── pnpm-workspace.yaml # pnpm workspace config
└── README.md # This file
🚀 Quick Start
Prerequisites
- Node.js >= 20.9.0
- pnpm >= 9.0.0
- Cloudflare account (for deployment)
Installation
# Clone the repository
git clone https://github.com/taoyadev/creepjs.git
cd creepjs
# Install dependencies (MUST use pnpm)
pnpm install
# Start development server
pnpm dev
# This will start:
# - Next.js on http://localhost:3000
# - Wrangler (Workers) on http://localhost:8787
Build
# Build all packages
pnpm turbo run build
# Build specific app
pnpm --filter @creepjs/web build
pnpm --filter @creepjs/api build
Testing
# Run all tests
pnpm turbo run test
# Test specific package
pnpm --filter @creepjs/core test
pnpm --filter @creepjs/api test
📖 Usage
Using the SDK
Installation (script tag — recommended):
<script src="https://creepjs.org/sdk.js"></script>
An npm package (@creepjs/sdk) is planned but not yet published.
Basic Usage (works today via the script tag):
The bundle exposes a global CreepJS namespace:
<script src="https://creepjs.org/sdk.js"></script>
<script>
const client = new CreepJS.CreepJS({
token: 'cfp_your_token',
fullBundleUrl: 'https://creepjs.org/sdk.full.js',
});
client.getFingerprint().then((result) => {
console.log('Fingerprint ID:', result.fingerprintId);
});
</script>
ES Modules (after the npm package ships):
import { getFingerprint } from '@creepjs/sdk';
// Get fingerprint with API token
const result = await getFingerprint({
token: 'cfp_your_token',
endpoint: 'https://api.creepjs.org/v1/fingerprint', // optional
cache: true, // Enable localStorage caching
cacheTtl: 3600, // Cache TTL in seconds (default 86400, max 7 days)
});
console.log(result);
// { fingerprintId, confidence, coverage, timestamp, cached, ... }
Using the API Directly
Get API Token:
curl -X POST https://api.creepjs.org/v1/token \
-H "Content-Type: application/json" \
-d '{"email":"[email protected]"}'
Generate Fingerprint:
curl -X POST https://api.creepjs.org/v1/fingerprint \
-H "Content-Type: application/json" \
-H "X-API-Token: cfp_your_token" \
-d '{
"components": {
"canvas": "...",
"webgl": "...",
"navigator": "..."
}
}'
See API Documentation for complete reference.
🚢 Deployment
Deploy to Cloudflare
1. Deploy Workers (API):
cd apps/api
# Login to Cloudflare
npx wrangler login
# Create KV namespace
npx wrangler kv namespace create CREEPJS_TOKENS
# Deploy
npx wrangler deploy
2. Deploy Pages (Frontend):
# Build the project
pnpm turbo run build --filter=@creepjs/web
# Deploy to Cloudflare Pages
cd apps/web
npx wrangler pages deploy .next --project-name=creepjs
3. GitHub Actions (Automatic):
Set these secrets in GitHub repository settings:
CLOUDFLARE_API_TOKEN - Your Cloudflare API tokenCLOUDFLARE_ACCOUNT_ID - Your Cloudflare account ID
Push to main branch to trigger automatic deployment.
See DEPLOYMENT.md for detailed instructions.
🧪 Testing
Unit Tests
# Run all tests
pnpm turbo run test
# Watch mode
pnpm --filter @creepjs/core test --watch
API Tests
# Test with Cloudflare Workers test environment
pnpm --filter @creepjs/api test
E2E Tests (Playwright)
# Run E2E tests
pnpm --filter @creepjs/web test:e2e
📊 Performance Targets
| Metric | Target | Current |
|---|
| API Response Time (p95) | <100ms | ~50ms |
| SDK Bundle Size (gzipped) | <15KB | ~12KB |
| Lighthouse Score | >95 | 98 |
| Uptime | >99.9% | 99.95% |
🔒 Privacy & Security
Core Principles
- Transparency - Clear disclosure of data collection
- Minimization - Only collect necessary fingerprint data
- User Control - Provide "Do Not Track" options
- Short Retention - No long-term storage by default
Compliance
- ✅ GDPR - Consent mechanisms, data deletion API
- ✅ CCPA - California privacy options
- ✅ Cookie Banner - Clear disclosure
- ✅ Privacy Policy - Easy-to-understand terms
See SECURITY.md for details.
🗺️ Roadmap
✅ Phase 1: MVP (Complete)
🚧 Phase 2: Enhanced Features (In Progress)
📅 Phase 3: Developer Tools (Planned)
See LAUNCH_PLAN.md for the execution source of truth.
🤝 Contributing
We welcome contributions from the community! Please read our Contributing Guide before submitting PRs.
Development Workflow
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature)
- Commit your changes (
git commit -m 'Add amazing feature')
- Push to the branch (
git push origin feature/amazing-feature)
- Open a Pull Request
Code Standards
- TypeScript strict mode enabled
- ESLint + Prettier for code formatting
- Write tests for new features
- Follow conventional commits
📄 License
- Core Engine: Based on CreepJS (MIT License)
- This Project: MIT License
See LICENSE for details.
🙏 Acknowledgments
Special thanks to Abraham Juliot for developing the excellent open-source CreepJS project, which serves as the technical foundation for this platform.
📞 Contact
