كيفية الترقية إلى الإصدار 12

لترقية إلى الإصدار 12، قم بتنفيذ الأمر التالي:

npm i next@12 react@17 react-dom@17 eslint-config-next@12

yarn add next@12 react@17 react-dom@17 eslint-config-next@12

pnpm up next@12 react@17 react-dom@17 eslint-config-next@12

bun add next@12 react@17 react-dom@17 eslint-config-next@12

معلومة مفيدة: إذا كنت تستخدم TypeScript، تأكد من ترقية @types/react و @types/react-dom إلى الإصدارات المقابلة لها.

الترقية إلى الإصدار 12.2

البرمجيات الوسيطة (Middleware) - إذا كنت تستخدم البرمجيات الوسيطة قبل الإصدار 12.2، يرجى الاطلاع على دليل الترقية لمزيد من المعلومات.

الترقية إلى الإصدار 12.0

الحد الأدنى لإصدار Node.js - تم رفع الحد الأدنى لإصدار Node.js من 12.0.0 إلى 12.22.0 وهو أول إصدار من Node.js يدعم وحدات ES الأصلية.

الحد الأدنى لإصدار React - الحد الأدنى المطلوب لإصدار React هو 17.0.2. للترقية يمكنك تنفيذ الأمر التالي في الطرفية:

npm install react@latest react-dom@latest

yarn add react@latest react-dom@latest

pnpm update react@latest react-dom@latest

bun add react@latest react-dom@latest

استبدال Babel بـ SWC

يستخدم Next.js الآن المترجم المعتمد على Rust SWC لترجمة JavaScript/TypeScript. هذا المترجم الجديد أسرع بمقدار 17 مرة من Babel عند ترجمة الملفات الفردية وأسرع بمقدار 5 مرات في التحديث السريع (Fast Refresh).

يوفر Next.js توافقًا كاملاً مع الإصدارات السابقة للتطبيقات التي تحتوي على تكوين Babel مخصص. جميع التحويلات التي يتعامل معها Next.js افتراضيًا مثل styled-jsx وإزالة الأكواد غير المستخدمة (tree-shaking) لـ getStaticProps / getStaticPaths / getServerSideProps تم نقلها إلى Rust.

عندما يحتوي التطبيق على تكوين Babel مخصص، سيتوقف Next.js تلقائيًا عن استخدام SWC لترجمة JavaScript/TypeScript وسيعود إلى استخدام Babel بنفس الطريقة التي كانت مستخدمة في Next.js 11.

سيتم نقل العديد من عمليات التكامل مع المكتبات الخارجية التي تتطلب حاليًا تحويلات Babel مخصصة إلى تحويلات SWC المعتمدة على Rust في المستقبل القريب. وتشمل هذه على سبيل المثال لا الحصر:

• Styled Components
• Emotion
• Relay

من أجل تحديد أولويات التحويلات التي ستساعدك في اعتماد SWC، يرجى مشاركة ملف .babelrc الخاص بك في موضوع الملاحظات هذا.

استبدال Terser بـ SWC للتصغير

يمكنك اختيار استبدال Terser بـ SWC لتصغير JavaScript بسرعة تصل إلى 7 أضعاف باستخدام علامة في next.config.js:

module.exports = {
  swcMinify: true,
}

يعد تصغير الأكواد باستخدام SWC علامة اختيارية لضمان إمكانية اختبارها ضد المزيد من تطبيقات Next.js الواقعية قبل أن تصبح الافتراضية في Next.js 12.1. إذا كان لديك ملاحظات حول التصغير، يرجى مشاركتها في موضوع الملاحظات هذا.

تحسينات في تحليل CSS لـ styled-jsx

إلى جانب المترجم المعتمد على Rust، قمنا بتنفيذ محلل CSS جديد يعتمد على المحلل المستخدم في تحويل Babel لـ styled-jsx. هذا المحلل الجديد لديه تحسينات في معالجة CSS ويظهر الآن أخطاء عند استخدام CSS غير صالح كان يتسلل سابقًا ويسبب سلوكًا غير متوقع.

بسبب هذا التغيير، سيؤدي CSS غير الصالح إلى ظهور خطأ أثناء التطوير وعند تنفيذ next build. هذا التغيير يؤثر فقط على استخدام styled-jsx.

