Fully branded short URLs via continuous integration on vanityURLs

Redirects as Code: Managing Short Links the GitOps Way

Mon, 10 Mar 2025 00:00:00 +0000

Most URL shorteners are black boxes. You log in through a web UI, create a link, and hope the service stays running. When something breaks — a link stops working, a campaign URL points to the wrong page, someone accidentally deleted a redirect — there’s no audit trail, no rollback, no way to know who changed what and when.

vanityURLs takes a different approach: your redirects live in a plain text file, in a Git repository, deployed via Cloudflare Pages. This is GitOps applied to URL management.

Why vanityURLs? The case for owning your short links

Mon, 20 Jan 2025 00:00:00 +0000

URL shorteners look like a solved problem. Pick a free service, paste a long URL, get a short one. Done. For years, services like bit.ly, goo.gl, and TinyURL made this trivially easy and free.

Then bit.ly slashed free accounts to 10 links per month. Google killed goo.gl. Millions of published links — in books, presentations, printed materials, email footers — started dying.

The problem isn’t that these services got worse. It’s that they were always the wrong architectural choice.

Say Goodbye to Third-Party URL Shorteners: Introducing VanityURLs

Fri, 16 Aug 2024 00:00:00 +0000

For years, URL shortening services like bit.ly, goo.gl, and tinyurl have been go-to tools for anyone needing to share compact links. These services were free and convenient — but the landscape is changing, and not for the better.

The Problem with Relying on Third-Party Services

In January 2024, Bitly — the leading URL shortener since 2008 — made a significant change: accounts created after 2018 were suddenly limited to just 10 links per month. For those who had relied on the previous limit of 10,000 free links per month, this was a major blow.

Accessibility Statement

Mon, 01 Jan 0001 00:00:00 +0000

Last reviewed: April 2026. This statement applies only to vanityURLs.link, not to self-hosted vanityURLs deployments.

We’re committed to making this site usable by as many people as possible, regardless of ability or assistive technology. This statement explains what we’ve implemented, what we know is imperfect, and how to test or report accessibility issues.

Conformance status

We target WCAG 2.1 Level AA and the site is partially conformant — the majority of criteria are met, with a small number of known gaps documented below.

Admin dashboard

Mon, 01 Jan 0001 00:00:00 +0000

The admin dashboard is intentionally read-only. It is an operational view over the generated registry, not a content management system.

It reads:

/v8s.json

What it shows

Route inventory
Effective state
Exact vs splat routing
Expiry review
Metadata quality
Routing-table behavior
Expiring-soon and missing-metadata filters

Analytics remain in Umami or Fathom. The dashboard is the routing and lifecycle plane; analytics tools are the measurement plane.

Protection

