Vercel Docs Teardown: Two Good Decisions, One Ongoing Mess

The verdict first: Vercel's docs are above average on information architecture and search, and below average on versioning. The site works well if you arrive knowing what you need. It works badly if you're a developer trying to figure out whether a tutorial you found on Stack Overflow is still correct for Next.js 15.

I've been in vercel.com/docs and nextjs.org/docs roughly once a week for three years. This post is a teardown of what's actually working there in April 2026, and where the cracks are visible. For the prior teardown in this series, see Stripe API docs.

The framework-vs-platform split is the best decision on the site

Vercel owns two doc sites. nextjs.org/docs is the framework reference. vercel.com/docs is the hosting platform reference. Most companies in their position would have merged these into one. Vercel didn't, and that's the single strongest structural choice on the whole property.

Why it works: the two audiences are different. A developer reading about App Router layouts doesn't need to know about Vercel's WAF rules, and a platform engineer configuring build environments doesn't need to know about React Server Components. Merging them would force every page to disambiguate, and the nav would bloat to cover both audiences at once.

The split also lets each site have its own opinionated sidebar. nextjs.org/docs reads like a book, organized around concepts (Routing, Data Fetching, Rendering, Caching). vercel.com/docs reads like a product manual, organized around features (Functions, Edge Middleware, Observability, Domains). Those are the right organizations for each, and neither would survive a merger.

The seam where the split gets awkward: deployment docs. If you're trying to figure out how environment variables get from .env.local into a production Function, you'll bounce between both sites, because the Next.js docs describe the API for reading envs and the Vercel docs describe how they're injected at runtime. The canonical page, vercel.com/docs/projects/environment-variables, is fine, but the cross-linking from nextjs.org/docs is spotty. Worth stealing: the architectural split. Worth avoiding: letting the cross-links rot.

Search is genuinely good, the command palette is better

Hit Cmd+K on either site and the command palette opens. This is the right default for a docs site, and I'll take it as uncontroversial now, but it's worth noting how much better it is than the search bar it replaced. The palette is keyboard-first, it shows results as you type, and it indexes both documentation pages and code examples.

What's under the hood is less obvious. The result list isn't just a keyword match. Search for "cache" and you get pages where caching is the actual subject, not pages that happen to mention the word. That's either a curated synonym map or a good reranker, and it's the difference between a search bar that works and a search bar that feels like an excuse not to build proper navigation.

What the search misses: it's bad at version-qualified queries. Search "middleware pages router" and you get mixed results from App Router and Pages Router docs with no clear signal which is which. If you know you're on the old Pages Router because your app hasn't migrated, you need to eyeball the URL of every result to figure out if it applies. A prefix filter in the palette ("in:pages-router") would fix this in an afternoon. They haven't shipped it.

Worth stealing: the Cmd+K palette is now table stakes. Worth avoiding: trusting a single search index across versioned content without giving users a way to scope it. Docsio's AI agent can wire up a scoped search bar for versioned docs in about a minute, which is less impressive than it sounds and more useful than you'd think. More on this pattern in documentation versioning.

The Next.js 14 to 15 migration docs are where it falls apart

Versioning is the hardest problem in any long-lived doc site, and Vercel is failing at it in a way that's visible to anyone who's tried to upgrade a production Next.js app in the last six months.

The surface problem: nextjs.org/docs shows "latest" by default, which is currently Next.js 15. There's a version switcher, but it only goes back to v13. If your app is on 14.2 and you want to know what changed in a specific API, you often can't tell without reading the migration guide, the v14 archived docs, and the current page, then diffing them by hand.

The deeper problem: App Router vs Pages Router coexistence. Every API page has to explain both, or pick one and hope the other audience gives up. The team mostly picked App Router, which is the right long-term call, but it means Pages Router users land on pages that describe a programming model they don't use, with a small "Pages Router" link in the top nav that takes them to a parallel but inconsistently maintained set of pages. The Pages Router equivalents are often 2 to 3 months behind on new features and examples.

