FAQ

You need a short domain using Cloudflare DNS, a GitHub account and repository, a Cloudflare account, Git, Node.js 20 or newer, npm, and a text editor. After cloning, the normal path is npm run detach, npm install, npm run setup, npm run local-install, and npm run check.

vanityURLs compiles link and policy source files into static runtime JSON that the Cloudflare Worker reads from the Static Assets binding. There is no account database or mutable click store in the default runtime; Git is the system of record.

No. vanityURLs is open-source software for running your own branded short-link instance on your Cloudflare account and domain. The public docs site is not a shared link-shortening service.

build/v8s.json is the generated runtime link registry consumed by the Worker. Humans edit the source link registry in custom/v8s-links.txt; the build validates that source and compiles it into this runtime JSON. Treat build/v8s.json as generated output, not hand-edited source.

Node.js is used for local tooling: setup prompts, builds, validation, tests, and helper commands. The deployed redirector runs on the Cloudflare Workers serverless platform, which executes JavaScript at the edge. The same language family lets the project share validation and build conventions across Linux, macOS, Windows, and Cloudflare Workers without shipping a native server process.

They are executable scripts, not compiled CPU-specific binaries. The shebang asks the operating system to launch node, then Node runs the text file. You do not need separate Apple Silicon, Intel, Linux, or Windows builds; you need a compatible Node.js runtime and the script file copied with executable permissions on Unix-like systems.

.mjs marks a JavaScript file as an ES module. ES modules use import and export syntax and match the module style used by modern Node.js tooling and Cloudflare Workers. In vanityURLs, .mjs files are still JavaScript; the extension mainly makes the module format explicit.

Public redirect and page requests use GET or HEAD; OPTIONS receives a quiet 204. Other methods return 405 Method not allowed, with POST /lookup/resolve reserved for lookup resolution and POST /_analytics/lookup reserved for the lookup-page beacon. Sandboxed custom HTML can call those two public lookup endpoints with Origin: null; protected endpoints remain locked down.

The build generates build/ and src/, then Cloudflare deploys src/worker.mjs with a Static Assets binding for build/. You can deploy manually with npx wrangler deploy --config wrangler.toml or let Cloudflare Workers & Pages run the build and deploy from Git.

For a normal production instance, run npm run update. It refreshes product-owned files from the latest stable vanityURLs release tag. Use npm run update -- --ref main only when you intentionally want unreleased code, usually on a test instance or while validating a fix with maintainers. If you upgrade from main, commit that choice clearly and switch back to the normal command after the next release is published. See Upgrading an instance for the full workflow.

The current runtime is a Cloudflare Worker using Static Assets, not a Cloudflare Pages _redirects site. Some Cloudflare dashboards still mention Workers & Pages, but the deployed application is the Worker configured in wrangler.toml.

Treat build/ and generated src/ as build output. Edit source files in custom/, product files in defaults/ or scripts/ only when contributing upstream, then rebuild with npm run build or npm run check.

Commit instance source files such as custom/, wrangler.toml, and normal repository metadata. Do not commit regenerated build/, src/, or other transient output unless the project documentation changes to require it.

The upgrade workflow refreshes product-owned files such as defaults/, scripts/, package manifests, and LICENSE. It refuses protected local paths including custom/, wrangler.toml, .dev.vars, and README.md.

Edit custom/v8s-links.txt, preferably through ./scripts/lnk for routine changes. defaults/v8s-links.txt is only the upstream starter fallback used when an instance has not created its own custom link file.

./scripts/lnk manages local source files for links, schedules, random slug defaults, tags, and block policies. Successful write operations are designed to run checks and publish locally, so review its behavior before using it in a repository with custom Git-signing requirements.

Yes. A splat link maps nested paths under a slug into a target containing :splat; exact links win first, then the Worker chooses the longest matching splat prefix.

npm run local-publish is a workstation convenience for validated instance changes: it runs checks, stages configured paths, chooses a commit message, commits, and pushes. Operators with required manual signing prompts should review this workflow before enabling it.

defaults/ is the upstream product baseline; custom/ is the instance-owned overlay. Keeping local changes in custom/ lets npm run upgrade refresh product files without trampling instance links, branding, policies, or legal choices.

Generated legal and trust pages require real operator values for legal identity, short domain, jurisdiction, governing law, contact emails, last updated date, analytics disclosure, and abuse response window. Placeholder values are treated as configuration issues instead of launch-ready content.

Setup supports deferring full privacy, terms, and standalone security pages, but that is a setup convenience rather than legal clearance. Before public launch, operators should complete the generated pages or provide their own reviewed replacements.

The architecture has no built-in click database. Redirect, miss, pageview, and lookup events are sent only when an optional analytics provider is configured for the Worker.