Protect /_stats, /_stats/*, /_tests, and /_tests/* with Cloudflare Access. The Worker validates the Access assertion header and fails closed when protection is incomplete.

bhdicaire.com

Mon, 01 Jan 0001 00:00:00 +0000

bhdicaire.com is the personal vanity domain of Benoît H. Dicaire, founder and primary maintainer of vanityURLs. It was the first deployment that proved the concept worked, predating the project’s open-source release.

All links are managed via the lnk CLI script and deployed automatically through Cloudflare Pages on every push to the main branch.

Blocklist policy

Mon, 01 Jan 0001 00:00:00 +0000

vanityURLs uses defaults/v8s-blocklist.json as the upstream trust-and-safety policy. Instance-specific policy lives in custom/v8s-blocklist.json and is merged over the defaults.

The goal is to protect the reputation of a short-link domain by reducing phishing, malware, redirect chains, and risky URL forms.

A redirect engine is powerful infrastructure. Do not use a vanityURLs instance to hide malicious destinations, bypass trust systems, launder another shortener chain, disguise affiliate or tracking links without disclosure, or route people to content they did not reasonably expect. A short-link domain earns trust slowly and can lose it very quickly.

CLI

Mon, 01 Jan 0001 00:00:00 +0000

The repo-local CLI is ./scripts/lnk. It is a Node executable, so it works on macOS, Linux, Windows, and CI environments where Node and Git are available.

Bash is not required for link management. The Zsh helper remains optional and separate.

Requirements

Node.js 20 or newer
npm
Git
Wrangler for deployment commands
A Cloudflare account only when deploying or managing Worker secrets

On Windows, run the commands from PowerShell, Windows Terminal, or a Git-aware shell. The CLI itself does not require WSL.

Cloudflare Workers

Mon, 01 Jan 0001 00:00:00 +0000

The current vanityURLs runtime deploys as a Cloudflare Worker with static assets. The Worker is the origin for the short-link hostname, so use a Worker Custom Domain instead of the older Pages _redirects or DNS AAAA 100:: route pattern.

Cloudflare splits the required vanityURLs settings across three different dashboard areas. Check the dashboard scope before changing a setting; being in the right Cloudflare product is not always enough.

Contribution Guide

Mon, 01 Jan 0001 00:00:00 +0000

Contributions are welcome! vanityURLs recognizes all types of contributions based on the all-contributors specification.

Ways to contribute

Bug reports — open an issue in the GitHub repository
Documentation — improve or translate docs in the website repository
Code — submit a pull request with fixes or new features
Community — help others in GitHub Discussions

This project is released with a Contributor Code of Conduct. By participating you agree to abide by its terms.

Pull request guidelines

Keep PRs focused — one feature or fix per PR
Update documentation for any user-facing changes
Add a clear description of what the PR does and why

Questions?

Start a discussion in GitHub Discussions before opening a PR for large changes.

Custom overrides

Mon, 01 Jan 0001 00:00:00 +0000

Use custom/ for instance-owned files. This keeps v8s.link-style deployments upgradable because default pages, Worker logic, and product policy can move forward without mixing in every local brand choice.

Build order

Copy defaults/public/ into build/
Overlay custom/public/ when it exists
Copy the default defaults/public/_stats/index.html
Overlay custom/public/_stats/index.html when it exists
Build v8s.json from custom/v8s-links.txt when it exists, otherwise from defaults/v8s-links.txt
Merge defaults/v8s-blocklist.json, optional custom/v8s-blocklist.json, and optional generated blocklist data

Recommended custom files

custom/v8s-links.txt
custom/v8s-schedules.json
custom/v8s-blocklist.json
custom/public/v8s-logo.svg
custom/public/v8s-redirected.svg
custom/public/favicon.svg

Only add HTML or CSS overrides when brand assets and content files are not enough.

Default links

Mon, 01 Jan 0001 00:00:00 +0000

The default link registry is defaults/v8s-links.txt. A production instance normally replaces it with custom/v8s-links.txt, but the defaults are useful because they show the supported shape of a real registry.

Namespaced examples

The default file groups links by human task area:

Prefix	Examples	Purpose
`ai/`	`ai/chat`, `ai/claude`, `ai/hf`	AI tools and model resources
`edu/`	`edu/a`, `edu/d`, `edu/s`	Research and academic lookup
`g/`	`g/cal`, `g/drive`, `g/meet`	Google productivity surfaces
`meet/`	`meet/g`, `meet/t`, `meet/z`	Meeting-room aliases
`pkg/`	`pkg/d`, `pkg/n`, `pkg/p`, `pkg/r`	Package registries
`social/`	`social/fb`, `social/ig`, `social/x`	Social profiles
`v8s/`	`v8s/code`, `v8s/doc`, `v8s/status`	vanityURLs project links

Namespacing keeps the root short-link space clean while still allowing memorable URLs such as v8s.link/social/x.

felx.cc

Mon, 01 Jan 0001 00:00:00 +0000

felx.cc is the personal vanity domain of Félix Léger, one of the creators of vanityURLs. It was one of the first production deployments of the project and serves as the live proof of concept.

All links at felx.cc are managed via a plain-text _redirects file hosted on GitHub and deployed automatically to Cloudflare Pages on every push.

Impressum

Mon, 01 Jan 0001 00:00:00 +0000

Last reviewed: April 2026

This notice is provided in accordance with § 5 DDG (Digitale-Dienste-Gesetz, Germany), § 5 ECG (E-Commerce-Gesetz, Austria), and equivalent transparency obligations for users in German-speaking countries.

License

Mon, 01 Jan 0001 00:00:00 +0000

vanityURLs is an open source software released under the MIT License.

MIT License

Copyright (c) 2024 Benoît H. Dicaire

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

The full license text is also available in the GitHub repository

Link format

Mon, 01 Jan 0001 00:00:00 +0000

v8s-links.txt is the human-authored source of truth for links. Each non-empty, non-comment row is pipe-delimited:

slug|target|state|title|description|tags|owner|expires_at|notes

Field	Required	Description
`slug`	yes	Slash-delimited alias path, without leading `/`
`target`	yes	Absolute `http` or `https` URL, or a hostname normalized to `https://`
`state`	no	`permanent`, `ephemeral`, `expired`, `disabled`, `maintenance`, `deactivated`
`title`	no	Dashboard title
`description`	no	Human-readable purpose
`tags`	no	Comma-separated tags
`owner`	recommended	Accountability label
`expires_at`	no	ISO date or timestamp
`notes`	no	Internal notes

Exact links

social/x|https://x.com/vanityURLs|permanent|X / Twitter|Social profile|social,x|v8s||

The link resolves only /social/x.

Migration guide

Mon, 01 Jan 0001 00:00:00 +0000

Use this guide when moving from the older Cloudflare Pages _redirects model to the current Worker model used by v8s.link.

What changed

wrangler.toml is the deployment source of truth
Static files are served through the Worker assets binding named ASSETS
The build copies defaults/, overlays custom/, and generates build/v8s.json
custom/v8s-links.txt is preferred when it exists; otherwise the build uses defaults/v8s-links.txt
/_stats and /_tests are protected by Cloudflare Access
Server-side analytics are emitted by the Worker
Scanner probes and risky destinations are blocked by v8s-blocklist.json

Convert legacy .lnk files

Legacy rows looked like this:

Privacy

Mon, 01 Jan 0001 00:00:00 +0000

Last reviewed: April 2026

This policy applies only to the current website (e.g., vanityURLs.link), not to sites built with vanityURLs.

vanityURLs.link is a documentation website for an open-source project. We take your privacy seriously.

Quickstart

Mon, 01 Jan 0001 00:00:00 +0000

vanityURLs is a Git-managed short-link engine for your own domain. The current runtime deploys as a Cloudflare Worker with static assets. The build starts from defaults/, overlays your custom/ files, generates build/v8s.json, and publishes the Worker with Wrangler.

What you need

A GitHub repository based on vanityURLs/vanityURLs
A short domain, such as the public reference domain v8s.link
A Cloudflare account with the domain in Cloudflare DNS
Node.js 20 or newer and npm
Git
Wrangler connected to the Cloudflare account that owns the Worker

The primary CLI is ./scripts/lnk, a Node script that runs on macOS, Linux, Windows, and CI environments where Node and Git are available. Bash is not required for link, schedule, or blocklist management. The optional scripts/v8s.zsh helper is only for Zsh users who want to open known redirects from their shell.

Release checklist

Mon, 01 Jan 0001 00:00:00 +0000

Use this checklist before launching a new instance or promoting a major upgrade. A v8s instance is simple, but a short-link domain still attracts scanners, bots, and abuse attempts.

Repository

Run npm run clean.
Refresh upstream defaults/ and scripts/ with the upgrade workflow.
Keep all instance-owned files in custom/.
Run npm run check.
Review generated registry and blocklist changes.
Commit and deploy from a clean working tree.

Worker and assets

Confirm the Worker has an ASSETS binding.
Confirm the custom domain points to the Worker.
Disable public workers.dev and preview URLs if they are not part of the service.
Protect /_stats and /_tests with Cloudflare Access.
Keep /_stats/* and /_tests/* policies narrow.
Confirm the Worker accepts only GET, HEAD, and OPTIONS.
Confirm private implementation assets return 404.

Cloudflare domain configuration

In Cloudflare, the relevant settings are split across three places:

Reporting a Vulnerability

Mon, 01 Jan 0001 00:00:00 +0000

If you discover a security vulnerability in vanityURLs

Please report it responsibly with GitHub Security Advisories

Do not open a public GitHub issue for security vulnerabilities

Repository layout

Mon, 01 Jan 0001 00:00:00 +0000

The repository separates product defaults from instance-owned changes. That separation is what makes v8s.link useful as a reference implementation and lets future instances update upstream code without losing local branding.

defaults/
 public/ # default HTML, CSS, icons, localized pages
 public/_stats/ # read-only stats dashboard shell
 v8s-links.txt # demo/default link registry
 v8s-schedules.json # optional schedule rules
 v8s-blocklist.json # default trust-and-safety policy
 v8s-blocklist-categories.json

custom/
 public/ # instance branding and page overrides
 v8s-links.txt # instance-owned links
 v8s-schedules.json # instance schedules
 v8s-blocklist.json # instance allow/block policy

scripts/
 src/
 worker.mjs # canonical Worker runtime source
 worker.test.mjs # Worker runtime tests
 lnk # Node CLI for links and schedules
 build.mjs # build defaults + custom into deploy output
 clean.mjs # remove generated output
 upgrade.mjs # refresh product-owned files from upstream

build/
 v8s.json # generated runtime registry
 v8s-blocklist.json # generated trust-and-safety policy
 ...static assets...

Defaults

defaults/ is the product baseline. The public v8s.link instance uses these files to show a working shortener with the search-style home page, expand page, localized status pages, default icons, the protected stats shell, and sample links.

Runtime registry

Mon, 01 Jan 0001 00:00:00 +0000

The Worker does not read v8s-links.txt on every request. The build creates a private runtime registry at build/v8s.json and publishes it as an internal asset. Direct public requests for v8s.json, redirect-targets.json, and blocklist assets return 404.

The registry is intentionally simple: one generated JSON file, schema version 2.2, validated before deploy, consumed by one Worker.

Build inputs

The registry is generated from:

defaults/v8s-links.txt, then custom/v8s-links.txt
defaults/v8s-schedules.json, then custom/v8s-schedules.json
defaults/v8s-blocklist.json, generated blocklist data, and custom/v8s-blocklist.json
static page assets from defaults/public/ overlaid by custom/public/

Use custom/ for every instance-owned change. That keeps future updates simple: upstream can refresh defaults/ and scripts/ while the instance keeps its own links, policy, branding, legal pages, and generated secrets.

Runtime security approach

Mon, 01 Jan 0001 00:00:00 +0000

The vanityURLs runtime is deliberately simple. It is not a public link-submission service, not a database-backed application, and not a general web framework. It is a Git-built redirect engine: validate the link registry, deploy static assets, read v8s.json, and return one of a small set of outcomes.

Simplicity is part of the security model. The Worker has fewer moving parts than a typical shortener: no public write API, no visitor accounts, no cookies, no client-side analytics, no database query layer, and no origin server behind Cloudflare.

Scheduled links

Mon, 01 Jan 0001 00:00:00 +0000

Scheduled links let a stable slug point somewhere different during configured time windows. Keep the normal link in v8s-links.txt, then add rules in v8s-schedules.json.

Schedules currently apply to exact links. Splat links stay path-driven.

For common schedule changes, use the Node CLI instead of hand-editing JSON:

./scripts/lnk schedule add hangout https://zoom.us/j/work --label work --days mon,tue,wed,thu,fri --from 09:00 --to 17:00 --timezone America/Toronto --default https://discord.gg/personal
./scripts/lnk schedule list hangout

The CLI writes custom/v8s-schedules.json by default. Set V8S_SCHEDULES_FILE or pass --file to use another path.

Security Statement

Mon, 01 Jan 0001 00:00:00 +0000

Last reviewed: April 2026

This statement applies to vanityURLs.link. It does not apply to self-hosted instances of vanityURLs, which are the sole responsibility of their operators.

vanityURLs.link is a static documentation website for the open-source project. vanityURLs does NOT do

Server-side analytics

Mon, 01 Jan 0001 00:00:00 +0000

vanityURLs records analytics from the Worker, not from browser JavaScript. Redirects can be measured even when the visitor never loads an HTML page, and the public pages do not need client-side tracking scripts.

Analytics is non-blocking. The Worker sends events with ctx.waitUntil(), so redirect latency is not tied to Umami, Fathom, or another provider being available.

Providers

Set one or more providers with ANALYTICS_PROVIDER:

[vars]
ANALYTICS_PROVIDER = "umami"
UMAMI_ENDPOINT = "https://cloud.umami.is/api/send"
UMAMI_WEBSITE_ID = "<umami website id>"
UMAMI_GEO_IP_MODE = "truncated"

[vars]
ANALYTICS_PROVIDER = "fathom"
FATHOM_SITE_ID = "<fathom site id>"
FATHOM_ENDPOINT = "https://cdn.usefathom.com/"

During a migration, send to both:

Terms of Service

Mon, 01 Jan 0001 00:00:00 +0000

Last reviewed: April 2026

1. The Website

https://www.vanityURLs.link is a documentation website provided to support the vanityURLs open-source project. It is offered for informational purposes only and may be modified or discontinued at any time without notice.

Trust Center

Mon, 01 Jan 0001 00:00:00 +0000

Upgrading an instance

Mon, 01 Jan 0001 00:00:00 +0000

Installing a vanityURLs instance is easy. Updating one safely is the part that needs a repeatable workflow, because the instance owner should keep links, branding, policy, and Cloudflare configuration while receiving new defaults, scripts, fixes, and security hardening.

The rule is simple:

instance-owned files live in custom/
Cloudflare deployment settings live in wrangler.toml
generated output is disposable
upstream product files live in defaults/ and scripts/

Upgrade command

Run from a clean worktree:

Validation and CI

Mon, 01 Jan 0001 00:00:00 +0000

Run validation before every deploy. v8s is designed so link mistakes, unsafe targets, stale generated assets, and Worker regressions fail before Cloudflare receives a new version.

Local commands

Use the combined check for normal work:

npm run check

It builds the runtime, runs lint checks, and executes the Worker tests. For targeted work, use:

npm run lint
npm test
npm run build
npm run smoke:analytics

Run npm run clean before release or before comparing generated output. It removes build cruft so the repo only shows intentional source changes.

Fully branded short URLs via continuous integration on vanityURLs

Redirects as Code: Managing Short Links the GitOps Way

Why vanityURLs? The case for owning your short links

Say Goodbye to Third-Party URL Shorteners: Introducing VanityURLs

The Problem with Relying on Third-Party Services

Accessibility Statement

Conformance status

Admin dashboard

What it shows

Protection

bhdicaire.com

Blocklist policy

CLI

Requirements

Cloudflare Workers

Cloudflare navigation map

Contribution Guide

Ways to contribute

Pull request guidelines

Questions?

Custom overrides

Build order

Recommended custom files

Default links

Namespaced examples

felx.cc

Impressum

License

Link format

Exact links

Migration guide

What changed

Convert legacy .lnk files

Privacy

Quickstart

What you need

Release checklist

Repository

Worker and assets

Cloudflare domain configuration

Reporting a Vulnerability

Repository layout

Defaults

Runtime registry

Build inputs

Runtime security approach

Scheduled links

Security Statement

Server-side analytics

Providers

Terms of Service

1. The Website

Trust Center

Upgrading an instance

Upgrade command

Validation and CI

Local commands