DEV Community

cynthia
cynthia

Posted on

The is-a.dev + Vercel Field Guide: Every Pitfall, Mapped

#webdev #vercel #dns #git

Free .is-a.dev subdomains are genuinely one of the better things the dev community has built. Clean URL, no cost, no registrar drama. The whole process is submitting a JSON file via GitHub Pull Request.

Here's the part nobody front-loads: the repo runs automated CI tests on every PR before a human even looks at it. Fail those, and you're already closed before a reviewer blinks. Pass those, and then a real human volunteer visits your site and reviews your files.

Two gates. Different failure modes. This guide covers both.

Step 0: Check Availability Before Anything Else

👉 https://is-a.dev

Search your name. Takes 10 seconds. Do it before you get attached.

What You Need

  • GitHub account
  • A project live, deployed, and has actual content on Vercel — not a placeholder page
  • Vercel dashboard open at your project → Settings → Domains
  • A screenshot of your live site (the PR template requires this)

Step 1: Fork, Clone, Branch 

git clone https://github.com/your-github-username/register.git
cd register
git checkout -b add-yourname-domain
Enter fullscreen mode Exit fullscreen mode

Fresh branch every time. Don't work on main.

Step 2: Your Domain File

Create domains/yourname.json:

{
  "owner": {
    "username": "your-github-username",
    "email": "your-email@example.com"
  },
  "records": {
    "CNAME": "cname.vercel-dns.com"
  }
}
Enter fullscreen mode Exit fullscreen mode

What the CI tests will catch here

record vs records — The CI schema validation flags record (singular) immediately. Your PR won't survive automated checks. It's records, plural, always.

Invalid JSON — A missing comma or unclosed brace and the CI fails. Validate at jsonlint.com before you push.

File in the wrong place — Must be inside domains/. Not the root, not a subfolder.

A records must be arrays — If you use an A record instead of CNAME, it has to be: "A": ["76.76.21.21"] — array syntax, even with one value.

CNAME + A in the same file — They conflict. CI will catch it. Pick one; for Vercel, CNAME is the right call since their IPs can change.

Self-referencing — A CNAME that points back to yourname.is-a.dev will also get caught.

Use CNAME over A record for Vercel. cname.vercel-dns.com is stable long-term.

Step 3: The Vercel Verification Pitfall ðŸšĻ

This is what gets people past CI but stopped by the human reviewer.

First — get your TXT token from Vercel

Your project needs to already be live and deployed. Then:

  1. Vercel project → Settings → Domains → Add Domain
  2. Enter yourname.is-a.dev
  3. Vercel asks if you want to redirect to www.yourname.is-a.dev — do not enable this (more on why in a second)
  4. Select the root domain only → click "Continue manually"
  5. Copy the TXT string Vercel shows you: 
vc-domain-verify=yourname.is-a.dev,sometoken123abc
Enter fullscreen mode Exit fullscreen mode

Vercel shows "Invalid Configuration" immediately. That's expected — your PR isn't merged yet. Leave it.

Where NOT to put the TXT record

The obvious move: add the TXT record into yourname.json next to the CNAME. Tidy, logical, wrong.

is-a.dev requires verification records in their own dedicated file. For Vercel, that file is _vercel.yourname.json:

{
  "owner": {
    "username": "your-github-username",
    "email": "your-email@example.com"
  },
  "records": {
    "TXT": "vc-domain-verify=yourname.is-a.dev,your-token-from-vercel"
  }
}
Enter fullscreen mode Exit fullscreen mode

You end up with two files:

File Does what
yourname.json Routes traffic to Vercel via CNAME
_vercel.yourname.json Proves ownership to Vercel via TXT

One routes. One verifies. That's the unlock.

Step 3b: The WWW Redirect Trap ðŸŠĪ

Back in Step 3 when Vercel asks about redirecting to www.yourname.is-a.dev — here's why you skip it:

