نصب و راه اندازی کامپایلر React

این راهنما به شما کمک می‌کند تا کامپایلر جدید React را در برنامه‌های خود نصب، پیکربندی و راه‌اندازی کنید.

نیازمندی‌ها (Prerequisites)

کامپایلر React به گونه‌ای طراحی شده است که بهترین کارایی را با React 19 داشته باشد، اما از نسخه‌های 17 و 18 نیز به طور کامل پشتیبانی می‌کند.

۱. نصب پکیج (Installation)

ابتدا باید پلاگین بابلِ کامپایلر را به عنوان یک وابستگی توسعه (devDependency) به پروژه خود اضافه کنید:

# با استفاده از npm
npm install -D babel-plugin-react-compiler@latest

# با استفاده از Yarn
yarn add -D babel-plugin-react-compiler@latest

# با استفاده از pnpm
pnpm install -D babel-plugin-react-compiler@latest

۲. پیکربندی ابزارهای ساخت (Basic Setup)

کامپایلر React به گونه‌ای طراحی شده که بدون نیاز به تنظیمات خاصی کار کند. فرآیند راه‌اندازی بر اساس ابزار ساخت پروژه شما (Build Tool) متفاوت است.

⚠️ یک تله و نکته بسیار مهم: پلاگین کامپایلر React حتماً باید اولین پلاگین در صف اجرای بابل (Babel Pipeline) باشد. کامپایلر برای تحلیل دقیق کدهای شما به کدهای منبع اصلی و دست‌نخورده نیاز دارد؛ بنابراین باید قبل از اعمال هرگونه تغییر یا تبدیل دیگری توسط سایر پلاگین‌ها، کدهای شما را پردازش کند.

تنظیم در Babel

فایل babel.config.js خود را ایجاد یا به‌روزرسانی کنید:

module.exports = {
  plugins: [
    'babel-plugin-react-compiler', // حتماً باید اولین گزینه باشد!
    // ... سایر پلاگین‌ها
  ],
};

تنظیم در Vite

اگر از ابزار Vite به همراه نسخه 6.0.0 یا بالاتر پلاگین رسمی راکت (@vitejs/plugin-react) استفاده می‌کنید، می‌توانید از قابلیت جدید reactCompilerPreset بهره ببرید. ابتدا پکیج بابل مربوطه را نصب کنید:

npm install -D @rolldown/plugin-babel

سپس فایل تنظیمات vite.config.js را به شکل زیر پیکربندی کنید:

// vite.config.js
import { defineConfig } from 'vite';
import react, { reactCompilerPreset } from '@vitejs/plugin-react';
import babel from '@rolldown/plugin-babel';

export default defineConfig({
  plugins: [
    react(),
    babel({
      presets: [reactCompilerPreset()]
    }),
  ],
});

نکته برای نسخه‌های قدیمی‌تر: در نسخه 6 پلاگین، امکان نوشتن کدهای بابل به صورت داخلی (Inline) حذف شده است. اگر از نسخه‌های قدیمی‌تر استفاده می‌کنید، باید بابل را به این شکل به آرگومان تابع react() پاس دهید:

// مخصوص نسخه‌های قدیمی‌تر vitejs/plugin-react@
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [
    react({
      babel: {
        plugins: ['babel-plugin-react-compiler'],
      },
    }),
  ],
});

تنظیم در React Router (نسخه 7)

پکیج vite-plugin-babel را نصب کرده و تنظیمات زیر را اعمال کنید:

// vite.config.js
import { defineConfig } from "vite";
import babel from "vite-plugin-babel";
import { reactRouter } from "@react-router/dev/vite";

export default defineConfig({
  plugins: [
    reactRouter(),
    babel({
      filter: /\.[jt]sx?$/,
      babelConfig: {
        presets: ["@babel/preset-typescript"], // اگر از تایپ‌اسکریپت استفاده می‌کنید
        plugins: [
          ["babel-plugin-react-compiler"],
        ],
      },
    }),
  ],
});

تنظیم در سایر ابزارها

• Metro (React Native): از آنجا که ری‌اکت نیتیو از طریق ابزار Metro با بابل هماهنگ می‌شود، کافی است تنظیمات بخش Babel را روی پروژه خود اعمال کنید.

