مترجم Next.js

مترجم Next.js، المكتوب بلغة Rust باستخدام SWC، يسمح لـ Next.js بتحويل وتصغير كود JavaScript الخاص بك للإنتاج. هذا يحل محل Babel للملفات الفردية و Terser لتصغير حزم الإخراج.

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

لماذا SWC؟

SWC هو منصة قابلة للتوسيع مبنية على Rust لأدوات المطورين السريعة من الجيل التالي.

يمكن استخدام SWC للتجميع والتصغير والتعبئة والمزيد - وهو مصمم ليكون قابلًا للتوسيع. إنه شيء يمكنك استدعاؤه لتنفيذ تحويلات الكود (سواء كانت مدمجة أو مخصصة). يتم تنفيذ هذه التحويلات من خلال أدوات عالية المستوى مثل Next.js.

اخترنا البناء على SWC لعدة أسباب:

• القابلية للتوسيع: يمكن استخدام SWC كـ Crate داخل Next.js، دون الحاجة إلى تفرع المكتبة أو حلول بديلة لقيود التصميم.
• الأداء: تمكنا من تحقيق تحديث أسرع بـ ~3 مرات وبناء أسرع بـ ~5 مرات في Next.js عن طريق التحول إلى SWC، مع وجود مجال لمزيد من التحسينات قيد التقدم.
• WebAssembly: دعم Rust لـ WASM ضروري لدعم جميع المنصات الممكنة وجعل تطوير Next.js متاحًا في كل مكان.
• المجتمع: مجتمع Rust والنظام البيئي رائعون ولا يزالان في نمو.

الميزات المدعومة

Styled Components

نعمل على نقل babel-plugin-styled-components إلى مترجم Next.js.

أولاً، قم بالتحديث إلى أحدث إصدار من Next.js: npm install next@latest. ثم، قم بتحديث ملف next.config.js الخاص بك:

module.exports = {
  compiler: {
    styledComponents: true,
  },
}

للحالات المتقدمة، يمكنك تكوين خصائص فردية لتجميع styled-components.

ملاحظة: minify، transpileTemplateLiterals و pure لم يتم تنفيذها بعد. يمكنك متابعة التقدم هنا. تحويلات ssr و displayName هي المتطلبات الرئيسية لاستخدام styled-components في Next.js.

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

Jest

يقوم مترجم Next.js بتحويل اختباراتك وتبسيط تكوين 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. ثم، قم بتحديث ملف jest.config.js الخاص بك:

const nextJest = require('next/jest')

// توفير المسار إلى تطبيق Next.js الخاص بك مما سيمكن تحميل next.config.js وملفات .env
const createJestConfig = nextJest({ dir: './' })

// أي تكوين مخصص تريد تمريره إلى Jest
const customJestConfig = {
  setupFilesAfterEnv: ['<rootDir>/jest.setup.js'],
}

// يتم تصدير createJestConfig بهذه الطريقة لضمان أن next/jest يمكنه تحميل تكوين Next.js، وهو غير متزامن
module.exports = createJestConfig(customJestConfig)

Relay

لتمكين دعم Relay:

module.exports = {
  compiler: {
    relay: {
      // يجب أن يتطابق هذا مع relay.config.js
      src: './',
      artifactDirectory: './__generated__',
      language: 'typescript',
      eagerEsModules: false,
    },
  },
}

جيد للمعرفة: في Next.js، جميع ملفات JavaScript في دليل pages تعتبر مسارات. لذا، بالنسبة لـ relay-compiler ستحتاج إلى تحديد إعدادات تكوين artifactDirectory خارج pages، وإلا فإن relay-compiler سينشئ ملفات بجانب الملف المصدر في دليل __generated__، وسيعتبر هذا الملف مسارًا، مما سيكسر بناء الإنتاج.

إزالة خصائص React

يسمح بإزالة خصائص JSX. هذا يستخدم غالبًا للاختبار. مشابه لـ babel-plugin-react-remove-properties.

لإزالة الخصائص التي تطابق التعبير العادي الافتراضي ^data-test:

