Next.js/compiler

يسمح مُصرِّف Next.js الذي كتب بلغة Rust باستخدام SWC بتحويل وتصغير شيفرة JavaScript لتصبح مناسبة لمرحلة الإنتاج. وبالتالي حل مكان Babel بالنسبة للملفات المستقلة و Terser لتصغير الحزم الناتجة.

إن التصريف باستخدام مصرّف Next.js أسرع بحوالي 17 مرة من استخدام Babel، وهو المصرِّف الافتراضي ابتداءً من النسخة 12. لكن إن كنت تستخدم إعدادات مهيئة مسبقًا لمحلل Babel أو كنت تستخدم ميزات غير مدعومة، سيتجاوز تطبيقك مصرّف Next.js ذاك ويستخدم Babel.

سجل التغييرات

النسخة	التغييرات
v13.1.0	دعم إدراج الوحدات بصورة مجزأة Modularize Imports أصبح مستقرًا.
v13.0.0	تفعيل مُصغِّر SWC افتراضيًا.
v12.3.0	مُصغِّر SWC أصبح مستقرًا.
v12.2.0	إضافة دعم تجريبي لإضافات SWC.
v12.1.0	دعم المكوّنات المنسَّقة ومكتبة Jest وإزالة خاصيات React ودعم المبدلات الديناميكية القديمة وإزالة تعليمات السجل Console ودعم الخاصية jsxImportSource.
v12.0.0	ظهور مصرِّف Next.js للمرة الأولى.

لماذا استخدم SWC؟

SWC هي منصة مبنية على لغة رست Rust مُعدّة لأدوات التطوير من الجيل الجديد، وبالإمكان استخدامها للتصريف وتصغير الشيفرة وتجميعها وغيرها الكثير، وقد صممت لكي تكون قابلة للتوسعة. فهي أداة يمكن استخدامها لتنفيذ تحويلات على الشيفرة (سواء مدمجة أو مخصصة)، ويجري تنفيذ هذه التحويلات ضمن بيئات عالية المستوى مثل Next.js.

لقد اخترنا بناء التطبيقات باستخدام SWC لأسباب عدة منها:

• قابلية التوسع: يمكن استخدام SWC كصندوق Crate داخل Next.js دون الحاجة إلى اشتقاق fork المكتبة أو الإلتفاف حول تقييدات التصميم.
• الأداء: أمكننا تحقيق معدل تحديث سريع أعلى بثلاث مرات ومعدل بناء أعلى بخمس مرات في Next.js عندما تحوّلنا لاستخدام SWC مع وجود مساحات أوسع للتحسينات التي لا تزال قيد التطوير.
• دعم WebAssembly: إن دعم لغة رست Rust لتجميعة WASM أمر حيوي لدعم مختلف منصات العمل، وبالتالي تطوير تطبيقات Next.js في كل مكان.
• مجتمع المطورين: إن مجتمع لغة رست Rust ومناخ التعامل ضمنه رائع وينمو باستمرار.

الميزات المدعومة في مصرِّف Next.js

إليك بعض الميزات التي يدعمها مُصرِّف Next.js

المكوِّنات المُنسّقة Styled Components

يجري العمل حاليًا على ربط babel-plugin-styled-components مع مصرّف Next.js ويمكنك تجريب ذلك. حدّث أولًا نسخة Next.js إلى النسخة الأخيرة بتنفيذ الأمر npm install next@latest ثم حدّث ملف التهيئة next.config.js:

module.exports = {
  compiler: {
    // see https://styled-components.com/docs/tooling#babel-plugin for more info on the options.
    styledComponents: boolean | {
      // مُفعل في بيئة التطوير ومعطل في بيئة الإنتاج لتقليل حجم الملف
      // ضبط الخيار هنا سيُعدل سلوك كل البيئات ويعطل السلوك الافتراضي
      displayName?: boolean,
      // مُفعل افتراضيًا
      ssr?: boolean,
      // مُفعل افتراضيًا
      fileName?: boolean,
      // فارغ افتراضيًا
      topLevelImportPaths?: string[],
      // ["index"] القيمة الافتراضية هي
      meaninglessFileNames?: string[],
      // مُفعل افتراضيًا
      cssProp?: boolean,
      // فارغ افتراضيًا
      namespace?: string,
      // غير مدعوم بعد
      minify?: boolean,
      // غير مدعوم بعد
      transpileTemplateLiterals?: boolean,
      // غير مدعوم بعد
      pure?: boolean,
    },
  },
}

