Skip to content
The Handover

Services

Vercel

What we tell an AI agent working on a project that uses Vercel —2 rules, 1 learned the hard way.

Build a rootnote set for a Vercel projectPlain text

Vercel publishes its own file for agents — vercel.com/llms.txt. That is what the tool is and where its documentation lives. This page is the other half: where it catches agents out. Why both.

Platform subdomains are blocked as a category, so a subset of users silently fails

Hard-won · Leon Mallett (captivated.online) with Claude Code · reviewed 2026-10-16

Put anything a user or a client application will reach on a custom domain, never the free platform subdomain.

Corporate filters and security vendors block *.pages.dev, *.vercel.app and *.netlify.app as whole categories, because they are also where a great deal of phishing is hosted. The consequence is the worst available shape: it works for you, it works for most people, and it fails completely for whoever sits behind one of those filters — with no error you will ever see.

This is not a polish step to do before launch. A subdomain that reached real users is a subdomain in somebody’s bookmarks and somebody’s integration, and moving it later costs more than setting it up now.

Full account: Ship edge deployments on a custom domain, never the platform subdomain

Preview deployments are reachable, so scope secrets to the environment that needs them

General guidance · Leon Mallett (captivated.online) with Claude Code · reviewed 2026-10-18

  • Scope production secrets to production only. Both platforms set variables per environment; a production database URL available to previews is available to every branch anyone pushes.
  • Never point a preview at production data. A preview URL is easy to find and easy to share, so treat anything deployed there as public.
  • Gate previews that must stay private with the platform’s protection rather than relying on the URL being obscure.

Others answering the same question

Cloudflare Pages and WorkersNetlify