• Webpack / Next.js / Expo / Rsbuild / Rspack: برای فعال‌سازی کامپایلر در این محیط‌ها، پیشنهاد می‌شود مستندات رسمی به‌روز شده‌ی هر کدام از این ابزارها را مطالعه کنید تا از آخرین هماهنگ‌کننده‌های بومی (مانند موتورهای SWC) استفاده کنید.

۳. هماهنگ‌سازی با ابزار خطایابی (ESLint Integration)

کامپایلر React شامل یک قانون (Rule) تخصصی برای ESLint است. وظیفه این قانون، شناسایی کدهایی است که با ساختار کامپایلر سازگار نیستند و نمی‌توان آن‌ها را بهینه‌سازی کرد.

هنگامی که این ابزار خطایی را گزارش می‌کند، کامپایلر به سادگی از بهینه‌سازی آن کامپوننت یا هوک خاص عبور می‌کند و به سراغ بقیه کدهای پروژه می‌رود؛ بنابراین برنامه شما دچار کرش یا خرابی نخواهد شد و شما می‌توانید با خیال راحت و سر فرصت خطاها را یکی‌یکی اصلاح کنید.

برای نصب پلاگین ESLint دستور زیر را اجرا کنید:

npm install -D eslint-plugin-react-hooks@latest

قوانین جدید کامپایلر در قالب پری‌ستِ recommended-latest در دسترس هستند و به شما کمک می‌کنند تا نقض قوانین اصلی راکت را سریعاً پیدا کرده و برطرف کنید.

۴. تایید و راستی‌آزمایی کارکرد کامپایلر (Verify Setup)

پس از نصب، به دو روش می‌توانید مطمئن شوید که کامپایلر با موفقیت در حال بهینه‌سازی کدهای شماست:

روش اول: بررسی از طریق React DevTools (آسان‌ترین راه)

کامپوننت‌هایی که توسط کامپایلر بهینه‌سازی شده باشند، در افزونه React DevTools یک نشان درخشان به شکل "✨ Memo" دریافت می‌کنند:

1. مطمئن شوید افزونه مرورگر React Developer Tools روی سیستم شما نصب است.

2. برنامه خود را در محیط توسعه (Development Mode) اجرا کنید.

3. بخش Inspect مروگر و تب ⚛️ Components را باز کنید.

4. به دنبال اموجی ستاره ✨ در کنار نام کامپوننت‌های خود بگردید. وجود این نشان یعنی کدهای آن کامپوننت بدون نوشتن حتی یک هوک دستی، کاملاً بهینه‌سازی شده‌اند.

روش دوم: بررسی کدهای خروجی (Build Output)

اگر کدهای نهایی کامپایل شده پروژه خود را باز کنید، متوجه خواهید شد که کامپایلر کدی شبیه به ساختار زیر را (که حاوی کدهای مدیریت حافظه پنهان و کش به کمک تابع _c از پکیج react/compiler-runtime است) به خروجی شما تزریق کرده است:

import { c as _c } from "react/compiler-runtime";
export default function MyApp() {
  const $ = _c(1);
  let t0;
  if ($[0] === Symbol.for("react.memo_cache_sentinel")) {
    t0 = <div>سلام دنیا</div>;
    $[0] = t0;
  } else {
    t0 = $[0];
  }
  return t0;
}

۵. خروج اضطراری از حالت کامپایل (Troubleshooting)

اگر پس از فعال‌سازی کامپایلر، متوجه شدید که کامپوننت خاصی رفتار عجیبی نشان می‌دهد یا دچار مشکل شده است، نیاز نیست کل کامپایلر را غیرفعال کنید. شما می‌توانید با استفاده از دستور متنی "use no memo" در بالاترین خط آن کامپوننت، آن را به طور موقت از چرخه بهینه‌سازی کامپایلر خارج کنید:

function ProblematicComponent() {
  "use no memo"; // کامپایلر این کامپوننت را نادیده می‌گیرد
  
  // کدهای کامپوننت شما در این قسمت قرار می‌گیرد
}

پس از اینکه ریشه مشکل (که معمولاً نقض یکی از قوانین پایه‌ای راکت است) را پیدا و برطرف کردید، می‌توانید این خط را حذف کنید تا کامپوننت دوباره به صورت خودکار بهینه‌سازی شود.