لم يضاف تنفيذ ودعم إلى التحويلات minify و transpileTemplateLiterals و pure ويمكنك تتبع نسبة الإنجاز هنا، إذ ssr و displayName هما التحويلان الرئيسيان المطلوبان لاستخدام المكوّنات المُنسّقة styled-components في Next.js.

مكتبة الاختبارت Jest

لا تدعم Jest التحويلات السابقة التي يؤمنها Babel فقط، لكنها تُبسِّط أيضًا تهيئة Jest مع Next.js بما في ذلك:

• التقليد التلقائي أو المحاكاة لملفات css. و module.css. (بما في ذلك تنسيقات scss.) ولعملية إدراج الصور.
• ضبط التحويلات transform تلقائيًا باستخدام SWC.
• تحميل ملفات env. (وشبيهاتها) ضمن الملف process.env.
• تجاهل node_modules خلال عملية تحليل وإنجاز الاختبارات والتحويل.
• تجاهل next. خلال عملية تحليل وإنجاز الاختبارات.
• تحميل الملف next.config.js لتفعيل رايات تحويلات SWC التجريبية.

حدّث أولًا نسخة Next.js إلى النسخة الأخيرة بتنفيذ الأمر npm install next@latest ثم حدّث ملف التهيئة next.config.js:

// jest.config.js
const nextJest = require('next/jest')
// next.config.js  تحديد مسار التطبيق والذي سيمكِّن من تحميل الملف 
// .env وملفات 
const createJestConfig = nextJest({ dir: './' })

// jest أية تهيئة إضافية تريد تمريرها إلى 
const customJestConfig = {
  setupFilesAfterEnv: ['<rootDir>/jest.setup.js'],
}

//على تحميل next/jest بهذا الشكل للتأكد من قدرة createJestConfig ثصدَّر 
//الغير متزامنة Next.js إعدادات 
module.exports = createJestConfig(customJestConfig)

دعم مكتبة Relay

لدعم Relay نفِّذ التالي:

// next.config.js
module.exports = {
  compiler: {
    relay: {
      // relay.config.js ينبغي أن يطابق
      src: './',
      artifactDirectory: './__generated__',
      language: 'typescript',
    },
  },
}

ملاحظة: تُعد جميع ملفات JavaScript الموجودة في المجلد pages بمثابة وجهات routes. ولكي تستخدم relay-compiler ستضطر إلى تضبط إعدادات artifactDirectory خارج المجلد pages وإلا سيوّلد المُصرِّف relay-compiler ملفات إلى جوار الملف المصدري في المجلد __generated__ وسيُعدُّ هذا الملف وجهة، مما يعطل نسخ الإنتاج في تطبيقك.

إزالة خاصيات React

يسمح بإزالة خاصيات JSX لأغراض الاختبار غالبًا، وبشكل مشابه للخاصية babel-plugin-react-remove-properties.

لإزالة الخاصيات التي تتطابق مع التعبير النمطي ‎^data-test:

// next.config.js
module.exports = {
  compiler: {
    reactRemoveProperties: true,
  },
}

لإزالة خاصية محددة:

// next.config.js
module.exports = {
  compiler: {
    //لذا تختلف صياغة التعبير عن Rust يعالج التعبير النمطي من قبل 
    //JavaScript تعبير 
    reactRemoveProperties: { properties: ['^data-custom$'] },
  },
}

إزالة استدعاءات Console

يتيح لك هذا التحويل إزالة كل الاستدعاءات *.console من شيفرة التطبيق (وليس من node_modules)، وبشكل مشابه للخاصية babel-plugin-transform-remove-console.

تُزال كل الاستدعاءات *.console كالتالي:

// next.config.js
module.exports = {
  compiler: {
    removeConsole: true,
  },
}

لإزالة كل الاستدعاءات *.console ما عدا console.error:

