Skip to content
vanityURLs
EN FR

Quickstart

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.

First deployment

Clone the repository

Create a repository from the vanityURLs template, then clone it locally.

git clone git@github.com:YOUR-ORG/YOUR-SHORT-DOMAIN.git
cd YOUR-SHORT-DOMAIN
npm install

Keep local changes in custom/

Do not edit defaults/ for your own branding or link list unless you are changing the upstream product defaults. Instance-owned files belong in custom/.

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

Create custom/v8s-links.txt with pipe-delimited rows, or use the CLI:

./scripts/lnk https://github.com/YOUR-ORG github --title GitHub --description "Organization profile" --tags source --owner team
./scripts/lnk https://docs.example.com docs --title Docs --description "Main documentation" --tags docs --owner team

The file format is:

# slug|target|state|title|description|tags|owner|expires_at|notes
github|https://github.com/YOUR-ORG|permanent|GitHub|Organization profile|source|team||
docs|https://docs.example.com|permanent|Docs|Main documentation|docs|team||

Missing schemes are normalized to https://. Use permanent for stable 301 redirects and ephemeral for temporary 302 redirects.

Build and validate

npm run check

The check command builds the Worker source, copies static assets, merges defaults and custom files, generates build/v8s.json, validates the registry, and checks policy files.

Optional terminal helper

The repository includes a Zsh helper at scripts/v8s.zsh for opening redirect targets from your terminal. Source it from your shell profile:

source /path/to/YOUR-SHORT-DOMAIN/scripts/v8s.zsh

The helper reads ~/.v8s.json, which npm run build creates from the generated registry. Override the path if you keep the registry somewhere else:

export V8S_REGISTRY=/path/to/v8s.json

Useful commands:

v8s --list          # list active slugs
v8s docs            # open the target for docs
v8s --print docs    # print the target without opening it
v8s --path          # show the registry path

v8s.zsh does not open arbitrary terminal input. It only opens http:// and https:// targets that already exist as permanent or ephemeral links in the generated registry.

Deploy with Cloudflare Workers

Review wrangler.toml, set the Worker name, then deploy:

npx wrangler deploy

Connect your custom domain to the Worker route in Cloudflare. Every future push to GitHub can trigger the same build and deploy through your CI or Cloudflare integration.

Verify

Open your home page, a known short link, /expand/, /404.html, /expired.html, /disabled.html, and /maintenance.html. If you configured protected views, open /_stats in a private browser and confirm Cloudflare Access appears before the dashboard.

Edit this page Last modified: