---
url: /guide/rolldown.md
---
# یکپارچه‌سازی با Rolldown

Vite در نظر دارد برای بهبود عملکرد و بهینه‌سازی فرآیند ساخت (build)، از [Rolldown](https://rolldown.rs) استفاده کند؛ باندلری مبتنی بر Rust.

## Rolldown چیست؟

Rolldown یک باندلر مدرن و پرسرعت برای JavaScript است که با زبان Rust نوشته شده. این ابزار با هدف جایگزینی مستقیم با Rollup طراحی شده و تلاش دارد تا بدون ایجاد ناسازگاری با اکوسیستم فعلی، بهبود چشم‌گیری در عملکرد ارائه دهد.

Rolldown بر سه اصل کلیدی تمرکز دارد:

* **سرعت**: با استفاده از زبان Rust ساخته شده تا حداکثر کارایی را ارائه دهد
* **سازگاری**: با افزونه‌های موجود Rollup به‌خوبی کار می‌کند
* **بهینه‌سازی**: دارای قابلیت‌هایی است که فراتر از امکانات esbuild و Rollup عمل می‌کنند

## چرا Vite در حال مهاجرت به Rolldown است؟

1. **یکپارچگی**: Vite در حال حاضر از esbuild برای پیش‌پردازش وابستگی‌ها و از Rollup برای ساخت نهایی استفاده می‌کند. Rolldown قصد دارد این دو مرحله را در یک باندلر واحد و پرسرعت ادغام کند تا پیچیدگی کاهش یابد.

2. **کارایی بالا**: پیاده‌سازی Rolldown بر پایه‌ی Rust باعث افزایش چشمگیر سرعت نسبت به باندلرهای مبتنی بر JavaScript شده است. هرچند نتایج ممکن است بسته به اندازه و پیچیدگی پروژه متفاوت باشند، اما تست‌های اولیه افزایش سرعت امیدوارکننده‌ای نسبت به Rollup نشان داده‌اند.

3. **قابلیت‌های بیشتر**: Rolldown امکاناتی ارائه می‌دهد که در Rollup یا esbuild وجود ندارند، مانند کنترل پیشرفته بر تقسیم چانک‌ها (chunk splitting)، HMR داخلی و پشتیبانی از Module Federation.

برای اطلاعات بیشتر درباره انگیزه‌های ساخت Rolldown، به [دلایل ساخت آن](https://rolldown.rs/guide/#why-rolldown) مراجعه کنید.

## مزایای امتحان کردن `rolldown-vite`

* تجربه زمان ساخت بسیار سریع‌تر، به‌ویژه در پروژه‌های بزرگ
* مشارکت در بهبود تجربه باندلینگ Vite از طریق ارائه بازخوردهای ارزشمند
* آماده‌سازی پروژه‌های شما برای یکپارچه‌سازی رسمی Rolldown در آینده

## چگونه Rolldown را امتحان کنیم

نسخه‌ای از Vite که با Rolldown پشتیبانی می‌شود، در حال حاضر به‌صورت یک بسته جداگانه با نام `rolldown-vite` در دسترس است. اگر در پروژه خود `vite` را به‌عنوان یک وابستگی مستقیم دارید، می‌توانید در فایل `package.json`، بسته `vite` را با استفاده از ویژگی "alias" به `rolldown-vite` ارجاع دهید. این کار باعث می‌شود هرجا که پروژه به `vite` ارجاع می‌دهد، در واقع `rolldown-vite` بارگذاری شود (بدون نیاز به تغییرات اضافی در کد).

```json
{
  "dependencies": {
    "vite": "^7.0.0" // [!code --]
    "vite": "npm:rolldown-vite@latest" // [!code ++]
  }
}
```

اگر از VitePress یا یک متافریم‌ورک استفاده می‌کنید که `vite` را به‌عنوان وابستگی همتا (peer dependency) دارد، باید وابستگی `vite` را در فایل `package.json` پروژه‌ خود جایگزین کنید. نحوه‌ی انجام این کار بسته به ابزار مدیریت بسته‌ای که استفاده می‌کنید (مانند npm ، yarn یا pnpm) کمی متفاوت است.

:::code-group

```json [npm]
{
  "overrides": {
    "vite": "npm:rolldown-vite@latest"
  }
}
```

```json [Yarn]
{
  "resolutions": {
    "vite": "npm:rolldown-vite@latest"
  }
}
```

```json [pnpm]
{
  "pnpm": {
    "overrides": {
      "vite": "npm:rolldown-vite@latest"
    }
  }
}
```

```json [Bun]
{
  "overrides": {
    "vite": "npm:rolldown-vite@latest"
  }
}
```

:::

پس از افزودن این overrides، کافی‌ست وابستگی‌های پروژه را مجدداً نصب کرده و سرور توسعه را راه‌اندازی یا پروژه را طبق روال همیشگی build کنید. هیچ تنظیمات اضافه‌ دیگری نیاز نیست.

## محدودیت‌های شناخته‌شده

با وجود اینکه Rolldown با هدف جایگزینی مستقیم برای Rollup توسعه یافته، هنوز برخی ویژگی‌ها در حال پیاده‌سازی هستند و تفاوت‌های رفتاری جزئی (و گاه عمده) نیز وجود دارد. برای مشاهده‌ی فهرست کامل و به‌روز این موارد، می‌توانید به [این Pull Request در GitHub](https://github.com/vitejs/rolldown-vite/pull/84#issue-2903144667) مراجعه کنید.

### هشدارهای اعتبارسنجی آپشن‌ها (Option Validation Warnings) {#option-validation-warnings}

Rolldown در صورتی که آپشن‌ای ناشناخته یا نامعتبر به آن داده شود، هشدار نمایش می‌دهد. از آنجا که برخی از آپشن‌های موجود در Rollup در حال حاضر در Rolldown پشتیبانی نمی‌شوند، ممکن است هنگام استفاده، بسته به تنظیمات شما یا متافریموکی که استفاده می‌کنید، با هشدار مواجه شوید. در ادامه نمونه‌ای از پیام چنین هشدارd آمده است:

> Warning validate output options.
>
> * For the "generatedCode". Invalid key: Expected never but received "generatedCode".

اگر خودتان این آپشن را اضافه نکرده‌اید، این مشکل باید توسط فریمورک مورد استفاده شما اصلاح شود.

### تفاوت‌های API

#### از `manualChunks` به `advancedChunks`

در Rolldown آپشن `manualChunks` که در Rollup وجود داشت، پشتیبانی نمی‌شود. در عوض Rolldown آپشن دقیق‌تر و قابل تنظیم‌تری به نام [`advancedChunks`](https://rolldown.rs/guide/in-depth/advanced-chunks#advanced-chunks) ارائه می‌دهد، که بیشتر شبیه به تنظیمات `splitChunk` در webpack است.

```js
// (Rollup) کانفیگ قدیمی
export default {
  build: {
    rollupOptions: {
      output: {
        manualChunks(id) {
          if (/\/react(?:-dom)?/.test(id)) {
            return 'vendor'
          }
        }
      }
    }
  }
}

// (Rolldown) کانفیگ جدید
export default {
  build: {
    rollupOptions: {
      output: {
        advancedChunks: {
          groups: [{ name: 'vendor', test: /\/react(?:-dom)?// }]
        }
      }
    }
  }
}
```

## عملکرد (Performance)

پکیج `rolldown-vite` تمرکز خود را بر حفظ سازگاری با اکوسیستم فعلی قرار داده است، بنابراین تنظیمات پیش‌فرض به‌گونه‌ای طراحی شده‌اند که انتقال از نسخه‌ی معمول Vite به‌راحتی انجام شود. با این حال، برای به‌دست آوردن عملکرد بهتر، می‌توانید از پلاگین‌های داخلی مبتنی بر Rust و سایر تنظیمات سفارشی‌سازی‌شده‌ی سریع‌تر استفاده کنید.

### فعال‌سازی پلاگین‌های بومی

با تشکر از Rolldown و Oxc، پلاگین‌های داخلی مختلف Vite مانند پلاگین‌های alias یا resolve به زبان Rust تبدیل شده‌اند. در زمان نگارش این مطلب، استفاده از این پلاگین‌ها به طور پیش‌فرض فعال نیست، زیرا رفتار آنها ممکن است با نسخه‌های جاوااسکریپتی متفاوت باشد.

برای تست این پلاگین‌ها، می‌توانید گزینه `experimental.enableNativePlugin` را در فایل کانفیگ Vite خود به مقدار `true` تنظیم کنید.

### ‎`@vitejs/plugin-react-oxc`

اگر از ‎`@vitejs/plugin-react` یا ‎`@vitejs/plugin-react-swc` استفاده می‌کنید، می‌توانید به پلاگین ‎`@vitejs/plugin-react-oxc` تغییر دهید. این پلاگین به جای Babel یا SWC ، از Oxc برای قابلیت fast-refresh در React استفاده می‌کند. این پلاگین به‌گونه‌ای طراحی شده که بدون نیاز به تغییرات زیاد، جایگزینی مستقیم (drop-in replacement) برای پلاگین‌های قبلی باشد و عملکرد ساخت (build) را بهبود دهد. همچنین با معماری داخلی `rolldown-vite` سازگارتر است.

توجه داشته باشید که تنها در صورتی می‌توانید به ‎`@vitejs/plugin-react-oxc` مهاجرت کنید که از هیچ پلاگین Babel یا SWC استفاده نکنید (از جمله کامپایلر React) یا تنظیمات SWC را تغییر (mutate) نداده باشید.

### بسته‌بندی‌کننده‌ی `withFilter`

نویسندگان پلاگین این امکان را دارند که از [قابلیت فیلتر هوک](#hook-filter-feature) برای کاهش سربار ارتباطی بین محیط‌های اجرای Rust و JavaScript استفاده کنند.
اما اگر برخی از پلاگین‌هایی که استفاده می‌کنید هنوز از این ویژگی پشتیبانی نمی‌کنند و با این حال مایلید از مزایای آن بهره‌مند شوید، می‌توانید با استفاده از بسته‌بندی‌کننده‌ی `withFilter`، خودتان آن پلاگین را درون یک فیلتر قرار دهید.

```js
// In your vite.config.ts
import { withFilter, defineConfig } from 'vite'
import svgr from 'vite-plugin-svgr'

export default defineConfig({
  plugins: [
    // Load the `svgr` plugin only for files which end in `.svg?react`
    withFilter(
      svgr({
        /*...*/
      }),
      { load: { id: /\.svg\?react$/ } },
    ),
  ],
})
```

## گزارش مشکلات

از آنجا که این یک ادغام آزمایشی است، ممکن است با مشکلاتی مواجه شوید. در صورت بروز هرگونه مشکل، لطفاً آن را در مخزن [`vitejs/rolldown-vite`](https://github.com/vitejs/rolldown-vite) گزارش دهید، **نه در مخزن اصلی Vite**.

هنگام [گزارش مشکلات](https://github.com/vitejs/rolldown-vite/issues/new)، لطفاً از الگوی مناسب استفاده کرده و موارد خواسته شده در آن را فراهم کنید، که معمولاً شامل موارد زیر است:

* یک نسخه حداقلی از مشکل
* جزئیات محیط شما (سیستم‌عامل، نسخه Node، مدیر بسته)
* هرگونه پیام خطا یا لاگ مرتبط

برای بحث و گفتگو مستقیم و رفع اشکال، حتماً به [Discord Rolldown](https://chat.rolldown.rs/) بپیوندید.

## سیاست نسخه‌بندی

سیاست نسخه‌بندی در `rolldown-vite` به‌گونه‌ای تنظیم شده که نسخه‌های اصلی (major) و فرعی (minor) آن با نسخه‌های متناظر در پکیج رسمی Vite هماهنگ باشد. این هم‌راستایی باعث می‌شود که قابلیت‌هایی که در یک نسخه‌ی فرعی مشخص از Vite وجود دارند، در نسخه‌ی فرعی متناظر `rolldown-vite` نیز در دسترس باشند. با این حال، توجه داشته باشید که نسخه‌های وصله‌ای (patch) بین این دو پروژه هماهنگ نیستند. بنابراین، اگر می‌خواهید مطمئن شوید که یک تغییر خاص از Vite معمولی در `rolldown-vite` نیز لحاظ شده است یا نه، می‌توانید به [تغییرات منتشرشده‌ی جداگانه‌ی `rolldown-vite`](https://github.com/vitejs/rolldown-vite/blob/rolldown-vite/packages/vite/CHANGELOG.md) مراجعه کنید.

همچنین توجه داشته باشید که خود `rolldown-vite` یک پروژه‌ی آزمایشی محسوب می‌شود. به دلیل ماهیت آزمایشی آن، ممکن است حتی در نسخه‌های وصله‌ای (patch) نیز تغییرات ناسازگار (breaking changes) ایجاد شود. افزون بر این، `rolldown-vite` تنها برای جدیدترین نسخه‌ی فرعی (minor) خود به‌روزرسانی دریافت می‌کند. حتی در صورت وجود اشکالات مهم یا آسیب‌پذیری‌های امنیتی، برای نسخه‌های قدیمی‌تر (اعم از نسخه‌های اصلی یا فرعی)، وصله‌ای منتشر نخواهد شد.

## برنامه‌های آینده

پکیج `rolldown-vite` یک راه‌حل موقتی است که برای جمع‌آوری بازخورد و تثبیت ادغام Rolldown طراحی شده است. در آینده، این قابلیت به مخزن اصلی Vite اضافه خواهد شد.

ما شما را تشویق می‌کنیم که بسته `rolldown-vite` را امتحان کنید و از طریق بازخورد و گزارش مشکلات، به توسعه آن کمک کنید.

در آینده، همچنین حالت "Full Bundle Mode" برای Vite معرفی خواهد شد که فایل‌های باندل شده را هم در حالت پروداکش و هم در *حالت توسعه* سرویس‌دهی می‌کند.

### چرا حالت Full Bundle Mode معرفی می‌شود؟

Vite به دلیل رویکرد سرور توسعه بدون بسته‌بندی شناخته شده است که یکی از دلایل اصلی سرعت و محبوبیت آن در زمان معرفی بود. این رویکرد در ابتدا به‌عنوان یک آزمایش برای بررسی اینکه چه‌قدر می‌توانیم مرزهای عملکرد سرور توسعه را بدون استفاده از بسته‌بندی سنتی جابجا کنیم، معرفی شد.

با این حال، با افزایش مقیاس و پیچیدگی پروژه‌ها، دو چالش اصلی به وجود آمده است:

1. **ناسازگاری بین محیط توسعه و پروداکشن**: در حالت توسعه، جاوااسکریپت بدون بسته‌بندی ارائه می‌شود، درحالی که در پروداکشن، فایل‌ها به‌صورت بسته‌بندی‌شده هستند. این تفاوت می‌تواند منجر به بروز رفتارهای متفاوت در زمان اجرا شود؛ رفتارهایی که فقط در محیط پروداکشن ظاهر می‌شوند و اشکال‌زدایی آن‌ها را دشوار می‌کنند.

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

با یکپارچه‌سازی Rolldown، این فرصت فراهم شده است تا تجربه‌های توسعه و پروداکشن را با حفظ عملکرد شاخص Vite، به یکدیگر نزدیک کنیم. «حالت بسته‌بندی کامل» (Full Bundle Mode) این امکان را فراهم می‌سازد که فایل‌های بسته‌بندی‌شده نه‌تنها در پروداکشن، بلکه در محیط توسعه نیز ارائه شوند؛ و این یعنی تلفیقی از بهترین ویژگی‌های هر دو دنیا:

* **زمان راه‌اندازی سریع حتی برای پروژه‌های بزرگ**
* **رفتار یکنواخت بین محیط توسعه و تولید**
* **کاهش سربار شبکه در هنگام بارگذاری مجدد صفحه**
* **حفظ بهینگی HMR در کنار خروجی مبتنی بر ESM**

در ابتدای معرفی، حالت Full Bundle به‌صورت **اختیاری (opt-in)** فعال خواهد شد. همانند یکپارچه‌سازی Rolldown، هدف این است که پس از دریافت بازخورد و اطمینان از پایداری، به‌صورت **پیش‌فرض** فعال شود.

## راهنمای نویسندگان افزونه‌ها و فریم‌ورک‌ها

::: tip نکته
این بخش بیشتر برای نویسندگان افزونه‌ها و سازندگان فریم‌ورک‌ها کاربرد دارد. اگر شما صرفاً یک کاربر نهایی هستید، می‌توانید از خواندن این بخش صرف‌نظر کنید.
:::

### مروری بر تغییرات مهم

* از Rolldown به‌جای Rollup برای فرایند build استفاده می‌شود.
* موتور بهینه‌سازی (optimizer) اکنون Rolldown است (قبلاً esbuild بود).
* پشتیبانی از CommonJS اکنون توسط Rolldown انجام می‌شود (قبلاً از ‎@rollup/plugin-commonjs استفاده می‌شد).
* برای پایین آوردن سطح سینتکس (syntax lowering) از Oxc استفاده می‌شود (قبلاً esbuild انجام می‌داد).
* فشرده‌سازی CSS به‌صورت پیش‌فرض با Lightning CSS انجام می‌شود (قبلاً esbuild بود).
* فشرده‌سازی جاوااسکریپت نیز اکنون به‌طور پیش‌فرض با Oxc minifier انجام می‌شود (به‌جای esbuild).
* برای باندل کردن فایل پیکربندی Vite نیز Rolldown به‌جای esbuild استفاده شده است.

### شناسایی `rolldown-vite` {#detecting-rolldown-vite}

::: warning هشدار
در بیشتر موارد، نیازی نیست بررسی کنید که آیا پلاگین شما با `rolldown-vite` اجرا می‌شود یا با Vite معمولی؛ بهتر است در هر دو حالت، رفتار یکسانی داشته باشید و از شرط‌گذاری در کد خودداری کنید.
:::

اگر لازم است در صورت استفاده از `rolldown-vite` رفتار متفاوتی داشته باشید، دو راه برای شناسایی آن وجود دارد:

بررسی وجود ویژگی `this.meta.rolldownVersion`:

```js
const plugin = {
  resolveId() {
    if (this.meta.rolldownVersion) {
      // rolldown-vite کد برای
    } else {
      // rollup-vite کد برای
    }
  },
}
```

::: tip نکته

از نسخه‌ی ۷.۰.۰ به بعد، `this.meta` در تمام هوک‌ها در Vite در دسترس است. در نسخه‌های قبلی، `this.meta` در هوک‌های اختصاصی Vite مانند هوک `config` در دسترس نبود.

:::

بررسی وجود `rolldownVersion`:

```js
import * as vite from 'vite'

if (vite.rolldownVersion) {
  // rolldown-vite کد برای
} else {
  // rollup-vite کد برای
}
```

اگر `vite` را به‌عنوان یک وابستگی (نه وابستگی همتا / peer dependency) دارید، `rolldownVersion` مفید است زیرا می‌توان آن را از هر جای کدتان استفاده کنید.

### نادیده گرفتن اعتبارسنجی آپشن‌ها در Rolldown

همان‌طور که [در بالا اشاره شد](#option-validation-warnings)، Rolldown زمانی که آپشن‌های ناشناس یا نامعتبری به آن داده شود، هشدار می‌دهد.

این مشکل را می‌توان با ارسال شرطی آپشن، بسته به اینکه آیا پروژه با `rolldown-vite` اجرا می‌شود یا نه، حل کرد (همان‌طور که [در بالا نشان داده شد](#detecting-rolldown-vite)).

### `transformWithEsbuild` نیاز به نصب جداگانه‌ی `esbuild` دارد

از آنجا که Vite دیگر خودش از `esbuild` استفاده نمی‌کند، اکنون `esbuild` به‌عنوان یک وابستگی هم‌سطح اختیاری (optional peer dependency) در نظر گرفته می‌شود. بنابراین اگر پلاگین شما از `transformWithEsbuild` استفاده می‌کند، یا باید خود پلاگین `esbuild` را در وابستگی‌هایش اضافه کند، یا کاربر باید آن را به صورت دستی نصب کند.

مهاجرت پیشنهادی این است که از تابع جدید `transformWithOxc` استفاده کنید که به جای `esbuild` از **Oxc** بهره می‌برد.

### لایه‌ی سازگاری برای آپشن‌های `esbuild`

پکیج Rolldown-Vite یک لایه‌ی سازگاری برای تبدیل آپشن‌های مربوط به `esbuild` به آپشن‌های معادل در Oxc یا `rolldown` دارد. همان‌طور که در [ecosystem-ci](https://github.com/vitejs/vite-ecosystem-ci/blob/rolldown-vite/README-temp.md) تست شده، این قابلیت در بسیاری از موارد، از جمله افزونه‌های ساده‌ی `esbuild`، به‌خوبی کار می‌کند.
با این حال، **پشتیبانی از آپشن‌های `esbuild` در آینده حذف خواهد شد** و به شما توصیه می‌شود از آپشن‌های متناظر در Oxc یا `rolldown` استفاده کنید.
می‌توانید آپشن‌هایی را که توسط این لایه‌ی سازگاری تنظیم شده‌اند، از طریق هوک `configResolved` دریافت کنید.

```js
const plugin = {
  name: 'log-config',
  configResolved(config) {
    console.log('options', config.optimizeDeps, config.oxc)
  },
},
```

### قابلیت فیلتر هوک (Hook Filter) {#hook-filter-feature}

Rolldown قابلیتی به نام [فیلتر هوک](https://rolldown.rs/guide/plugin-development#plugin-hook-filters) معرفی کرده است که هدف آن کاهش سربار ارتباطی بین محیط‌های اجرایی Rust و JavaScript است. با استفاده از این ویژگی، می‌توانید پلاگین خود را کارآمدتر کنید.
این قابلیت همچنین از نسخه‌ی 4.38.0 به بعد در Rollup و از نسخه‌ی 6.3.0 به بعد در Vite پشتیبانی می‌شود. برای اینکه پلاگین شما با نسخه‌های قدیمی‌تر نیز سازگار باقی بماند، توصیه می‌شود فیلتر را علاوه بر تعریف اولیه، درون بدنه‌ی هوک‌ها نیز اجرا کنید.

::: tip نکته

پکیج [‎`@rolldown/pluginutils`](https://www.npmjs.com/package/@rolldown/pluginutils) برخی ابزارهای کمکی (utilities) برای فیلتر کردن هوک‌ها فراهم می‌کند، مانند توابع `exactRegex` و `prefixRegex`.

:::

### تبدیل محتوا به JavaScript در هوک‌های `load` یا `transform`

اگر در هوک‌های `load` یا `transform` محتوایی را از انواع دیگر به JavaScript تبدیل می‌کنید، ممکن است نیاز باشد ویژگی `moduleType: 'js'‎` را به مقدار بازگشتی اضافه کنید. این کار به Rolldown یا Vite کمک می‌کند تا نوع ماژول را به‌درستی تشخیص داده و پردازش لازم را انجام دهد. در غیر این صورت، ممکن است محتوا به‌عنوان نوعی غیر از JavaScript در نظر گرفته شود و باعث خطا یا رفتارهای پیش‌بینی‌نشده شود.

```js
const plugin = {
  name: 'txt-loader',
  load(id) {
    if (id.endsWith('.txt')) {
      const content = fs.readFile(id, 'utf-8')
      return {
        code: `export default ${JSON.stringify(content)}`,
        moduleType: 'js', // [!code ++]
      }
    }
  },
}
```

این به این دلیل است که [Rolldown از ماژول‌هایی غیر از JavaScript نیز پشتیبانی می‌کند](https://rolldown.rs/guide/in-depth/module-types) و نوع ماژول را معمولاً بر اساس پسوند فایل تشخیص می‌دهد، مگر اینکه صراحتاً مشخص شده باشد.