// next.config.js
module.exports = {
  compiler: {
    removeConsole: {
      exclude: ['error'],
    },
  },
}

دعم المزخرفات القديمة Legacy Decorators

تكتشف Next.js تلقائيًا الراية experimentalDecorators في ملفات التهيئة jsconfig.json أو tsconfig.json. إذ تُستخدم المزخرفات القديمة Legacy decorators مع النسخ الأقدم من مكتبات مثلmobx، وتُدعم هذه الراية لأغراض التوافق فقط مع التطبيقات الموجودة، ولا ننصح باستخدامها في التطبيقات الجديدة.

حدّث أولًا نسخة Next.js إلى النسخة الأخيرة بتنفيذ الأمر npm install next@latest ثم حدّث ملف التهيئة next.config.js أو الملف jsconfig.json:

{
  "compilerOptions": {
    "experimentalDecorators": true
  }
}

دعم الخاصية importSource

تكتشف Next.js تلقائيًا الخاصية jsxImportSource في الملفين jsconfig.json و tsconfig.json وتطبقها، وتُستخدم هذه الخاصية عادة مع مكتبات مثل "Theme UI".

حدّث أولًا نسخة Next.js إلى النسخة الأخيرة بتنفيذ الأمر npm install next@latest ثم حدّث ملف التهيئة next.config.js أو الملف jsconfig.json:

{
  "compilerOptions": {
    "jsxImportSource": 'preact'
  }
}

دعم المكتبة Emotion

يجري العمل حاليًا على ربط emotion/babel-plugin@ مع مصرّف Next.js. لتجريب ذلك، حدّث أولًا نسخة Next.js إلى النسخة الأخيرة بتنفيذ الأمر npm install next@latest ثم حدّث ملف التهيئة next.config.js:

// next.config.js

module.exports = {
  compiler: {
    emotion: boolean | {
      // مفعلة افتراضيًا، وتُعطّل في نسخ الإنتاج
     
      sourceMap?: boolean,
      // 'dev-only' :القيمة الافتراضية هي 
      autoLabel?: 'never' | 'dev-only' | 'always',
      // '[local]':القيمة الافتراضية هي 
      // `[local]` و `[filename]` و `[dirname]`:القيمة المسموحة هي 
      // على إحدى القيمتين autoLabel يعمل هذا الخيار عندما يُضبط
      // 'dev-only' أو 'always'.
      // تتيح لك تحديد تنسيق العنوان الناتج
      // يٌعرّف التنسيق من خلال سلسلة نصية توضع فيها الأجزاء المتغيرة
      //[] بين قوسين مربعين 
      // "my-classname--[local]" مثال على ذلك  
      //ويُستبدل باسم المتغير [local] المتغير هو 
      labelFormat?: string,
      // القيمة الافتراضية غير مُعرفة
      // يسمح لك هذا الخيار بإخبار المُصرف ما هي الإدراجات التي يجب أن ينظر فيها
      // Emotion ليُحدد ما هي التحويلات، فإذا كنت تعيد تصدير تصديرات
      // فلا يزال بوسعك الاستفادة من التحويلات
      importMap?: {
        [packageName: string]: {
          [exportName: string]: {
            canonicalImport?: [string, string],
            styledBaseImport?: [string, string],
          }
        }
      },
    },
  },
}

التصغير Minification

بإمكانك الاستفادة من مصرِّف Next.js في تصغير الشيفرة minification الذي أصبح افتراضيًا مع النسخة 13، وهذا أسرع بسبع مرات من استخدام Terser، وإن كنت لا تزال بحاجة إلى استعمال Terser لأي سبب كان، فيمكنك تغيير الضبط كالتالي:

// next.config.js

module.exports = {
  swcMinify: true,
}

دعم إدراج الوحدات البرمجية بصورة مجزأة

تمامًا كما في babel-plugin-transform-imports.

يُحوَّل نمط الإدراج التالي:

import { Row, Grid as MyGrid } from 'react-bootstrap'
import { merge } from 'lodash'

إلى النمط الافتراضي للإدراج:

import Row from 'react-bootstrap/lib/Row'
import MyGrid from 'react-bootstrap/lib/Grid'
import merge from 'lodash/merge'

