React Docs Push Next.js. But I Built My App With Vite Anyway.

Mar 13, 2026

I opened the React documentation, clicked “Start a New React Project,” and saw Next.js listed as “recommended.”

So I used Next.js for my internal admin dashboard.

Three weeks later, I was debugging cache invalidation issues for a page that only authenticated users would ever see. Nobody would ever Google “admin dashboard settings panel.” SEO was completely irrelevant.

But the docs said Next.js was recommended. So I built with Next.js.

The Documentation Funnel

Here’s what the React documentation presents:

react.dev → "Start a New React Project"

Options presented:
├── Next.js (recommended) ← Front and center
├── Remix
├── Gatsby
├── Expo (for native)
└── "Other options" ← Buried at the bottom

New developers follow the path of least resistance. The docs say “recommended,” so they use Next.js. For everything.

A Reddit post captured this perfectly:

“The official React docs still funnel everyone straight into Next.js, and almost every greenfield job posting demands it.”

The original poster wasn’t exaggerating. I’ve seen the same pattern:

What I saw online          What job market wanted
-----------------          ----------------------
"Use Vite + TanStack"  vs   "Next.js required"
"SPAs are fine"        vs   "SSR experience"
"Keep it simple"       vs   "App Router knowledge"

The disconnect between community advice and market pressure is jarring.

React’s documentation explains their reasoning:

Next.js supports all React features (especially Server Components)
It’s production-ready with sensible defaults
Active maintenance and ecosystem support

These are valid reasons. But they’re not the whole story.

What the docs don’t mention:

Unstated Factors:
├── Vercel employs React core team members
├── React Server Components need a framework
├── Business partnerships influence positioning
└── Ecosystem momentum benefits Vercel

This isn’t a conspiracy. It’s business.

Vercel has invested heavily in React. They built Next.js, hired React contributors, and created features that require a framework. The recommendation makes sense from an ecosystem perspective.

But individual projects have different needs than the React ecosystem as a whole.

When I Questioned the Recommendation

I started a new project recently. Here’s my thought process:

My Requirements:
- Internal tool for team
- All users authenticated
- CRUD operations
- No public content
- No SEO needed

Next.js Features I'd Use:
- Routing: Yes
- SSR: No
- Server Components: No
- Image Optimization: Maybe
- API Routes: No (separate backend)

Features I'd Fight:
- Client/server component boundaries
- Cache invalidation
- Deployment complexity
- Build-time data fetching

The math didn’t work. I’d add complexity for features I wouldn’t use.

So I tried something different.

What Happened When I Used Vite

# What the docs showed me
npx create-next-app@latest my-dashboard

# What I actually needed
npm create vite@latest my-dashboard -- --template react-ts

The Vite setup gave me:

Vite SPA Stack:
├── React (with TypeScript)
├── TanStack Query (data fetching)
├── React Router (routing)
└── Simple deployment (static CDN)

What I didn't get:
├── SSR complexity
├── Cache invalidation headaches
├── Client/server component confusion
└── Server infrastructure costs

For data fetching, TanStack Query handled everything:

import { useQuery } from '@tanstack/react-query'

function UsersList() {
  const { data, isLoading } = useQuery({
    queryKey: ['users'],
    queryFn: () => fetch('/api/users').then(r => r.json())
  })

  if (isLoading) return <Spinner />

  return <UserTable users={data} />
}

No server components. No cache invalidation. No “use client” directives. Just React.

A Reddit commenter shared a similar experience:

“Went for React + Vite + RQ, good ol’ React paradigm, worked like a charm. Easier to compose React components compared to Next.js having to extract components because of client vs server.”

The Framework Decision I Use Now

After trying both approaches, I created a simple decision process:

                      START HERE
                          |
              Do you need SEO?
                    /     \
                  YES      NO
                   |        |
           Public content?  |
              /     \       |
            YES     NO      |
             |       |      |
         Next.js   Still    Use Vite SPA
         or Astro  consider  + TanStack
                   Next.js
                    |
            Do you need SSR
            for performance?
               /     \
             YES      NO
              |        |
          Next.js    Vite SPA

Let me break this down with specific examples:

Project Type	SEO Needed?	Recommendation
Public blog	Yes	Next.js or Astro
E-commerce store	Yes	Next.js
Internal dashboard	No	Vite SPA
Admin panel	No	Vite SPA
SaaS app (authenticated)	No	Vite SPA
Marketing site	Yes	Next.js
Documentation site	Yes	Next.js or Astro

Reading Documentation Critically

