Next.js 16 में अपग्रेड करना: माइग्रेशन नोट्स और समस्याएँ

तीन हफ्ते पहले मैं Seahawk ऑफिस में गुरुवार दोपहर बैठा था, बिल्कुल आश्वस्त कि Next.js 15 से 16 में अपने एक पर्सनल पोर्टफोलियो साइट पर अपग्रेड करने में चालीस मिनट से ज्यादा नहीं लगेंगे। पूरा दिन लग गया। और ईमानदारी से कहूँ? चेंजलॉग उन हिस्सों के लिए आपको तैयार नहीं करता जो वास्तव में टूटते हैं।

इस बिंदु तक मैंने 12,000 से ज्यादा साइट्स बनाई और शिप की हैं। मैं यह फ्लेक्स करने के लिए नहीं कह रहा, मैं इसलिए कह रहा हूँ क्योंकि मैंने इतने माइग्रेशन किए हैं कि जब ऑफिशियल अपग्रेड गाइड कुछ चीजों को छिपा रही हो तो मुझे पता चल जाता है। Next.js 16 कुछ चीजों को छिपाता है। तो यहाँ हैं मेरे असल नोट्स, उसी तरह लिखे गए हैं जिस तरह मैं चाहता था कि किसी ने मेरे लिए उन्हें लिखे होते।

---

मैंने अपग्रेड करने की परवाह क्यों की

Turbopack। यही छोटा जवाब है।

लंबा जवाब यह है कि मेरी दो साइट्स Next.js 14 पर थीं, एक पहले से ही 15 पर था, और मैं लगभग अठारह महीनों से Turbopack की कहानी को विकसित होते देख रहा था। वर्जन 16 पहला रिलीज है जहाँ Turbopack next dev के लिए डिफ़ॉल्ट रूप से चालू है। यह नगण्य विवरण नहीं है। एक मध्यम आकार की ई-कॉमर्स बिल्ड पर जो मैंने पिछले साल एक फैशन क्लाइंट के लिए किया था, डेवलपमेंट में कोल्ड स्टार्ट टाइम भयानक थे, पहले लोड पर 12 से 18 सेकंड की बात कर रहे हैं। अगर Turbopack सच में इसे कम करता है, तो माइग्रेशन की परेशानी सार्थक है।

स्पॉयलर: यह इसे कम करता है। एक ही तरह की प्रोजेक्ट पर, मैं 3 से 4 सेकंड का कोल्ड स्टार्ट देख रहा हूँ। यह असल है।

लेकिन वहाँ पहुँचने का रास्ता कुछ तीक्ष्ण किनारे रखता है।

---

असल अपग्रेड कमांड (और पहले क्या चलाना है)

किसी भी चीज़ को छुए बिना पहले अपनी मौजूदा कॉन्फ़िगरेशन का पूरा ऑडिट चलाएँ। मैं अब npx @next/codemod@latest को धार्मिकता से चलाता हूँ। यह सब कुछ नहीं पकड़ेगा लेकिन स्पष्ट नाम बदलाव और यथा API कॉल को पकड़ता है। इसे चलाएँ, आउटपुट को कमिट करें, फिर अपने package.json को बंप करें।

अपग्रेड खुद:

अपने package.json में next, react, और react-dom को उनके टार्गेट वर्जन में अपडेट करें
npm install चलाएँ (या pnpm install अगर आप समझदारी रखते हैं, मैं दो साल से pnpm पर हूँ)
कोडमॉड चलाएँ: npx @next/codemod@latest upgrade
next dev बूट करें और एक भी कंपोनेंट को छुए बिना हर चेतावनी पढ़ें
कंपोनेंट समस्याओं को ठीक करने से पहले कॉन्फ़िगरेशन समस्याओं को ठीक करें, यहाँ क्रम मायने रखता है

कोडमॉड स्टेप वह जगह है जहाँ मैंने लोगों को गिरते हुए देखा है। वे इसे छोड़ते हैं, तीन अलग त्रुटियों में पड़ते हैं, और एक घंटा ऐसी चीजों को खोजने में बिताते हैं जो ऑटो-फिक्स हो गई होतीं। इसे छोड़ें मत।

---

next.config.js बदलाव जो आपको काट सकते हैं

यह मेरे लिए पहली असल आश्चर्य थी। कॉन्फ़िगरेशन API मेरी उम्मीद से ज्यादा बदला।

`experimental` ब्लॉक अब पतला है