تُضبط إعدادات التحويل السابق كالتالي:

// next.config.js
module.exports = {
  modularizeImports: {
    'react-bootstrap': {
      transform: 'react-bootstrap/lib/{{member}}',
    },
    lodash: {
      transform: 'lodash/{{member}}',
    },
  },
}

تحويلات متقدمة

• استخدام التعابير النطية regular expressions: يماثل babel-plugin-transform-imports لكن التحويل يقولب باستخدام handlebars، وستكون التعابير النمطية وفق صياغة Rust.

تجعل الإعدادات التالية:

// next.config.js
module.exports = {
  modularizeImports: {
    'my-library/?(((\\w*)?/?)*)': {
      transform: 'my-library/{{ matches.[1] }}/{{member}}',
    },
  },
}

الشيفرة:

import { MyModule } from 'my-library'
import { App } from 'my-library/components'
import { Header, Footer } from 'my-library/components/App'

على الشكل:

import MyModule from 'my-library/MyModule'
import App from 'my-library/components/App'
import Header from 'my-library/components/App/Header'
import Footer from 'my-library/components/App/Footer'

• القولبة باستخدام Handlebars: يستخدم هذا التحويل صياغة handlebars لقولبة مسار المكتبة أو الوحدة التي نريد إدراجها في الحقل transform. يمكنك استخدام الدوال المساعدة والمتغيرات التالية:

1. matches: يمتلك النوع []string، ويضم كل المجموعات التي تتطابق مع التعبير النمطي. يعيد matches.[0] التطابق كاملًا.
2. member: من النوع []string، ويمثل اسم العضو المُدرج.
3. lowerCase و upperCase و camelCase: وهي دوال مساعدة لتحويل النص إلى حروف كبيرة أو صغيرة أو طريقة سنام الجمل.

الميزات التجريبية لمصرِّف Next.js

خيارات تنقيح عمل المُصغِّر

ما زال عمل المُصغِّر minifier في طور التجريب والاختبار، لذا وفرنا الخيارات التالية لأغراض التنقيح والبحث عن المشاكل، ولن تكون الخيارات متاحة متى ما استقر عمل المُصغِّر.

// next.config.js

module.exports = {
  experimental: {
    swcMinifyDebugOptions: {
      compress: {
        defaults: true,
        side_effects: false,
      },
    },
  },
}

ارجع إلى توثيق SWC لمزيد من التفاصيل.

تتبع أداء SWC

يمكنك توليد تعقبات التحويل الداخلية التي يجريها SWC بشكل مشابه لصيغة أحداث التعقب في متصفح كروميوم chromium.

// next.config.js

module.exports = {
  experimental: {
    swcTraceProfiling: true,
  },
}

بمجرد تفعيلها، سيولد SWC تعقيبات باسم swc-trace-profile-${timestamp}.json داخل المجلد /next.، ويمكنك استعمال أي عارض تعقبات trace viewer مناسب لتحميلها وعرضها مثل: chrome://tracing أو https://ui.perfetto.dev أو https://www.speedscope.app.

إضافات SWC

يمكنك ضبط تحويلات SWC لاستخدام دعم إضافات SWC التجريبي المكتوب باستخدام WebAssembly وذلك لتخصيص سلوك تحويل ما.

// next.config.js

module.exports = {
  experimental: {
    swcPlugins: [
      [
        'plugin',
        {
          ...pluginOptions,
        },
      ],
    ],
  },
}

تقبل swcPlugins مصفوفة من الصفوف لكل إضافة مع ضبطها، إذ يحوي كل صف مسار الإضافة وكائن لحواية ضبطها، وبالنسبة للمسار، يمكن أن يكون اسم وحدة npm أو مسار مطلق إلى ملف wasm..

ميزات غير مدعومة في مصرِّف Next.js

عندما يحتوي تطبيقك على الملف babelrc.، ستتراجع Next.js تلقائيًا لاستخدام Babel في تحويل الملفات المستقلة. يضمن ذلك التوافقية الرجعية مع التطبيقات الموجودة التي تستخدم إضافات Babel مخصصة.

المصادر

• الصفحة Compiler من توثيق Next.js الرسمي.