I learned to approach documentation with questions:

1. Who benefits from this recommendation?

The React docs benefit the React ecosystem. Next.js benefits Vercel. That doesn’t mean the recommendation is wrong, but understanding motivations helps.

2. Are alternatives fairly represented?

When docs bury alternatives under “Other options,” that’s a signal. The alternatives might work better for your use case.

3. Does this match my context?

The docs recommend Next.js because it supports all React features. But do I need all React features? Server Components are useless for an authenticated SPA.

4. What complexity does this add?

Every feature has a cost. SSR adds deployment complexity. Server Components add mental model overhead. Caching adds debugging time.

When Next.js Is the Right Choice

I’m not anti-Next.js. I use it when appropriate.

Use Next.js When:
├── SEO matters (public content)
├── Social sharing needs meta tags
├── Initial page load is critical
├── You need static generation
└── You're building a blog, store, or marketing site

Skip Next.js When:
├── All users are authenticated
├── SEO is irrelevant
├── You want simpler deployment
├── You don't need server features
└── You're building internal tools

The React docs aren’t wrong. They’re optimized for the framework ecosystem, not your specific project.

The Cost of Following Defaults

I’ve seen teams suffer from blindly following documentation defaults:

Symptom 1: Component boundary confusion

// Server Component
async function Dashboard() {
  const data = await fetchData() // Server-side only

  // Can't use useState here
  // Can't use useEffect here
  // Can't pass functions to children

  return <ClientWrapper data={data} />
}

// Client Component
'use client'
function ClientWrapper({ data }) {
  const [filter, setFilter] = useState('')

  // Now I'm managing two paradigms
  // And serializing data between them
}

This is necessary for SSR. But for an SPA? Unnecessary complexity.

Symptom 2: Deployment cost difference

Vite SPA Hosting:
- Vercel Free: $0/month
- Netlify Free: $0/month
- CloudFlare Pages: $0/month

Next.js SSR Hosting:
- Vercel Pro: $20/month minimum
- AWS Lambda: Variable
- Self-hosted: $10-50+/month

The infrastructure cost difference is real.

Symptom 3: Cache invalidation debugging

Next.js caching is powerful. It’s also a common source of bugs. I’ve spent hours debugging why data wasn’t refreshing, only to discover I needed to understand the caching layer.

What Senior Developers Actually Use

From the Reddit discussion and my experience:

Community Recommendation vs Job Market:

What seniors recommend:
├── Vite + React + TanStack Query for SPAs
├── Next.js only when SSR is needed
├── Start simple, add complexity when justified
└── Match stack to requirements

What job postings demand:
├── Next.js required
├── App Router experience
├── SSR knowledge
└── Vercel deployment familiarity

One commenter put it bluntly:

“It’s kinda telling that a lot of the tech-influencers who got people into NextJS have moved on once Vercel stopped paying them…”

I can’t verify that claim. But the sentiment reflects real frustration with ecosystem hype cycles.

My Rule Now

Start with Vite. Add Next.js only when you can articulate the specific feature you need.

This rule has served me well. It forces me to think about requirements before reaching for complexity.

If you can say:
"I need SSR because my pages must be indexed by search engines"
→ Use Next.js

If you can say:
"I need static generation because my content changes infrequently"
→ Use Next.js or Astro

If you can say:
"I need server-side data fetching for performance"
→ Consider Next.js

If you say:
"I should use Next.js because the docs recommend it"
→ Stop. Reconsider. You probably don't need it.

Quick Reference

Requirement                Framework Choice
----------                 ----------------
SEO critical              Next.js, Astro, Remix
Behind authentication      Vite SPA
Public marketing site      Next.js
Internal dashboard         Vite SPA
E-commerce storefront     Next.js
Admin panel               Vite SPA
Blog                      Next.js or Astro
SaaS application          Vite SPA (or split)

A Reddit commenter summarized it well:

“Easy solution is to choose stack based on actual requirements and characteristics instead of hype and marketing.”

Summary

React’s documentation recommends Next.js for ecosystem reasons. That recommendation serves the React framework ecosystem well.

But your project has different needs than the React ecosystem.

The docs aren’t wrong. They’re just not optimized for your specific use case.

Read documentation critically. Match your stack to your requirements. Don’t let ecosystem defaults drive your architecture decisions.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

👨‍💻 Reddit Discussion: Next.js SPA Reality Check
👨‍💻 React Official Documentation
👨‍💻 Vite Documentation
👨‍💻 Next.js Documentation
👨‍💻 TanStack Query

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!