कई फ्लैग जो पिछले एक या दो साल के लिए experimental में रहे थे, या तो स्थिर में प्रोन्नत किए गए हैं (और शीर्ष स्तर पर स्थानांतरित किए गए हैं) या पूरी तरह हटा दिए गए हैं। दो जो मैं व्यक्तिगत रूप से पार आया:

experimental.appDir, अब नहीं है। App Router अब डिफ़ॉल्ट है। अगर यह आपके कॉन्फ़िग में है, तो यह एक चेतावनी फेंकेगा (और कुछ सेटअप में, एक सीधी त्रुटि)।
experimental.serverComponentsExternalPackages को आपके कॉन्फ़िग के शीर्ष स्तर पर serverExternalPackages में बढ़ावा दिया गया।

वह दूसरा सर्वर सर्वर के लिए चुप विफल रहा था और मैं शायद चालीस मिनट तक गलत फ़ाइल को देख रहा था इससे पहले कि मुझे यह दिख गया। अपने next.config.js को ऊपर से नीचे तक जांचें इससे पहले कि आप मान लें कि एक घटक गलत है।

Turbopack कॉन्फ़िग एक नई जगह पर रहता है।

अगर आपके पास कोई कस्टम Webpack कॉन्फ़िग था और आप Turbopack पर स्विच कर रहे हैं (जो आप करेंगे, क्योंकि यह अब डेव के लिए डिफ़ॉल्ट है), तो आपको पता होना चाहिए कि आपका webpack() फ़ंक्शन next.config.js में Turbopack चलने पर लागू नहीं होता। यह केवल next build के दौरान लागू होता है, जो अभी भी Webpack का उपयोग करता है।

यह मायने रखता है अगर आपके पास कस्टम SVG हैंडलिंग थी (मैं अधिकांश प्रोजेक्ट पर SVGR का उपयोग करता हूँ), कस्टम मॉड्यूल उपनाम, या कोई लोडर कॉन्फ़िग। आपको इन्हें नए turbopack कॉन्फ़िग ब्लॉक में दोहराना होगा। Next.js Turbopack कॉन्फ़िगरेशन डॉक्स इस पर वास्तव में ठीक हैं, इससे पहले एक पढ़ने के लायक हैं कि आप मान लें कि कुछ टूट गया है।

---

React 19 संगतता: शांत बारूदी सुरंग

Next.js 16 React 19 के साथ अपनी peer dependency के रूप में आता है। अगर आप Next.js 14 से अपग्रेड कर रहे हैं (15 को छोड़ते हुए), तो आप एक बार में दो React मुख्य संस्करण कूद रहे हैं। यह वह जगह है जहाँ चीजें तीव्र हो जाती हैं।

सबसे बड़ी समस्या जो मुझे आई वह पुरानी तृतीय-पक्ष घटक लाइब्रेरी के साथ थी। मेरे पास एक क्लाइंट साइट था जो एक टेबल लाइब्रेरी का उपयोग कर रहा था जो आंतरिक रूप से ReactDOM.render() का उपयोग करता था। React 19 ने वह API पूरी तरह से हटा दिया, यह React 18 में deprecated था लेकिन यह अभी भी काम कर रहा था। 19 में, यह फेंक देता है। कठोरता से।

मैंने इस पर एक मंगलवार की सुबह बिताई। त्रुटि संदेश तुरंत आपको लाइब्रेरी की ओर इंगित नहीं करता; यह सिर्फ आपको बताता है कि ReactDOM.render अब समर्थित नहीं है। npm ls react चलाएँ यह देखने के लिए कि आपके पेड़ में कौन से पैकेज को React peer dependency घोषणाओं के साथ विरोध है। वह कमान अकेली मुझे शायद दो घंटे की अनुमान से बचा सकी।

React 19 के लिए विशेष रूप से कुछ पैटर्न जानने के लायक हैं:

forwardRef अब refs पास करने के लिए आवश्यक नहीं है; refs अब एक नियमित prop हैं। forwardRef का उपयोग करने वाले पुराने घटक अभी भी काम करते हैं, लेकिन आप deprecation चेतावनी देखेंगे।
use() अब स्थिर है और client घटकों में async डेटा के लिए वास्तव में उपयोगी है। मैंने इसे straightforward fetches के लिए useEffect + state पर पसंद में उपयोग करना शुरू किया है।
Server Actions के पास अधिक कठोर type आवश्यकताएँ हैं। अगर आपके पास अपने action signatures में कुछ भी ढीला typed था, तो TypeScript अब इसे खोज लेगा।

---

App Router: Caching Behaviour में क्या बदला

यह एक सूक्ष्म है और यह आपको production में पकड़ेगा अगर आप ध्यान नहीं दे रहे हैं।

