KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#typescript #ai-agents #developer-tools #cli #codex #claude-code #react #dsh-plugin #mcp #open-source #dsh #deepseek-harness

VisitorBadgeReloaded

★ 85 Open GitHub ↗

An extensible and modular visitor counter with a focus on performance and reliability. Serverless architecture.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Visitor Badge Reloaded ✨

![](https://vbr.nathanchung.dev/badge?page_id=visitor-badge-reloaded-visitors&color=55acb7&style=for-the-badge&logo=Github)

[![](https://img.shields.io/badge/License-MIT%202.0-blue.svg)](https://github.com/Nathan13888/VisitorBadgeReloaded/blob/master/LICENSE)
![](https://img.shields.io/github/issues-raw/Nathan13888/VisitorBadgeReloaded?label=Issues)
![](https://img.shields.io/github/issues-closed-raw/Nathan13888/VisitorBadgeReloaded?label=Closed+Issues)
![](https://img.shields.io/github/issues-pr-raw/Nathan13888/VisitorBadgeReloaded?label=Open+PRs)
![](https://img.shields.io/github/issues-pr-closed-raw/Nathan13888/VisitorBadgeReloaded?label=Closed+PRs)

**Visitor Badge Reloaded** began as a faster, maintained, and more customizable replacement
for [visitor-badge](https://github.com/jwenjian/visitor-badge).

It now provides configurable visitor-count badges, traffic analytics, and rate-limited web
and API access while remaining compatible with the original service.

---

## 🏎️ Benchmarks

> See [benchmark/README.md](benchmark/README.md) for details.

**Results:**

| Test Name | Requests | Success Rate | Avg Response | P95 | P99 | Throughput |
| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
| **Health Check** | 100 | 100.00% | 72.19ms | 539.55ms | 672.36ms | 27.97 req/s |
| **Badge - Sequential Requests** | 50 | 100.00% | 44.30ms | 29.59ms | 1046.52ms | 18.36 req/s |
| **Badge - With Hit Counting** | 100 | 100.00% | 101.00ms | 952.35ms | 1291.92ms | 32.41 req/s |
| **Badge - Read-Only (No Hits)** | 100 | 100.00% | 63.88ms | 48.31ms | 853.43ms | 61.73 req/s |
| **Badge - Low Concurrency** | 100 | 100.00% | 161.17ms | 1244.82ms | 1244.87ms | 30.96 req/s |
| **Badge - High Concurrency** | 200 | 100.00% | 468.04ms | 1349.58ms | 4102.70ms | 31.26 req/s |
| **Badge - Customized Styling** | 100 | 100.00% | 144.87ms | 1255.16ms | 1257.63ms | 63.15 req/s |
| **Analytics API** | 50 | 100.00% | 69.31ms | 80.14ms | 116.98ms | 105.85 req/s |
| **Landing Page** | 50 | 100.00% | 23.15ms | 39.84ms | 48.45ms | 236.99 req/s |
| **Stress Test - Burst Traffic** | 500 | 100.00% | 594.97ms | 1753.77ms | 4902.85ms | 35.73 req/s |

Performed on 2026-08-06 using a MacBook Pro (M4 Pro) against the public Cloudflare-hosted service.

**Quick Start:**

```bash
# Run a quick performance check (~30 seconds)
bun run benchmark/quick-bench.ts

# Run the full benchmark suite (~5 minutes)
bun run bench

# Generate visual HTML report
bun run bench:report
```

**What's tested:**

- Response time (avg, p50, p95, p99)
- Throughput (requests per second)
- Cache effectiveness
- Concurrent request handling
- Error rates and reliability
- Real-world usage patterns

Results are saved to `benchmark/results/` and can be compared over time to track performance trends.

## ⚙️ Settings

### Badge Options

To use the options, **append** these flags to the URL of the badge!

| Option                 | Flag                     | Description                                                                                                                                                                                                                                                                                                                          |
| ---------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Colour**             | `&color=<colour>`        | Background colour of the count, on the **right-side** of the badge. Takes a hex value without the `#`, one of Shields' names (`blue`, `brightgreen`, `critical`, ...), or any CSS colour.                                                                                                                                              |
| **Label Colour**       | `&lcolor=<colour>`       | Background colour of the label, on the **left-side** of the badge. Same formats as `&color=`.                                                                                                                                                                                                                                        |
| **Style**              | `&style=<style>`         | One of `flat`, `flat-square`, `plastic`, `for-the-badge` or `social`. Anything else falls back to `flat`.                                                                                                                                                                                                                            |
| **Text**               | `&text=<label>`          | Replaces the label on the **left-side** of the badge. A single underscore renders as a space (`Total_Visits`), `__` as a literal underscore, and `--` as a literal dash.                                                                                                                                                              |
| **Label** (legacy)     | `&label=<label>`         | Legacy alias for `&text=`. If both are present, `&text=` takes precedence.                                                                                                                                                                                                                                                          |
| **Custom**             | `&custom=<format>`       | Allows a **custom string format** to be set for the count. Replaces `CNT` with the view count, so `&custom=CNT_visits` renders "42 visits".                                                                                                                                                                                          |
| **Logo**               | `&logo=<logo name>`      | Adds a logo to the badge (refer to examples). Takes any [**Simple Icons**](https://simpleicons.org/) slug (`googlechrome`), the icon title with spaces as dashes (`google-chrome`), or a `data:` URI of your own image.                                                                                                               |
| **Logo Colour**        | `&logoColor=<colour>`    | Recolours the logo. Same formats as `&color=`. Defaults to white; pass an empty value to keep the icon's own brand colour.                                                                                                                                                                                                           |
| **hit**                | `&hit=off`               | **Enabled** by default. Determines if the badge will update the count (useful for duplicated badges or badges for just viewing the count). Anything other than `true` or `yes` — including an empty value — is considered **disabled**. A disabled badge is cached for 15 seconds, so it is much cheaper to serve.                    |

`&cache=` and `&unique=` are gone. Neither did anything: `&cache=` was never read by
the code, and `&unique=` was rejected by request validation before it could be. Caching
is no longer a knob — a badge that counts is never cached, and a badge that does not
count always is. See [Caching](#caching).

**Defaults**:

- Colour: "blue"
- Label Colour: "grey"
- Style: "flat"
- Text: "Visitors"
- Logo: _no logo_
- Logo Colour: "white"
- Hit: _enabled_

### Caching

A badge that counts a view (`&hit=` enabled, the default) is never cached, by
anything. Caching it would let a cache answer GitHub's image proxy on the
service's behalf and silently swallow the view.

A badge that does not count (`&hit=false`) is cached at the Cloudflare location
serving it for 15 seconds, and says so with `Cache-Control: public, max-age=15`.
Within that window it costs no storage access at all. Several differently styled
badges for one `page_id` also share a single count lookup, so a README full of
them is one read rather than one per badge.

Responses carry `X-VBR-Cache: HIT`, `MISS`, or `BYPASS` (for the counted badges
that are never cacheable). Cache entries do not replicate between Cloudflare
locations, so a `MISS` simply means you are the first to ask in that location.

### Rate Limits

Limits exist to bound cost, not to police badges, so they are keyed on the
caller rather than on the badge — a popular badge is not throttled for being
popular.

- **Counting a view** is limited per client, per badge. Over the limit the badge
  still renders normally; the view just is not counted. A rate limit never turns
  a README into a broken image.
- **Badge requests overall** are limited per client, and only checked when the
  cache missed. Far over that limit a client gets a `429` and a "Rate Limit
  Exceeded" badge.
- **Analytics** (`/api/analytics/:pageId` and `/info/:id`) is limited per client
  and returns `429` with `Retry-After`.

Limits are enforced per Cloudflare location and are eventually consistent, so
they are approximate by design.

### Examples 🧪

#### Different text background

![](https://vbr.nathanchung.dev/badge?page_id=visitor-badge-reloaded-visitors&color=590d22&style=for-the-badge&logo=Github&hit=false)
![](https://vbr.nathanchung.dev/badge?page_id=visitor-badge-reloaded-visitors&color=a4133c&style=for-the-badge&logo=Github&hit=false)
![](https://vbr.nathanchung.dev/badge?page_id=visitor-badge-reloaded-visitors&color=ff4d6d&style=for-the-badge&logo=Github&hit=false)
![](https://vbr.nathanchung.dev/badge?page_id=visitor-badge-reloaded-visitors&color=ffb3c1&style=for-the-badge&logo=Github&hit=false)

#### Different label background

![](https://vbr.nathanchung.dev/badge?page_id=visitor-badge-reloaded-visitors&lcolor=590d22&color=555555&style=for-the-badge&logo=Github&hit=false)
![](https://vbr.nathanchung.dev/badge?page_id=visitor-badge-reloaded-visitors&lcolor=a4133c&color=555555&style=for-the-badge&logo=Github&hit=false)
![](https://vbr.nathanchung.dev/badge?page_id=visitor-badge-reloaded-visitors&lcolor=ff4d6d&color=555555&style=for-the-badge&logo=Github&hit=false)
![](https://vbr.nathanchung.dev/badge?page_id=visitor-badge-reloaded-visitors&lcolor=ffb3c1&color=555555&style=for-the-badge&logo=Github&hit=false)

#### Different style

![](https://vbr.nathanchung.dev/badge?page_id=visitor-badge-reloaded-visitors&lcolor=590d22&color=555555&style=for-the-badge&logo=Github&hit=false)
![](https://vbr.nathanchung.dev/badge?page_id=visitor-badge-reloaded-visitors&lcolor=a4133c&color=555555&style=plastic&logo=Github&hit=false)
![](https://vbr.nathanchung.dev/badge?page_id=visitor-badge-reloaded-visitors&lcolor=ff4d6d&color=555555&style=flat&logo=Github&hit=false)
![](https://vbr.nathanchung.dev/badge?page_id=visitor-badge-reloaded-visitors&lcolor=ffb3c1&color=555555&style=flat-square&logo=Github&hit=false)

#### Different text

![](https://vbr.nathanchung.dev/badge?page_id=visitor-badge-reloaded-visitors&text=Visitors&lcolor=590d22&color=555555&style=for-the-badge&logo=Github&hit=false)
![](https://vbr.nathanchung.dev/badge?page_id=visitor-badge-reloaded-visitors&text=Fans&lcolor=a4133c&color=555555&style=for-the-badge&logo=Github&hit=false)
![](https://vbr.nathanchung.dev/badge?page_id=visitor-badge-reloaded-visitors&text=Lovers&lcolor=ff4d6d&color=555555&style=for-the-badge&logo=Github&hit=false)
![](https://vbr.nathanchung.dev/badge?page_id=visitor-badge-reloaded-visitors&text=Workers&lcolor=ffb3c1&color=555555&style=for-the-badge&logo=Github&hit=false)

#### Different logo

![](https://vbr.nathanchung.dev/badge?page_id=visitor-badge-reloaded-visitors&lcolor=fff&color=000&style=for-the-badge&logo=Github&logoColor=181717&hit=false)
![](https://vbr.nathanchung.dev/badge?page_id=visitor-badge-reloaded-visitors&lcolor=000&color=fff&style=for-the-badge&logo=Canva&logoColor=00C4CC&hit=false)
![](https://vbr.nathanchung.dev/badge?page_id=visitor-badge-reloaded-visitors&lcolor=000&color=fff&style=for-the-badge&logo=4chan&logoColor=006600&hit=false)
![](https://vbr.nathanchung.dev/badge?page_id=visitor-badge-reloaded-visitors&lcolor=000&color=fff&style=for-the-badge&logo=Snapchat&logoColor=FFFC00&hit=false)

## 🚢 Migrating From Visitor Badge

If you use the original [Visitor Badge](https://github.com/jwenjian/visitor-badge), just replace the domain name:

```
ie. 'visitor-badge.glitch.me/badge?page_id=YOURPAGEID' --> 'https://vbr.nathanchung.dev/badge?page_id=YOURPAGEID'
```

### Options (Old Option) (add as a [HTTP query parameter](https://en.wikipedia.org/wiki/Query_string))

**IMPORTANT: Other than the `page_id` option, there exists additional styling options and functional options (in the future). Badges are rendered with the same library Shields.io uses, so the styling options carry over from [Shields.io](https://shields.io/). Also, all the options are specified as HTTP parameters!!!**

- `page_id=<your id>` --> identifies your badge, make this unique to yourself. eg. `<your username.visitor.badge.reloaded` or `<username>-<username>`
- `color=<colour here>` --> the hex colour of the text background, **do NOT include the `#`**
- `lcolor=<colour here>` --> the hex colour of the label background, **do NOT include the `#`**
- `style=<style name>` --> one of `flat`, `flat-square`, `plastic`, `for-the-badge` or `social`
- `text=<Some text other than "Visitors">` --> put a customizable label on your badge
- `logo` --> logo to put beside the badge, go to <https://simpleicons.org/> for the available names
- `logoColor` --> refer to `color` for the formatting
- `cache` --> **removed**, and never actually did anything. Caching is automatic now; see [Caching](#caching)

## 🥳 Contributing

1. **Star ⭐** this project.
2. **Create an Issue** on Github if there are any issues of feature requests.
3. **Submit PRs**. Refer to [Contributing](#Contributing)

## 📦 Deploying your own instance (self-hosting)

### Cloudflare

```bash
# 1. install dependencies
bun i

# 2. use own workers kv
# update `wrangler.toml` with your own kv namespace id (avoid changing binding name to avoid regenerating types)
# @see https://developers.cloudflare.com/kv/get-started/

# 3. set the visitor hashing secret (any long random string)
# used to derive per-badge, per-day keys for the estimated unique visitor
# metric. It is never persisted, so a storage dump cannot be probed for
# whether a given address visited. Skip this and hit counting still works,
# but the estimate is reported as null rather than falling back to something
# weaker.
wrangler secret put VISITOR_HASH_KEY

# 4. rate limiting needs no setup, but the `namespace_id`s under [[ratelimits]]
# in `wrangler.toml` must be unique within your Cloudflare account. If you run
# other Workers that use rate limiting, renumber them. Leaving the bindings out
# entirely is supported - the limiters fail open and badges keep working.

# 5. deploy to cloudflare
# the Simple Icons set is generated into src/generated/ as part of the build,
# so this needs devDependencies installed (`bun i` above covers it)
bun run deploy
```

## 💻 Software Used

- Cloudflare Workers
- Typescript
- Hono
- [badge-maker](https://www.npmjs.com/package/badge-maker) (the renderer behind shields.io) and [Simple Icons](https://simpleicons.org/), both bundled into the Worker

VisitorBadgeReloaded

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README