I watched a team burn a full day last month trying to figure out whether revalidatePath worked the same way in the Pages Router. It doesn't. The docs technically say so, but the relevant sentence is in a paragraph on a page three clicks away from where they started.

Fix for Vercel: per-page version warnings ("This feature is App Router only. For Pages Router, see X"), and a persistent version pill in the sidebar that follows you across pages. Fix for your docs if you're copying Next.js's approach: don't. Either break the docs cleanly by major version with a forced picker at the top (the way Python 2 vs 3 docs did), or maintain a single version and deprecate aggressively. The worst option is the "mostly one version, with a ghost of another haunting the sidebar" pattern.

The AI features are mostly theater

Both sites have an AI chat. On nextjs.org it's a small "Ask AI" button, on vercel.com it's integrated into the search palette. You type a question, it returns a paragraph with source citations pointing back to docs pages.

The generous read: it's fine. The chat knows about the current version of Next.js, cites real pages, and will not hallucinate API signatures for routes that don't exist (most of the time). The first-pass answer to a specific question like "how do I configure ISR in a server component" is usable.

The critical read: it's not meaningfully better than opening a docs page and reading it. The AI answer compresses the same information you'd find on the canonical page, minus the code examples, minus the nuance about edge cases. For exploratory questions it's sometimes faster. For questions where you're going to copy-paste code into a project, you end up clicking through to the source page anyway. The AI adds a step rather than removing one.

What I'd actually want from a docs AI is different. I'd want it to diff my project's current code against the current docs and tell me what's outdated. "You're using getServerSideProps. Here's what the App Router equivalent looks like for your code." That would be load-bearing. A chat bar that summarizes pages I could read in the time it takes to type the question is not.

Worth stealing: none of this, yet. Worth watching: the feature is clearly going to get better, and the teams that figure out how to make AI docs actually interactive (rather than chat-shaped) will have an edge. See ai knowledge base for a broader take on where this is heading.

The interactive code examples are the hidden win

Most Next.js doc pages include live, editable code examples. You can fork them directly into the Vercel template gallery or CodeSandbox with a single click. This is underrated. It turns docs from a reading exercise into a running exercise, and the barrier to trying something drops to roughly zero.

The Learn site (nextjs.org/learn) takes this further. It's a full tutorial with embedded code editors and a real project that builds up over chapters. This is closer to how humans actually learn a framework (by building something) than the reference-style docs can ever get. Stripe has something similar with its Terminal tutorial, but Vercel's Learn site is genuinely best-in-class for a framework the scale of Next.js.

Worth stealing: the principle that a tutorial should run in the browser, not require a git clone. If your docs tool can generate runnable examples, use it. If it can't, at least link to a StackBlitz or CodeSandbox template from every tutorial page. Docsio does this by default for API references. For broader patterns see api documentation examples.

Worth avoiding: mistaking interactive examples for a replacement for clear prose. The Learn site works because the prose is sharp and the code follows it. Strip the prose and you have a codesandbox with no context.

What to steal and what to avoid

Steal: the framework-vs-platform split if you have two distinct products, the Cmd+K command palette with keyword-plus-synonym search, the runnable code examples from every tutorial page, the decision to organize sidebars around the domain (concepts for Next.js, features for Vercel) rather than around navigation convenience.

Avoid: shipping an AI chat before it can do something a keyword search can't, letting versioned content bleed across versions without clear per-page signals, maintaining two parallel framework versions where one is systematically 2 months behind.

The verdict I started with still holds. Vercel's docs are above average because of two structural decisions (the split, the palette) and one ongoing investment (the Learn site). They're below average because of versioning, which is the problem every docs site has and most sites solve by shipping less. Next.js is too popular to ship less. That's a problem Vercel has to solve with better tooling, not fewer pages.

If you're picking a documentation platform for your own product, the lesson here isn't that you should copy nextjs.org/docs. It's that every one of the good decisions on that site came from treating docs as a product with its own roadmap, and every one of the weak points is where that roadmap got outpaced by the framework it documents. The teams winning at docs in 2026 are the ones whose docs roadmap runs ahead of their product roadmap, not behind it.