Quickstart

Start your terminal

Open a terminal and move to the directory where you keep source code. For example:

cd ~/code

Use whatever local structure already works for you. The important part is that the vanityURLs instance lives in a directory you can find again.

Confirm GitHub authentication

Make sure your GitHub account is configured for either SSH or HTTPS before you push your own repository.

Create a new public or private GitHub repository for your redirector before the final push step. Do not initialize it with a README, license, or .gitignore; the local instance will provide the initial content.

Clone the vanityURLs code

You can use any directory name instead of v8s-link. Choose a name that will still make sense if you later align it with your GitHub repository and Worker name.

git clone https://github.com/vanityURLs/code.git v8s-link
cd v8s-link

Detach the clone from the upstream project

Run the detach helper before creating your own Git history. It removes upstream project metadata that is useful for vanityURLs development but not for your personal instance:

npm run detach

Confirm required tools are available on the workstation

which npm node git jq

If any command is missing, install it before continuing. jq is only required when you install the Local helper later in this Quickstart.

Install dependencies

npm install

Configure your instance

Run the installer:

npm run setup

For phase 1, focus on these installer answers.

Some defaults are derived from your previous answers so the installer does not ask for the same idea twice. Setup also skips related questions when you disable a section, such as analytics or full legal pages.

Setup writes links.random_slug_length as 3 when the value is missing. Edit custom/v8s-site-config.json later if you want a different default.

Install local helpers

npm run local-install

This installs the optional workstation shortcuts. Use Local helper for the read-only v8s shortcut, and LNK when you are ready to manage links and schedules from the terminal.

If you previously installed the workstation helper for another instance, your shell may already export V8S_REPO. The source command ./scripts/lnk now prefers the repository it is running from, but older clones can still be affected by a stale environment value. If ./scripts/lnk list shows links from another instance, run:

unset V8S_REPO
./scripts/lnk list

Create your first commit

git init
git add .
git commit -m "first commit"
git branch -M main

Push to your GitHub repository

Use the repository URL from the GitHub repository you created for your instance:

git remote add origin git@github.com:vanityURLs/v8s.link.git
git push -u origin main

or

git remote add origin https://github.com/vanityURLs/v8s.link.git
git push -u origin main

Connect the repository to Workers & Pages

In Cloudflare, open Build > Compute > Workers & Pages from the account main menu, then:

1. Create an application with the Worker name from wrangler.toml, such as v8s-link. The Cloudflare console does not rename Workers after creation, so see Wrangler Without Shooting Yourself in the Foot for why this name should match your local directory and GitHub repository
2. Continue with GitHub
3. Select your redirector repository
4. Confirm Cloudflare is using the project name written by setup in wrangler.toml
5. Leave the Build and Deploy fields as-is so wrangler.toml remains authoritative
6. Deselect builds for non-production branches unless you want every branch to deploy

Configure Access control

Open Access control in another tab and complete the activities there. Make sure that you have copied the Application Audience (AUD) Tag to your password manager.

Configure network protection

Traffic blocked by Cloudflare does not reach your vanityURLs instance, which reduces headaches and Worker noise. You may be surprised by the volume of unsolicited events. Review blocked requests in Cloudflare Security Events, not inside Workers, because those requests stop before the Worker runs.

Open Network protection in another tab and complete the activities there. Return here when those settings are in place.

Optional: test locally

Before validating the instance, you can run the Worker locally with npm run dev. Wrangler starts a local development server so you can check the homepage, generated pages, and basic redirects before Cloudflare deploys from GitHub.

Validate and push

npm run check
git status --short

If validation changed generated files or you still have local setup changes to publish:

git add .
git commit -m "chore: finish initial instance setup"
git push

If this is not your first push and git status --short is empty, there is nothing new to commit. Cloudflare should deploy from GitHub after the next push that changes the repository.

Test the deployment

Open the home page, /lookup/, /404.html, /expired.html, /disabled.html, and /maintenance.html.

If custom/v8s-links.txt does not exist, setup creates it from defaults/v8s-links.txt, then adapts the starter home, contact, and docs links for your short domain and owner label.

Test at least one initial custom link, such as https://<short-domain>/docs, and confirm that it redirects to the long link shown in the table. Test https://<short-domain>/contact when you want to see the starter schedule override that default during the configured 9-to-5 window.

Then test /en/_stats/, one other localized stats path such as /fr/_stats/, and /_tests from a signed-out or private browser profile. You should see Cloudflare Access before the protected dashboard or test page. The legacy /_stats path redirects to /en/_stats/.