Documentation on vanityURLs

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.

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.

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.

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:

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:

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.

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:

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.

Documentation on vanityURLs

Admin dashboard

What it shows

Protection

Blocklist policy

CLI

Requirements

Cloudflare Workers

Cloudflare navigation map

Custom overrides

Build order

Recommended custom files

Link format

Exact links

Migration guide

What changed

Convert legacy .lnk files

Quickstart

What you need

Release checklist

Repository

Worker and assets

Cloudflare domain configuration

Repository layout

Defaults

Runtime registry

Build inputs

Runtime security approach

Scheduled links

Server-side analytics

Providers

Upgrading an instance

Upgrade command

Validation and CI

Local commands