Everything I Wish I Knew Before Migrating My First Vite Project to Next.js

The Great Migration: Moving Beyond the SPA

If you have been building in the React ecosystem recently, you've likely started with Vite. It’s fast, the Developer Experience (DX) is unparalleled, and it just works. However, as projects scale, the requirements often evolve. You suddenly need better SEO, faster First Contentful Paint (FCP), or sophisticated server-side logic without managing a separate backend.

This is usually when the conversation turns to Next.js. While the migration seems straightforward on paper—it's all just React, right?—the reality involves a fundamental shift in how you think about routing, data fetching, and the browser lifecycle.

Here is everything I wish I knew before I made the jump from Vite to Next.js.

1. Routing: From Configuration to Convention

In a Vite project, you probably used react-router-dom. You defined a <Routes> component, listed your paths, and mapped them to components. It was explicit and centralized.

Next.js (specifically the App Router) uses file-system routing. Every folder in your app directory represents a route segment.

The Shift in Thinking

• 
  Vite: You decide where files live; the router links them.


• 
  Next.js: The folder structure is the URL structure.

You will spend your first few hours moving About.tsx to about/page.tsx. It feels tedious at first, but it eliminates a massive category of "broken link" bugs and makes code-splitting automatic.

2. The "use client" Directive

This is perhaps the biggest stumbling block for Vite developers. In Vite, every component is a client component—it runs in the browser. In Next.js, components are Server Components by default.

If you try to use useState, useEffect, or browser APIs like window or localStorage in a default Next.js component, your build will crash. You must add the 'use client' directive at the top of the file.

Pro-Tip: Don't just add 'use client' to everything. The goal is to keep as much logic as possible on the server to reduce the JavaScript bundle sent to the client. Push your stateful logic as far down the component tree as possible.

3. Data Fetching and useEffect Fatigue

In my Vite projects, data fetching looked like this:

const [data, setData] = useState(null);

useEffect(() => {

  fetch('/api/data').then(res => res.json()).then(setData);

}, []);

This often leads to "loading spinners everywhere." In Next.js, you can fetch data directly inside an async Server Component:

export default async function Page() {

  const res = await fetch('https://api.example.com/data');

  const data = await res.json();



  return <main>{data.title}</main>;

}

This is objectively cleaner, but it requires un-learning the habit of wrapping every API call in a useEffect hook.

4. Handling Global State (Redux, Context, Zustand)

In Vite, you likely wrapped your entire <App /> in a Provider. In Next.js, because the root layout is a Server Component, you can't put a Context Provider there directly if it uses hooks.

You'll need to create a separate Client Component for your providers:

'use client';

export function Providers({ children }) {

  return <ThemeProvider>{children}</ThemeProvider>;

}

Then, wrap your children in layout.tsx with this new component. It’s a small architectural hurdle that catches many off-guard.

5. The Path of Least Resistance

Manually refactoring architectural patterns, moving files, and swapping out react-router for the Next.js Link component can take days or weeks depending on the project size. If you want to skip the manual labor of restructuring your directories and converting client hooks, you can use