Shorthop

Install Shorthop on Cloudflare Workers

There are two ways in. The Deploy to Cloudflare button needs no terminal and asks only for an admin password. The setup wizard runs in a terminal and sets up everything at once.

Shorthop is an open-source (MIT) link shortener that runs as one Cloudflare Worker in your own account. It shows the clicks on each link and the payments they led to, and it stores no IP addresses and sets no cookies.

Product facts from the Shorthop repository, version 2.0.1. Other companies’ plans and limits checked on their own pages on .

What you need

  • A Cloudflare account. The free plan is enough.
  • A domain on Cloudflare for your short links, in the same account. A subdomain of a domain you already use is fine, such as go.example.com. If the domain isn’t on Cloudflare yet, add it, change the nameservers at your registrar and wait until the zone shows Active.
  • For the button: a GitHub or GitLab account. Cloudflare copies Shorthop into a new repository there, and it can be private.
  • For the wizard: Node.js 22.12 or newer and git. Allow about 20 minutes, most of it in the Cloudflare dashboard for Access and email.

With the Deploy button

  1. Press the button below and sign in to Cloudflare.
  2. Connect GitHub or GitLab. Cloudflare copies Shorthop into a new repository on your account.
  3. On the setup page, fill in ADMIN_PASSWORD: a long random password, at least 9 characters. The page lists about 20 fields. Leave every other one as it is, and keep ADMIN_AUTH at password.
  4. Press deploy. Cloudflare creates the KV namespace and the D1 database, both free, and deploys with Workers Builds.
  5. Open https://shorthop.<your-subdomain>.workers.dev/_admin/ and sign in with that password.

Deploy to Cloudflare

You start with password-only sign-in and no email. Cloudflare Access, statistics and email can be added later, from the same wrangler.toml and the Worker’s secrets. Dashboard → System status lists what is left.

Add your short domain

Links can’t be created until you add a short domain. In your copy of the repository, edit wrangler.toml (on GitHub, open the file and press the pencil icon):

routes = [{ pattern = "go.example.com", custom_domain = true }]

[vars]
SHORT_DOMAINS = "go.example.com"
FALLBACK_URL = "https://www.example.com"

Commit, and Workers Builds deploys it. The domain gets its DNS record and certificate within a few minutes, and the admin moves to https://go.example.com/_admin/. Settings → Short domains checks the domain live. Once it works, set workers_dev = false and commit, because a rate-limiting rule on your zone doesn’t cover the workers.dev address.

Moving from another shortener? Add the domain to SHORT_DOMAINS but hold back its route until your links are imported. The order is in Move your Bitly links to your own domain.

With the setup wizard

git clone https://github.com/jntegz/shorthop.git
cd shorthop
npm ci
npx wrangler login
npm run setup

npm run setup asks for your domains, how to protect the admin, your admin password and how to send email. Then it creates the KV namespace and the D1 database, writes wrangler.jsonc, uploads the secrets, deploys and checks the result.

It is safe to run again, and parts of it run on their own, such as npm run setup -- email or -- access. Add --dry-run to see what it would do without changing anything. Every dashboard step is in the setup manual.

What Workers Free allows

Shorthop doesn’t assume a paid plan. A personal shortener usually fits Workers Free. These are the limits that matter, and how Shorthop stays inside them.

LimitCloudflare allowsWhat Shorthop does
Requests100,000 a day for the whole account, reset at midnight UTCEvery request to a short domain counts, including slugs that don’t exist.
CPU time10 ms per requestThe setup tunes the admin password hash to fit: 25,000 PBKDF2 iterations on Free.
KV writes1,000 a dayOne per link save, imported link or republish.
Calls per request50 subrequestsWith WORKERS_PLAN set to free, imports, republishing and checks run in parts that fit.
Cloudflare AccessFree plan for up to 50 usersOptional: people sign in to the admin with their own accounts.
Workers PaidFrom $5 a month, 10 million requests a month includedRaises the limits. Choose it if your links must not go down.

Checked on Cloudflare’s Workers limits (requests, CPU, subrequests), Workers pricing (Paid), KV pricing (writes) and Zero Trust plans (Access). Every other service Shorthop uses is in the free-tier guide.

Website analytics write to D1, which allows 100,000 rows a day on Free. So that visitors to your website can’t use up the writes that logins and links need, Shorthop stores at most 15,000 website events a day on Free. System status warns at 80%.

The daily cap and the rate-limiting rule

On Workers Free, the 100,000 daily requests are a hard cap for the whole account. Once they are used up, Cloudflare answers with Error 1027 until midnight UTC, and every short link fails. The Worker can’t prevent that, because each request that reaches it already counts. Anyone who sends enough requests can use up the day.

A rate-limiting rule in each short domain’s zone stops one client from doing it quickly. Blocked requests stop at Cloudflare’s edge and never reach the Worker. In the Cloudflare dashboard, for the zone:

  1. Open Security → WAF → Rate limiting rules → Create rule.
  2. If incoming requests match: URI Path, wildcard /*. This covers everything the zone serves, so mind other sites on it.
  3. With the same characteristics: IP.
  4. When rate exceeds: 50 requests per 10 seconds. A visitor sends one request per click. Opening the admin loads a few dozen files, so raise the limit if the admin is on this zone and you hit it.
  5. Then take action: Block, for 10 seconds. Deploy.

Cloudflare’s Free plan allows one rate-limiting rule per zone, counting by IP over 10 seconds (rate limiting rules, checked ). Error 1027 and the midnight UTC reset are from Workers limits, checked the same day.

A rule raises the bar but doesn’t remove it: many clients, or one that stays under the limit for hours, can still use up the day. Turn off the workers.dev address once your domain works, watch one real short link with an uptime service, and choose Workers Paid if your links must not go down.

Common trip-ups

You seeWhy, and what to do
“Add a short domain first” when you create a linkThe button installs on workers.dev with no short domain yet. Add your domain to SHORT_DOMAINS and routes in wrangler.toml and commit.
Statistics stay emptyClicks are recorded, but reading them needs Analytics Engine access. Set CF_ACCOUNT_ID and add a CF_ANALYTICS_TOKEN secret with Account Analytics Read.
“Too many subrequests”, or an import stops partwayWORKERS_PLAN says paid on a Free account. Set it to free and deploy.
Logins are slow or time out on Workers FreeThe password hash is too expensive for 10 ms of CPU. Set the plan to Free in the setup, then run npm run setup -- password.
A link you just created shows the 404 pageSomeone opened it before it existed, and that miss is cached for up to 60 seconds. Wait a minute.

More in troubleshooting. Dashboard → System status checks your setup and names what’s missing.

Updating

System status shows the version you run and says when a new release is out.

  • Installed with the button: in your copy on GitHub, run Actions → Update Shorthop. It opens a pull request with the new version and keeps your wrangler.toml ids, routes and vars. Merging it deploys.
  • Installed with the wizard: git pull, npm ci, then npm run setup -- upgrade. It updates wrangler.jsonc, applies the database migrations and deploys.

Read the changelog’s Upgrading notes for each version first.

Put your own flyer up.

Your links on your domain, and every number in your own Cloudflare account. Cloudflare’s setup page asks only for an admin password.

back to the board