تغيير عنصر التغليف لـ next/image

يقدم next/image الآن عنصر <img> داخل <span> بدلاً من <div>.

إذا كان تطبيقك يحتوي على CSS يستهدف span مثل .container span، فإن الترقية إلى Next.js 12 قد تتطابق بشكل غير صحيح مع عنصر التغليف داخل مكون <Image>. يمكنك تجنب ذلك عن طريق تقييد المحدد إلى فئة معينة مثل .container span.item وتحديث المكون ذي الصلة بهذه الفئة، مثل <span className="item" />.

إذا كان تطبيقك يحتوي على CSS يستهدف علامة <div> لـ next/image، مثل .container div، فقد لا يتطابق بعد الآن. يمكنك تحديث المحدد إلى .container span، أو يفضل إضافة <div className="wrapper"> جديد يغلف مكون <Image> واستهدافه بدلاً من ذلك مثل .container .wrapper.

لم يتغير دعم className وسيظل يمرر إلى عنصر <img> الأساسي.

راجع الوثائق لمزيد من المعلومات.

اتصال HMR يستخدم الآن WebSocket

سابقًا، استخدم Next.js اتصال أحداث مرسلة من الخادم (server-sent events) لاستقبال أحداث HMR. يستخدم Next.js 12 الآن اتصال WebSocket.

في بعض الحالات عند توجيه الطلبات إلى خادم تطوير Next.js، ستحتاج إلى التأكد من معالجة طلب الترقية بشكل صحيح. على سبيل المثال، في nginx ستحتاج إلى إضافة التكوين التالي:

location /_next/webpack-hmr {
    proxy_pass http://localhost:3000/_next/webpack-hmr;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

إذا كنت تستخدم Apache (2.x)، يمكنك إضافة التكوين التالي لتمكين WebSocket للخادم. راجع المنفذ واسم المضيف وأسماء الخوادم.

<VirtualHost *:443>
 # ServerName yourwebsite.local
 ServerName "${WEBSITE_SERVER_NAME}"
 ProxyPass / http://localhost:3000/
 ProxyPassReverse / http://localhost:3000/
 # Next.js 12 يستخدم websocket
 <Location /_next/webpack-hmr>
    RewriteEngine On
    RewriteCond %{QUERY_STRING} transport=websocket [NC]
    RewriteCond %{HTTP:Upgrade} websocket [NC]
    RewriteCond %{HTTP:Connection} upgrade [NC]
    RewriteRule /(.*) ws://localhost:3000/_next/webpack-hmr/$1 [P,L]
    ProxyPass ws://localhost:3000/_next/webpack-hmr retry=0 timeout=30
    ProxyPassReverse ws://localhost:3000/_next/webpack-hmr
 </Location>
</VirtualHost>

بالنسبة للخوادم المخصصة مثل express، قد تحتاج إلى استخدام app.all لضمان تمرير الطلب بشكل صحيح، على سبيل المثال:

app.all('/_next/webpack-hmr', (req, res) => {
  nextjsRequestHandler(req, res)
})

تم إزالة دعم Webpack 4

إذا كنت تستخدم بالفعل webpack 5 يمكنك تخطي هذا القسم.

اعتمد Next.js webpack 5 كافتراضي للترجمة في Next.js 11. كما تم الإبلاغ في وثائق ترقية webpack 5 فإن Next.js 12 يزيل دعم webpack 4.

إذا كان تطبيقك لا يزال يستخدم webpack 4 باستخدام علامة الإلغاء، فسترى الآن خطأ يشير إلى وثائق ترقية webpack 5.

خيار target أصبح قديمًا

إذا لم يكن لديك target في next.config.js يمكنك تخطي هذا القسم.

أصبح خيار target قديمًا لصالح الدعم المدمج لتتبع التبعيات المطلوبة لتشغيل صفحة.

أثناء next build، سيتتبع Next.js تلقائيًا كل صفحة وتبعياتها لتحديد جميع الملفات المطلوبة لنشر نسخة إنتاجية من تطبيقك.

إذا كنت تستخدم حاليًا خيار target مضبوطًا على serverless، يرجى قراءة الوثائق حول كيفية الاستفادة من الإخراج الجديد.