Next.js 14 में, Server Components के अंदर fetch() को डिफ़ॉल्ट रूप से आक्रामकतापूर्वक कैश किया गया था। आपको { cache: 'no-store' } के साथ opt out करना था। Next.js 15 में उन्होंने इसे उलट दिया (fetch डिफ़ॉल्ट रूप से uncached है), और Next.js 16 उस दिशा को कुछ और स्पष्ट नियंत्रण के साथ जारी रखता है।

अगर आप 14 से 16 तक एक कूद में माइग्रेट किया (जैसे मैंने अपनी एक साइट के साथ किया), तो आपके पृष्ठ जो पुराने डिफ़ॉल्ट caching behaviour पर निर्भर थे, हर request पर live fetches करना शुरू करेंगे। कुछ पृष्ठों के लिए, वह ठीक है। दूसरों के लिए, यह आपके API को हथौड़ा मारेगा और आपके response times को टैंक करेगा।

The fix is explicit: use export const revalidate = 3600 (or whatever interval makes sense) at the route segment level, or pass { next: { revalidate: 3600 } } directly in your fetch call. The Next.js caching documentation has a solid breakdown of what caches what and when.

मैंने fetch( के लिए एक quick grep का उपयोग करके प्रभावित साइट पर हर data-fetching route को audit किया और स्पष्ट caching declarations जोड़े। कुछ दो घंटे का समय लगा लेकिन यह लायक था, response times ~800ms average से ~120ms तक गिर गए।

---

Turbopack व्यवहार में: अच्छा और कष्टप्रद

मैं आपको सीधा बताता हूँ: Turbopack प्रभावशाली है। Cold start times नाटकीय रूप से बेहतर हैं। Hot module replacement अधिकांश परिवर्तनों पर लगभग तुरंत महसूस होता है। दिन-प्रतिदिन विकास के लिए यह एक अर्थपूर्ण quality-of-life upgrade है।

लेकिन rough edges हैं।

अभी तक क्या काम नहीं करता

जिस समय मैंने ये migrations किए, कुछ चीजें अभी भी dev के लिए Turbopack के तहत पूरी तरह से समर्थित नहीं थीं:

कुछ Webpack-विशिष्ट लोडर्स के पास अभी तक Turbopack का समकक्ष नहीं है। SVGR को कॉन्फ़िग परिवर्तन की आवश्यकता थी (Turbopack का rules सिंटैक्स Webpack के module.rules से अलग है)।
कस्टम Babel transforms। Turbopack केवल SWC का उपयोग करता है। यदि आपके प्रोजेक्ट में कस्टम प्लग-इन्स के साथ .babelrc या babel.config.js है, तो वे चलाए नहीं जाएंगे। यह एक ज्ञात सीमा है और Vercel टीम अपने Turbopack docs में इसके बारे में स्पष्ट है।
कुछ PostCSS प्लग-इन संयोजन dev में अप्रत्याशित रूप से काम करते हैं। मैंने यह Tailwind v4 + कस्टम PostCSS सेटअप पर देखा, समाधान PostCSS प्लग-इन क्रम को स्पष्ट रूप से पिन करना था।

`--turbopack` फ़्लैग अब अनावश्यक है

चूंकि Turbopack संस्करण 16 में next dev के लिए डिफ़ॉल्ट है, आपको अब --turbopack फ़्लैग की आवश्यकता नहीं है। यदि आपके पास संस्करण 15 में इसके साथ प्रयोग करने के लिए आपके package.json scripts में है, तो यह कुछ नुकसान नहीं करेगा, लेकिन यह अनावश्यक है। अपने scripts को साफ़ करें।

---

TypeScript और ESLint कॉन्फ़िग अपडेट

दो घरेलू काम जो मुझे भ्रमित करते हैं।

Next.js 16 को TypeScript 5.x की आवश्यकता के लिए स्थानांतरित किया गया है। यदि आप अभी भी TypeScript 4.x पर हैं (और कुछ पुराने प्रोजेक्ट हैं), तो आपको इसे अलग से अपग्रेड करने की आवश्यकता है। कुछ भी शुरू करने से पहले npx tsc --version चलाएं।

ESLint कॉन्फ़िग की कहानी भी बदल गई है। Next.js 16 ESLint 9 समर्थन के साथ शिप करता है, और ESLint 9 पुरानी .eslintrc प्रारूप के बजाय flat config प्रारूप (eslint.config.js) का उपयोग करता है। यदि आप अभी भी पुरानी प्रारूप पर हैं, तो Next.js सुंदरता से वापस आएगा, लेकिन आप एक चेतावनी देखेंगे। मैंने अपने दो प्रोजेक्ट्स को flat config में माइग्रेट किया जबकि मैं वहां था। यह ईमानदारी से एक बार प्रारंभिक घर्षण के बाद स्वच्छ है।

---

मेरी माइग्रेशन चेकलिस्ट (क्रम में)

यह वह है जो मैं अपनी टीम के किसी भी व्यक्ति को इस अपग्रेड को करने के लिए देता हूं:

कुछ भी छूने से पहले अपनी वर्तमान कॉन्फ़िग फ़ाइलों और लॉक फ़ाइल का बैकअप लें
अपने Node.js संस्करण की जांच करें, Next.js 16 को Node 18.18 या बाद में आवश्यकता है
वर्तमान संस्करण पर पहले npx @next/codemod@latest upgrade चलाएं
अपने package.json में next, react, react-dom संस्करणों को बंप करें और इंस्टॉल करें
अपने next.config.js में प्रचारित या हटाए गए experimental flags के लिए समीक्षा करें
तीसरे पक्ष की लाइब्रेरी टकराव को देखने के लिए npm ls react चलाएं
अपने कोडबेस को fetch( के लिए grep करें और कैशिंग घोषणाओं का ऑडिट करें
किसी भी .babelrc या Webpack-विशिष्ट लोडर्स की जांच करें जिन्हें Turbopack समकक्ष की आवश्यकता है
Dev को बूट करें, घटकों को छूने से पहले सभी चेतावनियों को पढ़ें
कहीं भी तैनात करने से पहले स्थानीय रूप से एक उत्पादन बिल्ड चलाएं (next build)
एक स्टेजिंग वातावरण में तैनात करें और एक पूर्ण मैनुअल धुएं परीक्षण करें

वह अंतिम चरण स्पष्ट लगता है। लेकिन मैंने लोगों को स्टेजिंग को छोड़ते हुए और "छोटे" अपग्रेड पर सीधे उत्पादन में धकेलते हुए देखा है। एक कैशिंग व्यवहार परिवर्तन जो आपके होमपेज को हर अनुरोध पर एक लाइव API में हिट करता है, एक छोटी बात नहीं है।

---

FAQ

क्या Next.js 16 उत्पादन के लिए स्थिर है?

हां, ज्यादातर use cases के लिए। Turbopack-for-dev बदलाव सबसे बड़ा shift है, और चूंकि production builds अभी भी Webpack इस्तेमाल करते हैं, आपका deployed output उतना affected नहीं है जितना आपका dev experience। Caching behavior के बदलाव production के लिए ज्यादा चिंताजनक हैं, और अगर आप methodical हैं तो उन्हें audit करना सीधा है।

क्या मुझे React को 19 के साथ ही upgrade करना चाहिए?

तकनीकी रूप से Next.js 16 कम से कम React 18 को support करता है, लेकिन नई features (जैसे stable use() hook और ref-as-prop change) के लिए React 19 चाहिए। अगर आप किसी ऐसे project पर हैं जिसमें बहुत सारी third-party dependencies हैं, तो React 19 के लिए एक ही समय में commit करने से पहले compatibility check करना लायक है। React 19 upgrade guide को Next.js migration docs के साथ पढ़ना काफी useful है।

मेरा custom Webpack config Turbopack के तहत चला गया। मैं क्या करूं?

आपका Webpack config अभी भी next build के दौरान चलता है। Dev के लिए, आपको next.config.js में turbopack key का इस्तेमाल करके relevant parts को replicate करना होगा। Syntax अलग है, खासकर file transforms और aliases के लिए। Official Turbopack config reference check करें और अगर आपका Webpack config complex है तो इस पर एक या दो घंटे खर्च होने की उम्मीद रखें।

Turbopack असल में कितना तेज है?

जिन projects पर मैंने test किया है उन पर: cold start 12-18 seconds से गिरकर 3-4 seconds हो गया। Component changes पर HMR 1-3 seconds से गिरकर ज्यादातर cases में 200ms से कम हो गया। ये rough numbers हैं और project size के साथ बदलेंगी, लेकिन toy project से ज्यादा कुछ भी होने पर फर्क noticeable है।

---

Upgrade करना लायक है। Turbopack का dev speed ही आपके बड़े Next.js codebase में काम करने की feeling बदल देता है। बस caching changes और third-party library compatibility checks के बारे में आंखें खुली रखें, ये दोनों ही चीजें वह हैं जहां actual समय लगता है।

इसे एक बार में एक site पर करें। मैंने किया।