Nuxt 2 → Nuxt 3 Migration Playbook for SaaS

Migrating a SaaS product from Nuxt 2 legacy to Nuxt 3 is not optional anymore-it's survival.
This guide is for SaaS teams, CTOs, and senior FE devs who need a clear plan, not theory.

Business Impact

• Risk: Nuxt 2 is effectively end-of-life. Security updates are gone. Every week you delay is compounding tech debt.
• Opportunity: Nuxt 3 gives serverless-ready Nitro, native TypeScript, better DX, and Core Web Vitals uplift.
• Costs vs Value: Expect 4-8 weeks migration for a mid-size SaaS (~50 routes). Payoff: lower infra costs, faster builds, +10-15% Lighthouse performance.

Technical Breakdown

Key differences:

• Config: nuxt.config.js → nuxt.config.ts with defineNuxtConfig.
• State: Vuex → Pinia.
• Server: serverMiddleware → Nitro server/api/*.
• Build: Webpack → Vite.
• Routing: File-based stays, but middleware/plugin APIs changed.
• SEO: Native support for route rules + payload extraction.

Example: Config Rewrite

      
lang:ts filename:nuxt.config.ts
export default defineNuxtConfig({
modules: '@nuxt/content', '@pinia/nuxt',
typescript: { strict: true },
routeRules: {
'/dashboard/': { ssr: true },
'/blog/': { prerender: true }
},
nitro: { preset: 'vercel' }
})

    

Example: API Endpoint Migration

      
lang:ts filename:server/api/user.get.ts
import { z } from 'zod'
const querySchema = z.object({ id: z.string().uuid() })
export default defineEventHandler(async (event) => {
const { id } = await getValidatedQuery(event, querySchema.parse)
return { user: await getUserById(id) }
})
async function getValidatedQuery(event, validator) {
return validator(getQuery(event))
}

    

Migration Checklist

Pitfalls to Avoid

Phased Playbook

1. Audit (Week 1)
   • List routes, plugins, middleware.
   • Estimate effort for Vuex→Pinia, middleware rewrites.
2. Parallel Branch (Week 2)
   • Keep Nuxt 2 branch alive. Start Nuxt 3 branch.
   • Migrate config + basic layout.
3. Core Features (Weeks 3-4)
   • Move state, critical APIs, auth.
   • Run e2e + API tests.
4. SEO + Perf (Week 5)
   • Add routeRules, ISR/prerender.
   • Benchmark CWV.
5. Cutover (Week 6)
   • Staged rollout. Monitor error rates.
   • Kill Nuxt 2 branch when stable.

SEO & Performance Notes

• Core Web Vitals: Nuxt 3 reduces CLS and LCP by default with Vite and payload extraction.
• SSR/ISR: Use routeRules for hybrid SSR + prerender.
• Caching: Edge caching via Nitro presets (Vercel, Cloudflare).
• Routes: Ensure canonical URLs and trailing slash rules match legacy.

Example: Route Rules for SEO

      
lang:ts filename:nuxt.config.ts
export default defineNuxtConfig({
routeRules: {
'/': { ssr: true, static: true },
'/pricing': { isr: 300 },
'/blog/**': { prerender: true, sitemap: true },
}
})

    

Conclusion

Migrating from Nuxt 2 legacy to Nuxt 3 is an audit + rebuild, not a patch.
Done right, you get faster builds, modern SSR, and SEO uplift.
Delay it, and you’re sitting on a liability.