www.yourname.is-a.dev is a completely separate subdomain. It needs its own JSON file and its own PR in the is-a.dev repo. If you enable the redirect without registering www, Vercel goes looking for a domain it can't find — and your site serves a 404 instead of your portfolio.

Worse: if you then try to remove the redirect and go back to the root domain, Vercel can get stuck demanding a new TXT verification token for the www subdomain before it lets you proceed. It's an annoying loop.

If you accidentally clicked it already:

  1. Vercel → Project Settings → Domains
  2. Find www.yourname.is-a.dev
  3. Delete it 🗑ïļ
  4. Root domain only stays

Propagates in about 60 seconds. Back to normal.

Step 4: Submit the PR 

git add domains/yourname.json domains/_vercel.yourname.json
git commit -m "feat(domain): add yourname.is-a.dev with Vercel CNAME and verification"
git push origin add-yourname-domain
Enter fullscreen mode Exit fullscreen mode

Open a PR against is-a-dev/register. An automated welcome message appears when you do — read it. It tells you exactly what reviewers check. Short version:

  • Fill in the PR template — don't delete it or swap it out
  • Include a screenshot of your live site — not optional, reviewers look for it
  • Mention the domain is already added in Vercel

Reviewers are volunteers. A complete, clean submission is the only reliable fast path.

Full Pitfall Reference

What kills your PR When it's caught Fix
record not records CI — automated Fix the key, validate JSON
Invalid JSON syntax CI — automated Run through jsonlint.com
File outside domains/ CI — automated Move it to the right folder
A record as a string not array CI — automated "A": ["ip"]
CNAME + A in same file CI — automated Pick one
CNAME pointing to itself CI — automated Don't self-reference
TXT token inside main domain file Human reviewer Move to _vercel.yourname.json
Domain added to Vercel but shows 404 Human reviewer Add domain first, let Vercel sit in "pending"
No screenshot in PR description Human reviewer Add one
Site is under construction Human reviewer Finish it, then submit
www redirect enabled without registering www Human reviewer / post-merge Delete www entry in Vercel
PR goes stale after maintainer asks for changes Administrative Respond within a few days
Name already taken by a pending PR Administrative Check open PRs before submitting
Nested subdomain, parent doesn't exist CI or reviewer Register parent domain first

GitHub Pages? Same Pattern 

{
  "owner": {
    "username": "your-github-username"
  },
  "records": {
    "CNAME": "your-github-username.github.io"
  }
}
Enter fullscreen mode Exit fullscreen mode

Verification file: _github-pages-challenge-yourname.json — same structure, different prefix. The _platform.yourname.json naming convention applies across the board.

Pre-Submit Checklist

  • [ ] Name available at is-a.dev
  • [ ] Fresh branch off main
  • [ ] domains/yourname.json — CNAME, records plural, valid JSON
  • [ ] domains/_vercel.yourname.json — TXT token from Vercel
  • [ ] Domain added to Vercel Settings → Domains, root only, no www redirect
  • [ ] Site is live with real content
  • [ ] Screenshot of live site ready for PR description
  • [ ] PR template filled out, not replaced

After the Merge

Usually live within minutes. Still seeing the is-a.dev homepage after 15–20 min? Flush DNS:

# macOS
sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder

# Linux
sudo systemd-resolve --flush-caches

# Windows
ipconfig /flushdns
Enter fullscreen mode Exit fullscreen mode

Then enable Enforce HTTPS in Vercel. You have a clean URL now — secure it.

TL;DR

  1. Check is-a.dev first
  2. records — plural, or CI rejects you immediately
  3. CNAME to cname.vercel-dns.com
  4. Get TXT token: Vercel → project → Settings → Domains → Add Domain → Continue manually
  5. TXT token goes in _vercel.yourname.json — separate file, not the main one
  6. Root domain only in Vercel — skip the www redirect
  7. Screenshot in the PR description

Two gates. Two files. Right keys. That's the whole thing.

Written by a developer who now has a working .is-a.dev domain and a portfolio full of backend projects to show for it — cycy.is-a.dev 🚀

Top comments (0)