Self-host Shortener.dev on Cloudflare

Shortener.dev is open source under the AGPLv3, and the repository has everything that runs shortener.dev: the API, the dashboard and the website. You can run your own copy on your Cloudflare account and serve short links from your own domain.

Self-hosting makes sense if you want short links on your own domain, need data to stay in your Cloudflare account, or want to change how the shortener works. If you just want short links, the hosted version at shortener.dev is less work.

What runs where

The API Worker also serves the short links. Any request for a path like /spring-sale that isn't an API route is treated as a short link, so your short domain points at the same Worker as the API.

It uses these Cloudflare products: D1 for the database, two KV namespaces (cache and short link lookups), R2 for uploaded images, a Queue, Analytics Engine for clicks and request logs, rate limiting, and Email for verification codes. Check Cloudflare's pricing for the ones your account plan includes.

Run it locally

You need Node.js 24 or later and a Cloudflare account.

git clone https://github.com/Agenty/shortener.git
cd shortener
npm install

Create apps/api/.dev.vars with at least:

ENVIRONMENT=development
JWT_SECRET=a-long-random-string
APP_URL=http://localhost:5173
API_URL=http://localhost:8787
DOMAIN=localhost

Create the local database and start everything:

cd apps/api && npm run sql:dev && cd ../..
npm run dev

The API runs on http://localhost:8787, the dashboard on http://localhost:5173 and the website on http://localhost:3000. The API README lists the optional variables for Google and GitHub sign-in, Search Console verification, analytics and Stripe.

Deploy to Cloudflare

1. Create the resources from apps/api:

   npx wrangler login
   npx wrangler d1 create shortener
   npx wrangler kv namespace create KVCACHE
   npx wrangler kv namespace create LINKS
   npx wrangler r2 bucket create shortener
   npx wrangler queues create shortener-queue
   

2. Copy the D1 database_id and both KV id values into apps/api/wrangler.json, in the top-level config and in the previews block. The file in the repository points to the shortener.dev resources, so every ID has to be replaced.

3. Create the production tables with npm run sql.

4. Add each value from .dev.vars as a secret with production URLs, for example npx wrangler secret put JWT_SECRET.

5. Deploy the API with npm run deploy in apps/api, and the dashboard with npm run build && npx wrangler deploy in apps/app.

Use your own short domain

1. In the Cloudflare dashboard, add two custom domains to the API Worker: one for the API, such as api.example.com, and your short domain, such as go.example.com.
2. Set SHORT_DOMAIN in apps/api/services/links.service.ts and in apps/app/src/env.ts to your short domain.
3. Update the API URL in apps/app/src/env.ts, and in apps/web/src/lib/site.ts if you deploy the website.
4. Deploy again.

New links are returned as https://go.example.com/your-back-half.

Keep the safety checks on

The API only creates links to verified or whitelisted domains and refuses blocked ones. The check is assertVerifiedDestinations in apps/api/services/domain.service.ts. Leave it on: without it, anyone with an account on your instance can create links to phishing pages on your domain, and your short domain ends up on browser and email blocklists. See Is srt1.link safe? for what the checks do.

License

The AGPLv3 requires you to share your changes when you run a modified version as a public service. For a commercial license or help with a self-hosted setup, contact us.