مهاجرت و ادغام تدریجی

اگر می‌خواهید به پروژه فعلی خود قابلیت‌های تعاملی (Interactivity) اضافه کنید، نیازی نیست کل کدهای خود را دور بریزید و آن را از اول با React بازنویسی کنید. شما می‌توانید React را به پشته فناوری (Stack) فعلی خود اضافه کرده و کامپوننت‌های تعاملی آن را در هر کجای صفحات خود رندر کنید.

پیش‌نیاز توسعه محلی: برای توسعه پروژه در سیستم خود، حتماً باید Node.js را نصب داشته باشید. اگرچه می‌توان React را در محیط‌های آنلاین یا صفحات ساده HTML آزمایش کرد، اما در دنیای واقعی، اکثر ابزارهای جاوااسکریپت برای فرآیند کامپایل و توسعه به Node.js وابسته هستند.

سناریوی اول: استفاده از React برای یک زیرمسیر (Subroute) کامل

تصور کنید یک برنامه وب در آدرس example.com دارید که با یک فناوری سمت سرور دیگر (مانند Ruby on Rails) ساخته شده است، اما تصمیم دارید تمام صفحات و آدرس‌هایی که با example.com/some-app/* شروع می‌شوند را کاملاً با React پیاده‌سازی کنید.

مراحل پیاده‌سازی پیشنهادی:

1. بخش React برنامه را با یک فریم‌ورک استاندارد بسازید: پروژه جدید را با فریم‌ورک‌هایی مانند Next.js راه‌اندازی کنید.

2. تنظیم مسیر پایه (Base Path): آدرس /some-app را به عنوان مسیر پایه در تنظیمات فریم‌ورک خود مشخص کنید (این قابلیت در تمام فریم‌ورک‌های استاندارد پشتیبانی می‌شود).

3. پیکربندی سرور یا پروکسی: سرور اصلی یا سیستم Proxy خود را طوری تنظیم کنید که تمام درخواست‌های ارسالی به مسیر /some-app/* را مستقیماً به برنامه React هدایت کند.

نکته فنی: بسیاری از فریم‌ورک‌های مبتنی بر React به صورت فول‌استک عمل می‌کنند. با این حال، اگر نمی‌توانید یا تمایلی ندارید که جاوااسکریپت را روی سرور اجرا کنید، جای نگرانی نیست؛ کافی است خروجی کاملاً استاتیک پروژه (شامل HTML/CSS/JS) را تولید کرده و آن را در پوشه مربوط به مسیر /some-app/ در سرور خود قرار دهید.

سناریوی دوم: استفاده از React در بخشی از یک صفحه موجود

فرض کنید صفحه‌ای دارید که با فناوری دیگری (چه سمت سرور مثل Rails و چه سمت کلاینت مثل Backbone) ساخته شده است و فقط می‌خواهید یک کامپوننت تعاملی React را در نقطه‌ای خاص از آن صفحه رندر کنید. این روش، یکی از رایج‌ترین شیوه‌های ادغام React است (در واقع شرکت Meta نیز سال‌ها به همین شکل از React در پلتفرم‌های خود استفاده می‌کرد).

این کار در دو گام اصلی انجام می‌شود:

1. راه اندازی یک محیط جاوااسکریپت ماژولار که از سینتکس JSX و سیستم ماژول (import/export) پشتیبانی کند.

2. رندر کردن کامپوننت‌های React در موقعیت‌های دلخواه از صفحه HTML.

گام اول: راه‌اندازی محیط ماژولار جاوااسکریپت (Modular JS Environment)

این محیط به شما اجازه می‌دهد کامپوننت‌های خود را در فایل‌های مجزا بنویسید و از پکیج‌های مخزن npm (از جمله خودِ پکیج React) استفاده کنید.

• اگر پروژه شما از قبل سیستم ماژول (دستورات import) دارد: بررسی کنید که آیا نوشتن یک تگ مانند <div /> در کدهای جاوااسکریپت باعث خطای سینتکس (Syntax Error) می‌شود یا خیر. اگر خطا داد، باید ابزار Babel را به همراه پلاگین اختصاصی @babel/preset-react تنظیم کنید تا کدهای JSX به جاوااسکریپت استاندارد تبدیل شوند.

• اگر پروژه شما سیستم کامپایلر ندارد: پیشنهاد می‌شود آن را با ابزار Vite راه‌اندازی کنید. جامعه کاربری Vite افزونه‌های آماده‌ای برای اتصال به فریم‌ورک‌های بک‌اند مانند Rails، Django و Laravel توسعه داده‌اند.

برای تست کارکرد محیط، دستور زیر را در ترمینال پوشه پروژه اجرا کنید:

npm install react react-dom

سپس این کدهای تست را در بالاترین بخش فایل اصلی جاوااسکریپت خود (مانند index.js یا main.js) قرار دهید:

// index.js
import { createRoot } from 'react-dom/client';

// پاک کردن موقت محتوای کل صفحه برای تست
document.body.innerHTML = '<div id="app"></div>';

// رندر کردن یک المان ساده React
const root = createRoot(document.getElementById('app'));
root.render(<h1>Hello, world</h1>);

اگر پس از بازخوانی صفحه، کل محتوای قبلی حذف شد و عبارت "!Hello, world" را دیدید، یعنی محیط شما با موفقیت آماده کار شده است.

گام دوم: رندر کردن کامپوننت‌های React در موقعیت‌های دلخواه

قطعاً در پروژه واقعی شما نمی‌خواهید کل محتوای HTML قبلی صفحه را پاک کنید! بنابراین کدهای تست مرحله قبل را حذف کنید.

هدف ما این است که کامپوننت‌ها را در جاهای مشخصی از فایل HTML تزریق کنیم. ابتدا فایل HTML (یا قالب‌های سمت سرور که آن را تولید می‌کنند) را باز کرده و یک شناسه منحصربه‌فرد (id) به تگ مدنظر خود اضافه کنید:

<nav id="navigation"></nav>

حالا با استفاده از دستور document.getElementById این المان را در فایل جاوااسکریپت پیدا کرده، آن را به متد createRoot تحویل می‌دهید و کامپوننت اختصاصی خود را درون آن رندر می‌کنید:

// index.js
import { createRoot } from 'react-dom/client';

// تعریف کامپوننت منو
function NavigationBar() {
  return <h1>Hello from React!</h1>;
}

// یافتن المان نگهدارنده در HTML قدیمی و رندر کامپوننت درون آن
const domNode = document.getElementById('navigation');
const root = createRoot(domNode);
root.render(<NavigationBar />);

با این کار، ساختار و محتوای اصلی صفحه HTML شما کاملاً حفظ می‌شود، اما کامپوننت <NavigationBar /> دقیقاً داخل تگ <nav id="navigation"> ظاهر خواهد شد.

استراتژی مهاجرت تدریجی: هنگام اضافه کردن React به پروژه‌های قدیمی، معمولاً کار را با المان‌های تعاملی کوچک (مثل دکمه‌ها یا فرم‌ها) شروع می‌کنند و به مرور زمان بخش‌های بزرگ‌تری از صفحه را به کامپوننت‌های React تبدیل می‌کنند. اگر در نهایت به نقطه‌ای رسیدید که کل صفحه شما تبدیل به React شد، پیشنهاد می‌شود برای بهره‌مندی از حداکثر کارایی، پروژه را به یک فریم‌ورک اختصاصی (مثل Next.js) مهاجرت دهید.

استفاده از React Native در برنامه‌های موبایل قدیمی (Native Apps)

دقیقاً مشابه دنیای وب، فریم‌ورک React Native را نیز می‌توان به صورت گام‌به‌گام و تدریجی به برنامه‌های موبایل بومی اضافه کرد. اگر یک اپلیکیشن اندروید (با زبان‌های Java یا Kotlin) یا آی‌او‌اس (با زبان‌های Objective-C یا Swift) دارید، می‌توانید بخش یا صفحاتی از آن را بدون تغییر دادن کل ساختار اپلیکیشن، با React Native پیاده‌سازی و یکپارچه‌سازی کنید.