UMAMI_GEO_IP_MODE controls whether the Worker forwards full, truncated, or no visitor IP information to Umami. If Umami is configured and the mode is missing or invalid, the documented default is truncated.

The default architecture does not create visitor accounts or a per-click identity database, so operators can explain that the redirector is not designed to identify visitors. That architectural fact does not remove obligations created by optional analytics, Cloudflare logs, local law, or operator-added tooling.

The documented provider choices are Umami and Fathom, configured through Worker variables and secrets. Both are server-side integrations from the Worker rather than browser JavaScript trackers.

Scheduled links evaluate rules in order using the configured timezone, weekdays, and from/to window. The first active rule wins; if none match, the link uses its normal target.

A schedule rule uses its own timezone when present; otherwise the Worker falls back to UTC. Use an IANA timezone such as America/Toronto to avoid guessing around daylight saving time.

A link can be permanent, ephemeral, expired, disabled, maintenance, or deactivated. The Worker resolves the effective state before redirecting, so state pages or error routes can replace a normal redirect.

When expires_at is a valid date in the past, the Worker treats the link as expired even if the stored state is different. The default expired route serves the expired state page instead of the destination.

The built-in state pages return meaningful status codes: disabled links return 403, expired links return 410, and maintenance links return 503. Deactivated links fall through to the not-found flow.

Build-time policy and runtime sanitation focus on HTTP(S) destinations without embedded credentials, private-network targets, localhost targets, or known risky destination patterns. Operators can replace the source policy in custom/v8s-policies.json.

No. When custom/v8s-policies.json exists, it replaces the selected default policy source for the instance. This makes local policy ownership explicit and prevents removed local decisions from reappearing through an implicit merge. An empty or minimal custom policy is valid; copy defaults/v8s-policies.json into custom/ only when you want the defaults as an editable template.

For localizable HTML assets, the Worker checks Accept-Language against the configured supported languages and serves the first available localized file. If no localized file is available, it falls back to the root asset, which is normally English.

Put instance-owned public assets and page replacements under custom/public/. During build, vanityURLs copies defaults/public/ first and then overlays custom/public/, so custom files win without editing upstream defaults. Product-owned runtime CSS and JavaScript use v8s- filenames and should normally stay in defaults/public/; copying them to custom/public/ creates a local shadow that can go stale after upgrades. Custom HTML receives a sandboxed compatibility profile that still allows same-host custom CSS, JavaScript, inline styles, inline scripts, forms, popups, downloads, and public lookup calls.

The Worker redirects /security.txt to /.well-known/security.txt with a permanent redirect. The generated file depends on {{operator.short_domain}}, {{operator.security_contact}}, and {{operator.last_updated}}.

The Worker treats localized stats paths such as /en/_stats/ and /fr/_stats/, and localized tests paths such as /en/_tests/ and /fr/_tests/, as protected operational paths. Configure the Cloudflare Access application for */_stats, */_stats/*, */_tests, and */_tests/* path patterns. Legacy /_stats redirects to /en/_stats/, and legacy /_tests redirects to /en/_tests/. If CF_ACCESS_TEAM_DOMAIN or CF_ACCESS_AUD is missing, protected paths fail closed with 503 instead of becoming public.

For protected paths, the Worker checks the cf-access-jwt-assertion token against the configured Cloudflare Access team domain and audience. It validates the token algorithm, issuer, audience, time window, and RS256 signature from the Access JWKS.

The Worker keeps application behavior deterministic, while Cloudflare edge controls should reject noisy traffic before it spends Worker CPU or analytics quota. Use both layers: Cloudflare for high-volume network protection, and Worker checks for application-specific redirect safety.

Known scanner paths are matched against the incoming request before short-link lookup. Matching probes receive a plain no-store 404 and should not become normal short-link misses.

Send a report to {{operator.abuse_contact}} and include the short URL, destination if known, why it is harmful, and any supporting evidence. The default instance also publishes /abuse-report.md as a structured template.

The instance operator configured in custom/v8s-site-config.json is responsible for the domain, destinations, legal pages, abuse response, and operational choices for {{operator.short_domain}}. vanityURLs supplies code and defaults; it does not become the operator of each deployed instance.

No. Generated terms state that short links may redirect to third-party websites and that publishing a short link does not endorse the destination or its operator. Abuse reports should target the short link and, when appropriate, the destination host or registrar too.

vanityURLs is a strong fit when you want links as code, Git history, self-operated Cloudflare infrastructure, and no shared hosted-service account surface. Hosted shorteners usually win when you need a managed dashboard, team permissions, built-in billing support, or a public API without running your own deployment.