module.exports = {
  compiler: {
    reactRemoveProperties: true,
  },
}

لإزالة خصائص مخصصة:

module.exports = {
  compiler: {
    // التعبيرات العادية المعرفة هنا تتم معالجتها في Rust لذا فإن التركيب مختلف عن
    // JavaScript `RegExp`s. انظر https://docs.rs/regex.
    reactRemoveProperties: { properties: ['^data-custom$'] },
  },
}

إزالة Console

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

إزالة جميع استدعاءات console.*:

module.exports = {
  compiler: {
    removeConsole: true,
  },
}

إزالة إخراج console.* باستثناء console.error:

module.exports = {
  compiler: {
    removeConsole: {
      exclude: ['error'],
    },
  },
}

Legacy Decorators

سيكتشف Next.js تلقائيًا experimentalDecorators في jsconfig.json أو tsconfig.json. تُستخدم الديكورات القديمة بشكل شائع مع إصدارات أقدم من المكتبات مثل mobx.

هذه العلامة مدعومة فقط لتوافق مع التطبيقات الموجودة. لا نوصي باستخدام الديكورات القديمة في التطبيقات الجديدة.

أولاً، قم بالتحديث إلى أحدث إصدار من Next.js: npm install next@latest. ثم، قم بتحديث ملف jsconfig.json أو tsconfig.json الخاص بك:

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

importSource

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

أولاً، قم بالتحديث إلى أحدث إصدار من Next.js: npm install next@latest. ثم، قم بتحديث ملف jsconfig.json أو tsconfig.json الخاص بك:

{
  "compilerOptions": {
    "jsxImportSource": "theme-ui"
  }
}

Emotion

نعمل على نقل @emotion/babel-plugin إلى مترجم Next.js.

أولاً، قم بالتحديث إلى أحدث إصدار من Next.js: npm install next@latest. ثم، قم بتحديث ملف next.config.js الخاص بك:

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

التصغير

يتم استخدام مترجم swc الخاص بـ Next.js للتصغير افتراضيًا منذ الإصدار v13. هذا أسرع بـ 7 مرات من Terser.

إذا كان Terser لا يزال مطلوبًا لأي سبب يمكن تكوين ذلك.

module.exports = {
  swcMinify: false,
}

تحويل الوحدات

يمكن لـ Next.js تحويل وتعبئة التبعيات تلقائيًا من الحزم المحلية (مثل monorepos) أو من التبعيات الخارجية (node_modules). هذا يحل محل حزمة next-transpile-modules.

module.exports = {
  transpilePackages: ['@acme/ui', 'lodash-es'],
}

Modularize Imports

تم استبدال هذا الخيار بـ optimizePackageImports في Next.js 13.5. نوصي بالترقية لاستخدام الخيار الجديد الذي لا يتطلب تكوينًا يدويًا لمسارات الاستيراد.

الميزات التجريبية

تتبع أداء SWC

يمكنك إنشاء تتبع التحويلات الداخلية لـ SWC كتنسيق trace event لـ chromium.

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

بمجرد التمكين، سينشئ swc تتبعًا باسم swc-trace-profile-${timestamp}.json تحت .next/. يمكن لمشاهد تتبع chromium (chrome://tracing/, https://ui.perfetto.dev/)، أو مشاهد flamegraph المتوافقة (https://www.speedscope.app/) تحميل وتصور التتبعات المولدة.

إضافات SWC (تجريبي)

يمكنك تكوين تحويل swc لاستخدام دعم الإضافات التجريبي لـ SWC المكتوب بـ wasm لتخصيص سلوك التحويل.

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

يقبل swcPlugins مصفوفة من tuples لتكوين الإضافات. يحتوي tuple للإضافة على مسار الإضافة وكائن لتكوين الإضافة. يمكن أن يكون مسار الإضافة اسم حزمة npm أو مسارًا مطلقًا إلى الملف الثنائي .wasm نفسه.

الميزات غير المدعومة

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

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

سجل الإصدارات