---
url: /changes/this-environment-in-hooks.md
---
# `this.environment` در هوک‌ها

::: tip بازخورد
به ما در [Environment API feedback discussion](https://github.com/vitejs/vite/discussions/16358) بازخورد دهید
:::

پیش از Vite 6، فقط دو محیط موجود بود: `client` و `ssr`. یک آرگومان هوک پلاگین `options.ssr` در `resolveId`، `load` و `transform` به نویسندگان پلاگین این امکان را می‌داد که هنگام پردازش ماژول‌ها در هوک‌های پلاگین، این دو محیط را از هم تمایز دهند. در Vite 6، یک برنامه Vite می‌تواند هر تعداد محیط نام‌گذاری‌شده را طبق نیاز تعریف کند. ما `this.environment` را در زمینه پلاگین معرفی می‌کنیم تا با محیط ماژول جاری در هوک‌ها تعامل داشته باشیم.

دامنه تاثیر: `نویسندگان پلاگین Vite`

::: warning منسوخ‌شدن در آینده
`this.environment` در نسخه `v6.0` معرفی‌شد. منسوخ شدن `options.ssr` برای یکی از نسخه‌های اصلی (major) آینده برنامه‌ریزی شده است. در آن زمان، شروع به توصیه به مهاجرت پلاگین‌ها به استفاده از API جدید خواهیم کرد. برای شناسایی استفاده از این ویژگی، می‌توانید `future.removePluginHookSsrArgument` را در تنظیمات Vite خود به مقدار `"warn"` تنظیم کنید.
:::

## انگیزه

`this.environment` نه تنها به پیاده‌سازی هوک پلاگین اجازه می‌دهد که نام محیط جاری را بداند، بلکه دسترسی به گزینه‌های پیکربندی محیط، اطلاعات گراف ماژول، و خط لوله تبدیل (transform pipeline) را نیز فراهم می‌کند (`environment.config`، `environment.moduleGraph`، `environment.transformRequest `). در دسترس بودن نمونه محیط در زمینه پلاگین به نویسندگان پلاگین این امکان را می‌دهد که از وابستگی به سرور توسعه کامل (که معمولاً از طریق هوک `configureServer` در ابتدای راه‌اندازی کش می‌شود) جلوگیری کنند.

## راهنمای مهاجرت

برای انجام یک مهاجرت سریع در پلاگین‌های موجود، آرگومان `options.ssr` را با `this.environment.config.consumer === 'server'` در هوک‌های `resolveId`، `load` و `transform` جایگزین کنید:

```ts
import { Plugin } from 'vite'

export function myPlugin(): Plugin {
  return {
    name: 'my-plugin',
    resolveId(id, importer, options) {
      const isSSR = options.ssr // [!code --]
      const isSSR = this.environment.config.consumer === 'server' // [!code ++]

      if (isSSR) {
        // منطق خاص SSR
      } else {
        // منطق خاص Client
      }
    },
  }
}
```

برای یک پیاده‌سازی پایدارتر در بلندمدت، هوک پلاگین باید به جای تکیه بر نام محیط، به‌طور دقیق برای [چندین محیط](/guide/api-environment-plugins.html#accessing-the-current-environment-in-hooks)  از گزینه‌های محیطی ریزدانه استفاده کند.

---

---
url: /guide/api-hmr.md
---
# API HMR

:::tip نکته
این API مربوط به سمت کلاینت برای HMR است. برای مدیریت به‌روزرسانی‌های HMR در پلاگین‌ها، [handleHotUpdate](./api-plugin#handlehotupdate) را ببینید.

API دستی HMR عمدتاً برای توسعه‌دهندگان فریمورک‌ها و ابزارها طراحی شده است. به عنوان کاربر نهایی، احتمالاً HMR از قبل در قالب‌های اولیه خاص فریمورک‌ها برای شما مدیریت شده است.
:::

Vite سپس API دستی HMR خود را از طریق آبجکت ویژه `import.meta.hot` در دسترس قرار می‌دهد:

```ts
import type { ModuleNamespace } from 'vite/types/hot.d.ts'
import type {
  CustomEventName,
  InferCustomEventPayload,
} from 'vite/types/customEvent.d.ts'

// ---cut---
interface ImportMeta {
  readonly hot?: ViteHotContext
}

interface ViteHotContext {
  readonly data: any

  accept(): void
  accept(cb: (mod: ModuleNamespace | undefined) => void): void
  accept(dep: string, cb: (mod: ModuleNamespace | undefined) => void): void
  accept(
    deps: readonly string[],
    cb: (mods: Array<ModuleNamespace | undefined>) => void,
  ): void

  dispose(cb: (data: any) => void): void
  prune(cb: (data: any) => void): void
  invalidate(message?: string): void

  on<T extends CustomEventName>(
    event: T,
    cb: (payload: InferCustomEventPayload<T>) => void,
  ): void
  off<T extends CustomEventName>(
    event: T,
    cb: (payload: InferCustomEventPayload<T>) => void,
  ): void
  send<T extends CustomEventName>(
    event: T,
    data?: InferCustomEventPayload<T>,
  ): void
}
```

## شرط لازم برای حفاظت (Conditional Guard)

اول از همه، مطمئن شوید تمام استفاده‌های API HMR را درون یک بلوک شرطی قرار داده‌اید تا کد در محیط تولید (production) حذف شود (tree-shaken):

```js
if (import.meta.hot) {
  // کد مربوط به HMR
}
```

## پشتیبانی از IntelliSense برای TypeScript

Vite تعاریف نوع (type definitions) را برای `import.meta.hot` در [`vite/client.d.ts`](https://github.com/vitejs/vite/blob/main/packages/vite/client.d.ts) ارائه می‌دهد. می‌توانید یک فایل `vite-env.d.ts` در دایرکتوری `src` ایجاد کنید تا TypeScript این تعاریف نوع را تشخیص دهد:

```ts [vite-env.d.ts]
/// <reference types="vite/client" />
```

## `hot.accept(cb)`

برای اینکه یک ماژول به صورت خودکار تغییرات را بپذیرد (self-accept)، از `import.meta.hot.accept` با یک تابع بازگشتی (callback) استفاده کنید که ماژول به‌روزشده را دریافت می‌کند:

```js twoslash
import 'vite/client'
// ---cut---
export const count = 1

if (import.meta.hot) {
  import.meta.hot.accept((newModule) => {
    if (newModule) {
      // وقتی خطای نحوی رخ دهد newModule undefined خواهد بود
      console.log('updated: count is now ', newModule.count)
    }
  })
}
```

یک ماژول که تغییرات داغ را می‌پذیرد به عنوان **مرز HMR** (HMR boundary) در نظر گرفته می‌شود.

HMR در Vite در واقع ماژول واردشده اصلی را جایگزین نمی‌کند: اگر یک ماژول مرز HMR، واردات (imports) را از یک وابستگی (dependency) مجدداً صادر (re-export) کند، مسئول به‌روزرسانی آن صادرات مجدد است (و این صادرات باید با استفاده از `let` تعریف شوند). علاوه بر این، واردکننده‌های (importers) بالادست در زنجیره از ماژول مرز، از تغییر مطلع نخواهند شد. این پیاده‌سازی ساده‌شده HMR برای بیشتر موارد استفاده در محیط توسعه کافی است، در حالی که از کار پرهزینه تولید ماژول‌های پراکسی (proxy) اجتناب می‌کند.

Vite نیاز دارد که فراخوانی این تابع به صورت `import.meta.hot.accept(` (با حساسیت به فاصله‌ها) در کد منبع ظاهر شود تا ماژول بتواند به‌روزرسانی را بپذیرد. این یک نیاز برای تحلیل استاتیکی است که Vite برای فعال کردن پشتیبانی HMR برای یک ماژول انجام می‌دهد.

## `hot.accept(deps, cb)`

یک ماژول همچنین می‌تواند به‌روزرسانی‌ها از وابستگی‌های مستقیم را بدون بارگذاری مجدد خود بپذیرد:

```js twoslash
// @filename: /foo.d.ts
export declare const foo: () => void

// @filename: /example.js
import 'vite/client'
// ---cut---
import { foo } from './foo.js'

foo()

if (import.meta.hot) {
  import.meta.hot.accept('./foo.js', (newFoo) => {
    // تابع بازگشتی ماژول به‌روزشده './foo.js' را دریافت می‌کند
    newFoo?.foo()
  })

  // همچنین می‌تواند آرایه‌ای از ماژول‌های وابستگی را بپذیرد:
  import.meta.hot.accept(
    ['./foo.js', './bar.js'],
    ([newFooModule, newBarModule]) => {
      // تابع بازگشتی آرایه‌ای دریافت می‌کند که فقط ماژول به‌روزشده
      // غیر null است. اگر به‌روزرسانی موفقیت‌آمیز نباشد (مثلاً خطای نحوی)،
      // آرایه خالی خواهد بود
    },
  )
}
```

## `hot.dispose(cb)`

یک ماژول self-accepting یا ماژولی که انتظار دارد توسط دیگران پذیرفته شود، می‌تواند از `hot.dispose` برای پاکسازی اثرات جانبی پایدار ایجادشده توسط نسخه به‌روزشده استفاده کند:

```js twoslash
import 'vite/client'
// ---cut---
function setupSideEffect() {}

setupSideEffect()

if (import.meta.hot) {
  import.meta.hot.dispose((data) => {
    // پاکسازی اثر جانبی
  })
}
```

## `hot.prune(cb)`

یک تابع بازگشتی ثبت کنید که وقتی ماژول دیگر در صفحه import نشود فراخوانی می‌شود. در مقایسه با `hot.dispose`، اگر کد منبع اثرات جانبی را خودش در به‌روزرسانی‌ها پاکسازی می‌کند و فقط نیاز دارید هنگام حذف از صفحه پاکسازی شود، می‌توان از این استفاده کرد. Vite در حال حاضر از این برای واردات `.css` استفاده می‌کند.

```js twoslash
import 'vite/client'
// ---cut---
function setupOrReuseSideEffect() {}

setupOrReuseSideEffect()

if (import.meta.hot) {
  import.meta.hot.prune((data) => {
    // پاکسازی اثر جانبی
  })
}
```

## `hot.data`

شیء `import.meta.hot.data` بین نمونه‌های مختلف یک ماژول به‌روزشده حفظ می‌شود. می‌توان از آن برای انتقال اطلاعات از نسخه قبلی ماژول به نسخه بعدی استفاده کرد.

توجه کنید که انتساب مجدد (re-assignment) خود `data` پشتیبانی نمی‌شود. در عوض، باید خصوصیت‌های شیء `data` را تغییر دهید تا اطلاعات اضافه‌شده از سایر هندلرها حفظ شوند.

```js twoslash
import 'vite/client'
// ---cut---
// صحیح
import.meta.hot.data.someValue = 'hello'

// پشتیبانی نمی‌شود
import.meta.hot.data = { someValue: 'hello' }
```

## `hot.decline()`

این در حال حاضر یک noop است و برای سازگاری با نسخه‌های قبلی وجود دارد. اگر در آینده استفاده جدیدی برای آن ایجاد شود، ممکن است تغییر کند. برای نشان دادن اینکه ماژول قابلیت به‌روزرسانی داغ را ندارد، از `hot.invalidate()` استفاده کنید.

## `hot.invalidate(message?: string)`

یک ماژول self-accepting ممکن است در زمان اجرا متوجه شود که نمی‌تواند یک به‌روزرسانی HMR را مدیریت کند، بنابراین باید به‌روزرسانی به صورت اجباری به واردکننده‌ها (importers) منتقل شود. با فراخوانی `import.meta.hot.invalidate()`، سرور HMR واردکننده‌های فراخواننده را باطل می‌کند، گویی فراخواننده self-accepting نبوده است. این یک پیام هم در کنسول مرورگر و هم در ترمینال ثبت می‌کند. می‌توانید یک پیام برای ارائه زمینه درباره دلیل باطل‌سازی ارسال کنید.

توجه کنید که همیشه باید `import.meta.hot.accept` را فراخوانی کنید حتی اگر قصد دارید بلافاصله `invalidate` را فراخوانی کنید، در غیر این صورت کلاینت HMR به تغییرات آینده ماژول self-accepting گوش نخواهد داد. برای انتقال واضح هدف خود، توصیه می‌کنیم `invalidate` را درون تابع بازگشتی `accept` مانند زیر فراخوانی کنید:

```js twoslash
import 'vite/client'
// ---cut---
import.meta.hot.accept((module) => {
  // می‌توانید از نمونه جدید ماژول برای تصمیم‌گیری درباره باطل‌سازی استفاده کنید.
  if (cannotHandleUpdate(module)) {
    import.meta.hot.invalidate()
  }
})
```

## `hot.on(event, cb)`

به یک رویداد HMR گوش دهد.

رویدادهای HMR زیر به صورت خودکار توسط Vite ارسال می‌شوند:

* `'vite:beforeUpdate'` وقتی یک به‌روزرسانی در حال اعمال است (مثلاً یک ماژول جایگزین می‌شود)
* `'vite:afterUpdate'` وقتی یک به‌روزرسانی اعمال شده است (مثلاً یک ماژول جایگزین شده است)
* `'vite:beforeFullReload'` وقتی یک بارگذاری کامل در حال رخ دادن است
* `'vite:beforePrune'` وقتی ماژول‌هایی که دیگر نیاز نیستند در حال حذف هستند
* `'vite:invalidate'` وقتی یک ماژول با `import.meta.hot.invalidate()` باطل می‌شود
* `'vite:error'` وقتی خطایی رخ می‌دهد (مثلاً خطای نحوی)
* `'vite:ws:disconnect'` وقتی اتصال WebSocket قطع می‌شود
* `'vite:ws:connect'` وقتی اتصال WebSocket (دوباره) برقرار می‌شود

رویدادهای سفارشی HMR نیز می‌توانند از طریق پلاگین‌ها ارسال شوند. برای جزئیات بیشتر [handleHotUpdate](./api-plugin#handlehotupdate) را ببینید.

## `hot.off(event, cb)`

حذف تابع بازگشتی از شنودگرهای رویداد.

## `hot.send(event, data)`

ارسال رویدادهای سفارشی به سرور توسعه Vite.

اگر قبل از اتصال فراخوانی شود، داده‌ها بافر شده و پس از برقراری اتصال ارسال می‌شوند.

برای اطلاعات بیشتر، [ارتباط کلاینت-سرور](/guide/api-plugin.html#client-server-communication) را ببینید، شامل بخشی درباره [تایپ رویدادهای سفارشی](/guide/api-plugin.html#typescript-for-custom-events).

## مطالعه بیشتر

اگر می‌خواهید بیشتر درباره نحوه استفاده از API HMR و نحوه کار آن در عمق یاد بگیرید، این منابع را بررسی کنید:

* [Hot Module Replacement is Easy](https://bjornlu.com/blog/hot-module-replacement-is-easy)

---

---
url: /guide/api-plugin.md
---
# API پلاگین

پلاگین‌های Vite بر پایه‌ی رابط پلاگین‌های Rollup ساخته شده‌اند و چند گزینه‌ی اضافی مخصوص Vite را ارائه می‌کنند. به همین دلیل، می‌توانید یک پلاگین Vite بنویسید که هم در محیط توسعه و هم در زمان Build قابل استفاده باشد.

**پیشنهاد می‌شود قبل از مطالعه این بخش به مستندات [RollUp's plugin](https://rollupjs.org/plugin-development/) مراجعه کنید.**

## ساخت یک پلاگین

Vite الگوهای از پیش تعریف‌ شده‌ای را ارائه می‌دهد، پس قبل از ساخت یک پلاگین جدید، حتماً [راهنمای ویژگی‌ها](https://vite.dev/guide/features) را بررسی کنید تا ببینید آیا نیاز شما قبلاً پوشش داده شده است یا خیر. همچنین، پلاگین‌هایی موجود در جامعه‌ی توسعه‌دهندگان را بررسی کنید؛ [پلاگین‌های سازگار با Rollup](https://github.com/rollup/awesome) و [پلاگین‌های مخصوص Vite](https://github.com/vitejs/awesome-vite#plugins).

هنگام ایجاد یک پلاگین، می‌توانید آن را مستقیماً در فایل `vite.config.js` خود تعریف کنید. نیازی به ایجاد یک پکیج جداگانه نیست. اما اگر می‌خواهید که از پلاگین خود در پروژه‌های مختلف استفاده شود، می‌توانید آن را به اشتراک بگذارید تا به [دیگر توسعه‌دهندگان](https://chat.vite.dev) کمک کنید.

::: tip نکته
هنگام یادگیری، دیباگ کردن یا ساخت پلاگین‌ها، توصیه می‌کنیم از [vite-plugin-inspect](https://github.com/antfu/vite-plugin-inspect) در پروژه‌ی خود استفاده کنید. این پلاگین به شما امکان مشاهده وضعیت پلاگین‌های Vite را می‌دهد. پس از نصب، می‌توانید با مراجعه به `localhost:5173/__inspect/‎` ماژول‌ها و فرآیند تغییرات پروژه‌ی خود را بررسی کنید. برای اطلاعات بیشتر، به [مستندات vite-plugin-inspect](https://github.com/antfu/vite-plugin-inspect) مراجعه کنید.
![vite-plugin-inspect](/assets/vite-plugin-inspect.y9xM77K_.png)
:::

## قراردادها

اگر پلاگین شما از هوک‌های اختصاصی Vite استفاده نمی‌کند می‌تواند به‌عنوان یک [پلاگین سازگار با Rollup](#سازگاری-با-پلاگینهای-rollup) پیاده‌ سازی شود، توصیه می‌شود از [قراردادهای نام‌گذاری پلاگین‌های Rollup](https://rollupjs.org/plugin-development/#conventions) پیروی کنید.

* نام پلاگین باید واضح باشد و با پیشوند `-rollup-plugin` شروع شود.
* در فایل `package.json`، کلمات کلیدی `rollup-plugin` و `vite-plugin` را اضافه کنید.

این کار باعث می‌شود پلاگین شما نه‌تنها در Vite، بلکه در Rollup خالص یا پروژه‌های مبتنی بر WMR نیز قابل استفاده باشد.

برای پلاگین‌های اختصاصی Vite:

* نام پلاگین باید واضح باشد و با پیشوند `-vite-plugin` شروع شود.
* در فایل package.json، کلیدواژه‌ی `vite-plugin` را اضافه کنید.
* در مستندات پلاگین توضیح دهید که چرا این پلاگین فقط مخصوص Vite است (مثلاً اگر از هوک‌های مخصوص Vite استفاده می‌کند).

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

* `-vite-plugin-vue` برای پلاگین‌های Vue
* `-vite-plugin-react` برای پلاگین‌های React
* `-vite-plugin-svelte` برای پلاگین‌های Svelte

برای اطلاعات بیشتر، به بخش [قراردادهای ماژول‌های مجازی](#قرارداد-ماژولهای-مجازی) مراجعه کنید.

## تنظیمات پلاگین‌ها

پلاگین‌ها به `devDependencies` پروژه اضافه می‌شود و از طریق آرایه‌ی `plugins` پیکربندی می‌شود.

```js [vite.config.js]
import vitePlugin from 'vite-plugin-feature'
import rollupPlugin from 'rollup-plugin-feature'

export default defineConfig({
  plugins: [vitePlugin(), rollupPlugin()],
})
```

پلاگین‌های Falsy نادیده گرفته می‌شوند، بنابراین می‌توان از این ویژگی برای فعال یا غیرفعال کردن پلاگین‌ها استفاده کرد.

آرایه‌ی `plugins` از پیش‌تنظیم‌ها پشتیبانی می‌کند که شامل چندین پلاگین در یک عنصر واحد هستند. این ویژگی برای قابلیت‌های پیچیده (مانند یکپارچه‌سازی با فریمورک‌ها) که از چند پلاگین تشکیل شده‌اند، مفید است. این آرایه به‌صورت داخلی تبدیل به یک لیست مسطح (Flattened) خواهد شد.

```js
// framework-plugin
import frameworkRefresh from 'vite-plugin-framework-refresh'
import frameworkDevtools from 'vite-plugin-framework-devtools'

export default function framework(config) {
  return [frameworkRefresh(config), frameworkDevTools(config)]
}
```

```js [vite.config.js]
import { defineConfig } from 'vite'
import framework from 'vite-plugin-framework'

export default defineConfig({
  plugins: [framework()],
})
```

## مثال های ساده

:::tip نکته
طبق یک قرارداد رایج، پلاگین‌های Vite/Rollup به‌صورت تابع کارخانه‌ای (Factory Function) نوشته می‌شوند که پلاگین را به صورت یک آبجکت بازمی‌گرداند. این تابع می‌تواند گزینه‌هایی (Options) را بپذیرد که به کاربران اجازه می‌دهد پلاگین را سفارشی‌سازی کنند.
:::

### تبدیل انواع فایل‌های سفارشی

```js
const fileRegex = /\.(my-file-ext)$/

export default function myPlugin() {
  return {
    name: 'transform-file',

    transform(src, id) {
      if (fileRegex.test(id)) {
        return {
          code: compileFileToJS(src),
          map: null, // provide source map if available
        }
      }
    },
  }
}
```

### استفاده از یک فایل مجازی

مثال‌ها را در [بخش بعدی](#قرارداد-ماژولهای-مجازی) ببینید.

## قرارداد ماژول‌های مجازی

ماژول‌های مجازی یک روش کاربردی هستند که به شما امکان می‌دهند اطلاعات مربوط به زمان ساخت (build time) را با استفاده از سینتکس معمولی ایمپورت ESM به فایل‌های سورس منتقل کنید.

```js
export default function myPlugin() {
  const virtualModuleId = 'virtual:my-module'
  const resolvedVirtualModuleId = '\0' + virtualModuleId

  return {
    name: 'my-plugin', // required, will show up in warnings and errors
    resolveId(id) {
      if (id === virtualModuleId) {
        return resolvedVirtualModuleId
      }
    },
    load(id) {
      if (id === resolvedVirtualModuleId) {
        return `export const msg = "from virtual module"`
      }
    },
  }
}
```

که این امکان را فراهم می‌کند تا ماژول را در جاوااسکریپت ایمپورت کنید:

```js
import { msg } from 'virtual:my-module'

console.log(msg)
```

ماژول‌های مجازی در Vite (و Rollup) به‌طور قراردادی با پیشوند `virtual` شروع می‌شوند: برای مسیرهای قابل مشاهده توسط کاربر آغاز می‌شوند. اگر ممکن باشد، باید از نام پلاگین به‌عنوان یک فضای نام برای جلوگیری از تداخل با پلاگین‌های دیگر در اکوسیستم استفاده کرد. به‌عنوان مثال، یک `vite-plugin-posts` ممکن است از کاربران بخواهد که `virtual:posts` یا `virtual:posts/helpers` را به‌عنوان ماژول‌های مجازی وارد کنند تا اطلاعات زمان ساخت را دریافت کنند. از نظر داخلی، پلاگین‌هایی که از ماژول‌های مجازی استفاده می‌کنند باید شناسه ماژول را هنگام حل کردن، با پیشوند `‎\0` علامت‌گذاری کنند. این یک قرارداد از اکوسیستم Rollup است که از پردازش شناسه توسط سایر پلاگین‌ها (مانند Node resolution) جلوگیری می‌کند. همچنین ویژگی‌های اصلی مانند sourcemaps می‌توانند از این اطلاعات برای تمایز میان ماژول‌های مجازی و فایل‌های معمولی استفاده کنند. `‎\0`به‌عنوان یک کاراکتر مجاز در آدرس‌های ایمپورت شناخته نمی‌شود، بنابراین هنگام تجزیه و تحلیل ایمپورت باید آن را جایگزین کنیم. شناسه ماژول مجازی با `‎\0{id}` در نهایت در توسعه در مرورگر به صورت `‎/@id/__x00__{id}` کدگذاری می‌شود. این شناسه قبل از وارد شدن به پایپ‌لاین پلاگین‌ها مجدداً رمزگشایی می‌شود، بنابراین این مورد توسط کدهای هوک پلاگین‌ها دیده نمی‌شود.

توجه داشته باشید که ماژول‌هایی که به‌طور مستقیم از یک فایل واقعی مشتق شده‌اند، مانند ماژول اسکریپت در یک کامپوننت تک‌ فایلی (مانند فایل‌های ‎.vue یا ‎.svelte)، نیازی به پیروی از این قرارداد ندارند. کامپوننت‌های تک‌فایلی معمولاً مجموعه‌ای از زیرماژول‌ها را هنگام پردازش تولید می‌کنند، اما کد در این ماژول‌ها می‌تواند به سیستم فایل بازگردانده شود. استفاده از `‎\0` برای این زیرماژول‌ها باعث می‌شود که sourcemaps به‌درستی کار نکند.

## هوک‌های عمومی

در زمان توسعه، سرور توسعه Vite یک کانتینر پلاگین ایجاد می‌کند که [هوک‌های ساخت Rollup](https://rollupjs.org/plugin-development/#build-hooks) را به همان شیوه‌ای که Rollup انجام می‌دهد، فراخوانی می‌کند.

هوک‌های زیر یک‌بار در زمان شروع سرور فراخوانی می‌شوند:

* [`options`](https://rollupjs.org/plugin-development/#options)
* [`buildStart`](https://rollupjs.org/plugin-development/#buildstart)

هوک‌های زیر برای هر درخواست ماژول فراخوانی می‌شوند:

* [`resolveId`](https://rollupjs.org/plugin-development/#resolveid)
* [`load`](https://rollupjs.org/plugin-development/#load)
* [`transform`](https://rollupjs.org/plugin-development/#transform)

این هوک‌ها همچنین دارای پارامتر `options` گسترش‌یافته‌ای هستند که شامل ویژگی‌های خاص Vite می‌شود. برای اطلاعات بیشتر می‌توانید به [مستندات SSR](/guide/ssr#ssr-specific-plugin-logic) مراجعه کنید.

برخی از فراخوانی‌های `resolveId` ممکن است مقدار `importer` را به‌صورت یک مسیر مطلق برای یک فایل کلی `index.html` در ریشه دریافت کنند. این به این دلیل است که به دلیل الگوی سرور توسعه بدون باندل Vite، همیشه امکان تعیین دقیق ایمپورت‌‌کننده (importer) وجود ندارد. با این حال، برای ایمپورت‌هایی که در مسیر حل وابستگی‌های Vite پردازش می‌شوند، ایمپورت‌‌کننده را می‌توان در مرحله‌ی تحلیل ایمپورت‌ها ردیابی کرد و مقدار صحیح `importer` را ارائه داد.

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

* [`buildEnd`](https://rollupjs.org/plugin-development/#buildend)
* [`closeBundle`](https://rollupjs.org/plugin-development/#closebundle)

توجه داشته باشید که هوک [`moduleParsed`](https://rollupjs.org/plugin-development/#moduleparsed) در زمان توسعه **فراخوانی نمی‌شود**، زیرا Vite برای بهبود عملکرد از تجزیه کامل AST اجتناب می‌کند.

هوک‌های تولید خروجی [Output Generation Hooks](https://rollupjs.org/plugin-development/#output-generation-hooks) (به‌جز `closeBundle`) در زمان توسعه **فراخوانی نمی‌شوند**. شما می‌توانید سرور توسعه Vite را به‌عنوان فراخوانی فقط `rollup.rollup()‎` بدون فراخوانی `bundle.generate()‎` در نظر بگیرید.

## هوک های مخصوص Vite

پلاگین‌های Vite می‌توانند هوک‌هایی ارائه دهند که مخصوص Vite هستند. این هوک‌ها توسط Rollup نادیده گرفته می‌شوند.

### `config`

* **تایپ:** `‎(config: UserConfig, env: { mode: string, command: string }) => UserConfig | null | void`
* **نوع اجرا:** `async`, `sequential`

  این هوک به شما امکان می‌دهد قبل از اینکه پیکربندی Vite نهایی شود، آن را تغییر دهید. این هوک پیکربندی اولیه کاربر (ترکیب گزینه‌های خط فرمان و فایل پیکربندی) و همچنین محیط جاری پیکربندی را دریافت می‌کند که شامل `mode` و `command` است. می‌تواند یک آبجکت پیکربندی جزئی را بازگرداند که در پیکربندی موجود ادغام می‌شود، یا می‌تواند مستقیماً پیکربندی را تغییر دهد (اگر ادغام پیش‌فرض نتیجه مطلوب را ارائه ندهد).

  **مثال:**

  ```js
  // return partial config (recommended)
  const partialConfigPlugin = () => ({
    name: 'return-partial',
    config: () => ({
      resolve: {
        alias: {
          foo: 'bar',
        },
      },
    }),
  })

  // mutate the config directly (use only when merging doesn't work)
  const mutateConfigPlugin = () => ({
    name: 'mutate-config',
    config(config, { command }) {
      if (command === 'build') {
        config.root = 'foo'
      }
    },
  })
  ```

  ::: warning نکته
  پلاگین‌های کاربر قبل از اجرای این هوک پردازش می‌شوند، بنابراین اضافه کردن پلاگین‌های دیگر داخل هوک `config` تأثیری نخواهد داشت.
  :::

### `configResolved`

* **تایپ:** `‎(config: ResolvedConfig) => void | Promise<void>‎`
* **نوع اجرا:** `async`, `parallel`

  این هوک بعد از نهایی شدن تنظیمات Vite اجرا می‌شود. از این هوک برای خواندن و ذخیره تنظیمات نهایی استفاده کنید. همچنین زمانی مفید است که پلاگین نیاز دارد بر اساس دستوری که اجرا شده رفتار متفاوتی داشته باشد.

  **مثال:**

  ```js
  const examplePlugin = () => {
    let config

    return {
      name: 'read-config',

      configResolved(resolvedConfig) {
        // store the resolved config
        config = resolvedConfig
      },

      // use stored config in other hooks
      transform(code, id) {
        if (config.command === 'serve') {
          // dev: plugin invoked by dev server
        } else {
          // build: plugin invoked by Rollup
        }
      },
    }
  }
  ```

  در نظر داشته باشید که مقدار `command` در حالت توسعه (dev) معادل `serve` است (در cli، دستورات `vite`، `vite dev` و `vite serve` معادل هم هستند).

### `configureServer`

* **تایپ:** `‎(server: ViteDevServer) => (() => void) | void | Promise<(() => void) | void>‎`
* **نوع اجرا:** `async`, `sequential`
* **همچنین ببینید:** [ViteDevServer](./api-javascript#vitedevserver)

  این هوک برای پیکربندی سرور توسعه استفاده می‌شود. رایج‌ترین کاربرد آن افزودن میان‌افزارهای (middlewares) سفارشی به برنامه داخلی [connect](https://github.com/senchalabs/connect) است:

  ```js
  const myPlugin = () => ({
    name: 'configure-server',
    configureServer(server) {
      server.middlewares.use((req, res, next) => {
        // custom handle request...
      })
    },
  })
  ```

  **افزودن میان‌افزار**

  هوک `configureServer` قبل از نصب میان‌افزارهای داخلی اجرا می‌شود، بنابراین میان‌افزارهای سفارشی به‌صورت پیش‌فرض قبل از میان‌افزارهای داخلی اجرا خواهند شد. اگر بخواهید یک میان‌افزار را **بعد از** میان‌افزارهای داخلی اضافه کنید، می‌توانید یک تابع از `configureServer` بازگردانید. این تابع پس از نصب میان‌افزارهای داخلی فراخوانی خواهد شد:

  ```js
  const myPlugin = () => ({
    name: 'configure-server',
    configureServer(server) {
      // return a post hook that is called after internal middlewares are
      // installed
      return () => {
        server.middlewares.use((req, res, next) => {
          // custom handle request...
        })
      }
    },
  })
  ```

  **ذخیره دسترسی به سرور**

  در برخی موارد، سایر هوک‌های پلاگین ممکن است به نمونه سرور توسعه دسترسی داشته باشند (مثلاً برای دسترسی به سرور web socket، پایشگر سیستم فایل، یا گراف ماژول‌ها). این هوک می‌تواند برای ذخیره نمونه سرور و استفاده از آن در سایر هوک‌ها نیز استفاده شود:

  ```js
  const myPlugin = () => {
    let server
    return {
      name: 'configure-server',
      configureServer(_server) {
        server = _server
      },
      transform(code, id) {
        if (server) {
          // use server...
        }
      },
    }
  }
  ```

  توجه داشته باشید که `configureServer` هنگام اجرای نسخه نهایی فراخوانی نمی‌شود، بنابراین سایر هوک‌های شما باید مراقب نبود آن باشند.

### `configurePreviewServer`

* **تایپ:** `‎(server: PreviewServer) => (() => void) | void | Promise<(() => void) | void>‎`
* **نوع اجرا:** `async`, `sequential`
* **همچنین ببینید:** [PreviewServer](./api-javascript#previewserver)

  این هوک مشابه [`configureServer`](/guide/api-plugin.html#configureserver) است اما برای سرور پیش‌نمایش (preview server) استفاده می‌شود. درست مانند `configureServer`، این هوک قبل از نصب سایر میان‌افزارها اجرا می‌شود. اگر می‌خواهید یک میان‌افزار را بعد از سایر میان‌افزارها اضافه کنید، می‌توانید یک تابع از `configurePreviewServer` برگردانید که بعد از نصب میان‌افزارهای داخلی فراخوانی خواهد شد:

  ```js
  const myPlugin = () => ({
    name: 'configure-preview-server',
    configurePreviewServer(server) {
      // return a post hook that is called after other middlewares are
      // installed
      return () => {
        server.middlewares.use((req, res, next) => {
          // custom handle request...
        })
      }
    },
  })
  ```

### `transformIndexHtml`

* **تایپ:** `IndexHtmlTransformHook | { order?: 'pre' | 'post', handler: IndexHtmlTransformHook }‎`
* **نوع اجرا:** `async`, `sequential`

  این هوک برای تغییر و پردازش فایل‌های HTML مانند `index.html` در نظر گرفته شده است. این هوک مقدار HTML فعلی و یک context transform را دریافت می‌کند. Context transform در حالت dev شامل نمونه‌ای از [`ViteDevServer`](./api-javascript#vitedevserver) است و در حالت build شامل بسته خروجی Rollup می‌شود.

  این هوک می‌تواند async باشد و یکی از موارد زیر را برگرداند:

  * رشته HTML تغییر یافته
  * یک آرایه از اشیای توصیف‌کننده (`{tag, attr, children}`) که به HTML موجود اضافه شوند. (هر تگ می‌تواند مشخص کند که در کجای صفحه قرار بگیرد، پیش‌فرض: ابتدای `<head>` قرار می‌گیرد.)
  * یک آبجکت شامل هر دو مورد فوق به صورت `{ html, tags }`

به‌طور پیش‌فرض مقدار `order` روی `undefined` تنظیم شده است، به این معنا که این هوک بعد از پردازش HTML اجرا می‌شود.اگر بخواهید یک اسکریپت را به HTML اضافه کنید و این اسکریپت از پردازش پلاگین‌های Vite عبور کند، باید `order: 'pre'‎` را تنظیم کنید. و اگر بخواهید هوک شما بعد از همه‌ی هوک‌هایی که مقدار `order` آن‌ها undefined است اجرا شود، `order: 'post'‎` را تنظیم کنید.

**مثال:**

```js
const htmlPlugin = () => {
  return {
    name: 'html-transform',
    transformIndexHtml(html) {
      return html.replace(
        /<title>(.*?)<\/title>/,
        `<title>Title replaced!</title>`,
      )
    },
  }
}
```

**امضاء کامل هوک:**

```ts
type IndexHtmlTransformHook = (
  html: string,
  ctx: {
    path: string
    filename: string
    server?: ViteDevServer
    bundle?: import('rollup').OutputBundle
    chunk?: import('rollup').OutputChunk
  },
) =>
  | IndexHtmlTransformResult
  | void
  | Promise<IndexHtmlTransformResult | void>

type IndexHtmlTransformResult =
  | string
  | HtmlTagDescriptor[]
  | {
      html: string
      tags: HtmlTagDescriptor[]
    }

interface HtmlTagDescriptor {
  tag: string
  attrs?: Record<string, string | boolean>
  children?: string | HtmlTagDescriptor[]
  /**
   * default: 'head-prepend'
   */
  injectTo?: 'head' | 'body' | 'head-prepend' | 'body-prepend'
}
```

::: warning نکته
این هوک در صورتی فراخوانی نخواهد شد که از فریم‌ورکی استفاده کنید که مدیریت سفارشی فایل‌های ورودی را انجام می‌دهد (برای مثال [SvelteKit](https://github.com/sveltejs/kit/discussions/8269#discussioncomment-4509145)).
:::

### `handleHotUpdate`

* **تایپ:** `‎(ctx: HmrContext) => Array<ModuleNode> | void | Promise<Array<ModuleNode> | void>‎`
* **همچنین ببینید:** [HMR API](./api-hmr)

  این هوک برای انجام مدیریت سفارشی بروزرسانی HMR (Hot Module Replacement) استفاده می‌شود. این هوک یک آبجکت کانتکست دریافت می‌کند که دارای امضای زیر است:

  ```ts
  interface HmrContext {
    file: string
    timestamp: number
    modules: Array<ModuleNode>
    read: () => string | Promise<string>
    server: ViteDevServer
  }
  ```

  * `modules`: آرایه‌ای از ماژول‌ها است که تحت تأثیر فایل تغییر یافته قرار گرفته‌اند. آرایه است زیرا یک فایل ممکن است به چندین ماژول سرو شده مربوط باشد (مثل SFC‌های Vue).

  * `read`: یک تابع خواندن غیرهمزمان است که محتوای فایل را باز می‌گرداند. این تابع فراهم شده است زیرا در برخی سیستم‌ها، callback تغییر فایل ممکن است خیلی سریع اجرا شود پیش از اینکه ویرایشگر فایل را به‌طور کامل به‌روزرسانی کند و فراخوانی مستقیم `fs.readFile` ممکن است محتوای خالی برگرداند. تابع read این رفتار را نرمال می‌کند.

  هوک می‌تواند تصمیم بگیرد که:

  * لیست ماژول‌های تحت تأثیر را فیلتر کرده و دقیق‌تر کند تا HMR (Hot Module Replacement) دقیق‌تر باشد.

  * یک آرایه خالی برگرداند و یک بار بارگذاری کامل انجام دهد:

    ```js
    handleHotUpdate({ server, modules, timestamp }) {
      // Invalidate modules manually
      const invalidatedModules = new Set()
      for (const mod of modules) {
        server.moduleGraph.invalidateModule(
          mod,
          invalidatedModules,
          timestamp,
          true
        )
      }
      server.ws.send({ type: 'full-reload' })
      return []
    }
    ```

  * یک آرایه خالی برگرداند و انجام مدیریت کامل HMR سفارشی را با ارسال رویدادهای سفارشی به کلاینت انجام دهد:

    ```js
    handleHotUpdate({ server }) {
      server.ws.send({
        type: 'custom',
        event: 'special-update',
        data: {}
      })
      return []
    }
    ```

  کد کلاینت باید هندلر مربوطه را با استفاده از [API HMR](./api-hmr) ثبت کند (این می‌تواند از طریق هوک transform همان پلاگین اضافه شود):

  ```js
  if (import.meta.hot) {
    import.meta.hot.on('special-update', (data) => {
      // perform custom update
    })
  }
  ```

## ترتیب اجرای پلاگین‌ها در Vite

یک پلاگین در Vite می‌تواند ویژگی `enforce` را مشخص کند (مشابه لودرهای Webpack) تا ترتیب اجرای آن را تنظیم کند. مقدار `enforce` می‌تواند `"pre"` یا `"post"`باشد. ترتیب اجرای پلاگین‌ها پس از پردازش به شکل زیر خواهد بود:

* Alias
* پلاگین‌های کاربر با `enforce: 'pre'‎`
* پلاگین‌های هسته‌ای Vite
* پلاگین‌های کاربر بدون مقدار `enforce`
* پلاگین‌های مربوط به ساخت (build) در Vite
* پلاگین‌های کاربر با `enforce: 'post'‎`
* پلاگین‌های پس از ساخت Vite (مانند minify، manifest، گزارش‌گیری)

توجه داشته باشید که این ترتیب جدا از ترتیب اجرای هوک‌ها است، زیرا هوک‌ها همچنان مطابق با مقدار `order` خود در [Rollup](https://rollupjs.org/plugin-development/#build-hooks) پردازش می‌شوند.

## برنامه های شرطی

به‌طور پیش‌فرض، پلاگین‌ها هم در حالت توسعه (serve) و هم در حالت بیلد (build) اجرا می‌شوند. اما اگر پلاگین‌ای فقط در یکی از این دو حالت موردنیاز باشد، می‌توان از ویژگی `apply` برای مشخص کردن اینکه پلاگین فقط در `'build'` یا `'serve'` اجرا شود:

```js
function myPlugin() {
  return {
    name: 'build-only',
    apply: 'build', // or 'serve'
  }
}
```

همچنین می‌توان از یک تابع برای کنترل دقیق‌تر استفاده کرد:

```js
apply(config, { command }) {
  // apply only on build but not for SSR
  return command === 'build' && !config.build.ssr
}
```

## سازگاری با پلاگین‌های Rollup

تعداد قابل توجهی از پلاگین‌های Rollup مستقیماً به عنوان پلاگین Vite کار می‌کنند (مثلاً `‎@rollup/plugin-alias` یا `‎@rollup/plugin-json`) اما نه همه آن‌ها، زیرا برخی از هوک‌های پلاگین در یک سرور توسعه بدون باندل معنایی ندارند.

به طور کلی، اگر یک پلاگین Rollup دارای شرایط زیر باشد، باید بدون مشکل به عنوان پلاگین Vite کار کند:

* از هوک [`moduleParsed`](https://rollupjs.org/plugin-development/#moduleparsed) استفاده نمی‌کند.
* وابستگی زیاد بین هوک‌های مربوط به فاز باندل و فاز خروجی ندارد.

اگر یک پلاگین Rollup فقط برای مرحله ساخت (build) مناسب باشد، می‌توان آن را در `build.rollupOptions.plugins` مشخص کرد. این کار همان عملکردی را خواهد داشت که یک پلاگین Vite با `enforce: 'post'‎` و `apply: 'build'‎` دارد.

همچنین می‌توان یک پلاگین Rollup موجود را با ویژگی‌های مخصوص Vite تقویت کرد:

```js [vite.config.js]
import example from 'rollup-plugin-example'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    {
      ...example(),
      enforce: 'post',
      apply: 'build',
    },
  ],
})
```

## نرمال‌سازی مسیرها

Vite در هنگام حل شناسه‌ها مسیرها را نرمال‌سازی می‌کند تا از جداکننده‌های POSIX ( / ) استفاده کند، در حالی که در ویندوز، حجم درایو را حفظ می‌کند. از طرف دیگر، Rollup به‌طور پیش‌فرض مسیرهای حل‌شده را دست‌نخورده نگه می‌دارد، بنابراین شناسه‌های حل‌شده در ویندوز از جداکننده‌های ( \ ) win32 استفاده می‌کنند. با این حال، پلاگین‌های Rollup به‌صورت داخلی از [تابع کمکی `normalizePath`](https://github.com/rollup/plugins/tree/master/packages/pluginutils#normalizepath) از `‎@rollup/pluginutils` استفاده می‌کنند، که جداکننده‌ها را قبل از انجام مقایسه‌ها به فرمت POSIX تبدیل می‌کند. این بدان معناست که هنگام استفاده از این پلاگین‌ها در Vite، مقادیر `include` و `exclude` در الگوهای پیکربندی و سایر مسیرهای مشابه در مقایسه با شناسه‌های حل‌شده به‌درستی کار می‌کنند.

بنابراین، برای پلاگین‌های Vite، هنگام مقایسه مسیرها با شناسه‌های حل‌شده، مهم است که ابتدا مسیرها را نرمال‌سازی کرده و از جداکننده‌های POSIX (`/`) استفاده کنید. یک تابع کمکی معادل normalizePath نیز از ماژول vite صادر شده است.

```js
import { normalizePath } from 'vite'

normalizePath('foo\\bar') // 'foo/bar'
normalizePath('foo/bar') // 'foo/bar'
```

## فیلتر کردن، الگوی include/exclude

Vite تابع [`createFilter` از بسته ‎`@rollup/pluginutils`](https://github.com/rollup/plugins/tree/master/packages/pluginutils#createfilter) را در دسترس قرار می‌دهد تا پلاگین‌ها و یکپارچه‌سازی‌های مخصوص Vite از الگوی استاندارد فیلتر کردن include/exclude استفاده کنند. این الگو در خود هسته Vite نیز به کار می‌رود.

## ارتباط کلاینت-سرور

از نسخه 2.9، Vite ابزارهایی را برای پلاگین‌ها فراهم می‌کند تا به ارتباط با کلاینت‌ها کمک کنند.

### سرور به کلاینت

در سمت پلاگین، می‌توان از `server.ws.send` برای ارسال رویدادها به کلاینت استفاده کرد:

```js [vite.config.js]
export default defineConfig({
  plugins: [
    {
      // ...
      configureServer(server) {
        server.ws.on('connection', () => {
          server.ws.send('my:greetings', { msg: 'hello' })
        })
      },
    },
  ],
})
```

::: tip نکته
توصیه می‌کنیم **همیشه یک پیشوند** به نام رویدادهای خود اضافه کنید تا از تداخل با سایر پلاگین‌ها جلوگیری شود.
:::

در سمت کلاینت، از [`hot.on`](/guide/api-hmr.html#hot-on-event-cb) برای گوش دادن به رویدادها استفاده کنید:

```ts twoslash
import 'vite/client'
// ---cut---
// client side
if (import.meta.hot) {
  import.meta.hot.on('my:greetings', (data) => {
    console.log(data.msg) // hello
  })
}
```

### کلاینت به سرور

برای ارسال رویدادها از کلاینت به سرور، می‌توان از [`hot.send`](/guide/api-hmr.html#hot-send-event-payload) استفاده کرد:

```ts
// client side
if (import.meta.hot) {
  import.meta.hot.send('my:from-client', { msg: 'Hey!' })
}
```

سپس از `server.ws.on` استفاده کنید و به رویدادها در سمت سرور گوش دهید.

```js [vite.config.js]
export default defineConfig({
  plugins: [
    {
      // ...
      configureServer(server) {
        server.ws.on('my:from-client', (data, client) => {
          console.log('Message from client:', data.msg) // Hey!
          // reply only to the client (if needed)
          client.send('my:ack', { msg: 'Hi! I got your message!' })
        })
      },
    },
  ],
})
```

### TypeScript برای رویدادهای سفارشی

به‌صورت داخلی، Vite تایپ payload را از رابط `CustomEventMap` استنتاج می‌کند. می‌توان رویدادهای سفارشی را با گسترش این ساختار گسترش داد:

:::tip نکته
باید هنگام مشخص کردن فایل‌های تعریف ساختار تایپ‌اسکریپت، حتماً پسوند `d.ts.` را اضافه کنید. در غیر این صورت، تایپ‌اسکریپت ممکن است نتواند تشخیص دهد که ساختار فایل چیست.
:::

```ts [events.d.ts]
import 'vite/types/customEvent.d.ts'

declare module 'vite/types/customEvent.d.ts' {
  interface CustomEventMap {
    'custom:foo': { msg: string }
    // 'event-key': payload
  }
}
```

این تعریف ساختار توسط `<InferCustomEventPayload<T` برای استنتاج تایپ داده payload برای رویداد `T` استفاده می‌شود. برای کسب اطلاعات بیشتر در مورد نحوه استفاده از این ساختار، به [مستندات API HMR](./api-hmr#hmr-api) مراجعه کنید.

```ts twoslash
import 'vite/client'
import type { InferCustomEventPayload } from 'vite/types/customEvent.d.ts'
declare module 'vite/types/customEvent.d.ts' {
  interface CustomEventMap {
    'custom:foo': { msg: string }
  }
}
// ---cut---
type CustomFooPayload = InferCustomEventPayload<'custom:foo'>
import.meta.hot?.on('custom:foo', (payload) => {
  // The type of payload will be { msg: string }
})
import.meta.hot?.on('unknown:event', (payload) => {
  // The type of payload will be any
})
```

---

---
url: /guide/api-environment-plugins.md
---
# API محیط برای پلاگین‌ها

:::warning آزمایشی
رابط Environment API هنوز در مرحله‌ی آزمایشی (experimental) هست. با این حال، ما تلاش می‌کنیم بین نسخه‌های اصلی (major) پایداری این APIها را حفظ کنیم تا جامعه‌ی توسعه‌دهندگان بتوانند با آن‌ها کار کرده و تجربیات خود را بر اساس آن‌ها توسعه دهند. ما قصد داریم این APIهای جدید را در یکی از نسخه‌های اصلی آینده به حالت پایدار (stable) برسانیم. البته ممکن است در این فرآیند تغییرات شکننده (breaking changes) نیز اعمال شود، اما این کار زمانی انجام خواهد شد که پروژه‌ها و کتابخانه‌های وابسته فرصت کافی برای آزمایش و ارزیابی این قابلیت‌های جدید را داشته باشند.

منابع:

* [بحث و گفتگو](https://github.com/vitejs/vite/discussions/16358) جایی که ما در حال جمع‌آوری نظرات درباره APIهای جدید هستیم.
* [PR مربوط به Environment API](https://github.com/vitejs/vite/pull/16471) جایی که API جدید پیاده‌سازی و بررسی شده است.

لطفاً نظرات و بازخوردهای خود را با ما به اشتراک بگذارید.
:::

## دسترسی به محیط فعلی در هوک‌ها

از آنجا که تا نسخه Vite 6 فقط دو محیط وجود داشت (`client` و `ssr`)، یک بولین `ssr` برای شناسایی محیط فعلی در APIهای Vite کافی بود. هوک‌های پلاگین یک بولین `ssr` را در آخرین پارامتر گزینه‌ها دریافت می‌کردند و API ها انتظار داشتند که یک پارامتر `ssr` اختیاری برای ارتباط صحیح ماژول‌ها با محیط مناسب ارائه شود (برای مثال `server.moduleGraph.getModuleByUrl(url, { ssr })`).

با معرفی محیط‌های قابل پیکربندی، اکنون یک روش یکنواخت برای دسترسی به گزینه‌ها و نمونه‌های محیط در پلاگین‌ها وجود دارد. هوک‌های پلاگین اکنون `this.environment` را در کانتکست خود ارائه می‌دهند و APIهایی که قبلاً به یک بولین `ssr` نیاز داشتند، اکنون به محیط مناسب محدود شده‌اند (برای مثال `environment.moduleGraph.getModuleByUrl(url)`).

سرور Vite یک مسیر پردازش پلاگین مشترک دارد، اما زمانی که یک ماژول پردازش می‌شود، همیشه در کانتکست یک محیط مشخص انجام می‌شود. نمونه `environment` در کانتکست پلاگین در دسترس است.

یک پلاگین می‌تواند از نمونه `environment` برای تغییر نحوه پردازش یک ماژول بر اساس پیکربندی محیط استفاده کند (که می‌توان از طریق `environment.config` به آن دسترسی داشت).

```ts
  transform(code, id) {
    console.log(this.environment.config.resolve.conditions)
  }
```

## ثبت محیط‌های جدید با استفاده از هوک‌ها

پلاگین‌ها می‌توانند محیط‌های جدیدی را در هوک `config` اضافه کنند (برای مثال، برای داشتن یک گراف ماژول جداگانه برای [RSC](https://react.dev/blog/2023/03/22/react-labs-what-we-have-been-working-on-march-2023#react-server-components)):

```ts
  config(config: UserConfig) {
    config.environments.rsc ??= {}
  }
```

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

## پیکربندی محیط با استفاده از هوک‌ها

در زمان اجرای هوک `config`، لیست کامل محیط‌ها هنوز مشخص نیست و محیط‌ها می‌توانند تحت تأثیر مقادیر پیش‌فرض از تنظیمات محیط در سطح ریشه یا به صورت صریح از طریق رکورد `config.environments` قرار گیرند. پلاگین‌ها باید مقادیر پیش‌فرض را با استفاده از هوک `config` تنظیم کنند.
برای پیکربندی هر محیط، می‌توانند از هوک جدید `configEnvironment` استفاده کنند. این هوک برای هر محیط با تنظیمات جزئی اضافه‌شده آن، شامل مقادیر پیش‌فرض نهایی، فراخوانی می‌شود.

```ts
  configEnvironment(name: string, options: EnvironmentOptions) {
    if (name === 'rsc') {
      options.resolve.conditions = // ...
```

## هوک `hotUpdate`

* **تایپ:** `‎(this: { environment: DevEnvironment }, options: HotUpdateOptions) => Array<EnvironmentModuleNode> | void | Promise<Array<EnvironmentModuleNode> | void>‎`
* **همچنین ببینید:** [HMR API](./api-hmr)

هوک `hotUpdate` به پلاگین‌ها اجازه می‌دهد تا مدیریت به‌روزرسانی HMR سفارشی را برای یک محیط خاص انجام دهند. زمانی که یک فایل تغییر می‌کند، الگوریتم HMR برای هر محیط به ترتیب موجود در `server.environments` به صورت سری اجرا می‌شود، بنابراین هوک `hotUpdate` چندین بار فراخوانی خواهد شد. این هوک یک آبجکت کانتکست با امضای زیر دریافت می‌کند:

```ts
interface HotUpdateOptions {
  type: 'create' | 'update' | 'delete'
  file: string
  timestamp: number
  modules: Array<EnvironmentModuleNode>
  read: () => string | Promise<string>
  server: ViteDevServer
}
```

* `this.environment` محیط اجرایی ماژول است که در آن به‌روزرسانی فایل در حال پردازش است.

* `modules` آرایه‌ای از ماژول‌ها در این محیط است که تحت تأثیر فایل تغییر یافته قرار گرفته‌اند. این آرایه شامل چندین ماژول است، زیرا یک فایل ممکن است به چندین ماژول سرو شده نگاشت شود (مثلاً در Vue SFCها).

* `read` یک تابع خواندن غیرهمزمان است که محتوای فایل را برمی‌گرداند. این تابع ارائه شده است زیرا در برخی سیستم‌ها، ممکن است callback تغییر فایل خیلی سریع اجرا شود، قبل از اینکه ویرایشگر فایل را به‌طور کامل به‌روزرسانی کند، و در این حالت استفاده مستقیم از `fs.readFile` محتوای خالی برمی‌گرداند. تابع `read` این رفتار را نرمال‌سازی می‌کند.

این هوک می‌تواند:

* لیست ماژول‌های تحت تأثیر را فیلتر کرده و محدود کند تا HMR دقیق‌تر انجام شود.

* یک آرایه خالی برگرداند و بارگذاری کامل را انجام دهد:

  ```js
  hotUpdate({ modules, timestamp }) {
    if (this.environment.name !== 'client')
      return

    // Invalidate modules manually
    const invalidatedModules = new Set()
    for (const mod of modules) {
      this.environment.moduleGraph.invalidateModule(
        mod,
        invalidatedModules,
        timestamp,
        true
      )
    }
    this.environment.hot.send({ type: 'full-reload' })
    return []
  }
  ```

* آرایه خالی برگردانید و مدیریت کامل HMR سفارشی را با ارسال رویدادهای سفارشی به کلاینت انجام دهید:

  ```js
  hotUpdate() {
    if (this.environment.name !== 'client')
      return

    this.environment.hot.send({
      type: 'custom',
      event: 'special-update',
      data: {}
    })
    return []
  }
  ```

  کد کلاینت باید با استفاده از [HMR API](./api-hmr) هندلر مربوطه را ثبت کند (این کار می‌تواند توسط هوک `transform` همان پلاگین انجام شود):

  ```js
  if (import.meta.hot) {
    import.meta.hot.on('special-update', (data) => {
      // perform custom update
    })
  }
  ```

## وضعیت وابسته به محیط (Per-environment State) در پلاگین‌ها

از آنجا که یک نمونه‌ی یکسان از پلاگین ممکن است در محیط‌های مختلف (مثلاً کلاینت و SSR) استفاده شود، وضعیت (state) مربوط به پلاگین باید با استفاده از `this.environment` تفکیک شود. این همان الگویی است که پیش‌تر نیز در اکوسیستم استفاده می‌شده؛ یعنی برای نگهداری وضعیت ماژول‌ها به صورت مجزا برای SSR و کلاینت، از مقدار بولی `ssr` به عنوان کلید استفاده می‌شده تا از قاطی شدن وضعیت ماژول‌های SSR و کلاینت جلوگیری شود. در این حالت می‌توان از ساختاری مانند `Map<Environment, State>`‎ برای نگهداری وضعیت مستقل هر محیط استفاده کرد. نکته: برای حفظ سازگاری با نسخه‌های قبلی، متدهای `buildStart` و `buildEnd` به صورت پیش‌فرض فقط برای محیط کلاینت فراخوانی می‌شوند، مگر اینکه گزینه‌ی `perEnvironmentStartEndDuringDev: true` فعال شده باشد.

```js
function PerEnvironmentCountTransformedModulesPlugin() {
  const state = new Map<Environment, { count: number }>()
  return {
    name: 'count-transformed-modules',
    perEnvironmentStartEndDuringDev: true,
    buildStart() {
      state.set(this.environment, { count: 0 })
    },
    transform(id) {
      state.get(this.environment).count++
    },
    buildEnd() {
      console.log(this.environment.name, state.get(this.environment).count)
    }
  }
}
```

## پلاگین‌های مخصوص هر محیط

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

```js
const UnoCssPlugin = () => {
  // مشترک سراسری state
  return {
    buildStart() {
      // WeakMap<Environment, Data> مقداردهی وضعیت مخصوص هر محیط با
      // this.environment با استفاده از
    },
    configureServer() {
      // استفاده از هوک‌های سراسری به صورت معمول
    },
    applyToEnvironment(environment) {
      // برگردانید true اگر این پلاگین باید در این محیط فعال باشد، مقدار
      // یا یک پلاگین جدید برای جایگزینی آن برگردانید
      // اگر این هوک استفاده نشود، پلاگین در همه محیط‌ها فعال خواهد بود
    },
    resolveId(id, importer) {
      // فقط برای محیط‌هایی که این پلاگین در آن‌ها اعمال می‌شود، فراخوانی می‌شود
    },
  }
}
```

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

```js
import { nonShareablePlugin } from 'non-shareable-plugin'

export default defineConfig({
  plugins: [
    {
      name: 'per-environment-plugin',
      applyToEnvironment(environment) {
        return nonShareablePlugin({ outputName: environment.name })
      },
    },
  ],
})
```

Vite یک تابع کمکی به نام `perEnvironmentPlugin` ارائه می‌دهد تا مواردی که نیازی به هوک‌های دیگر ندارند، ساده‌تر کند:

```js
import { nonShareablePlugin } from 'non-shareable-plugin'

export default defineConfig({
  plugins: [
    perEnvironmentPlugin('per-environment-plugin', (environment) =>
      nonShareablePlugin({ outputName: environment.name }),
    ),
  ],
})
```

هوک `applyToEnvironment` در زمان پیکربندی فراخوانی می‌شود، و در حال حاضر بعد از اجرای `configResolved` انجام می‌گیرد. دلیل این ترتیب، وجود پروژه‌هایی در اکوسیستم است که پلاگین‌ها را در این مرحله تغییر می‌دهند. با این حال، ممکن است در آینده فرآیند تشخیص پلاگین‌های محیطی (environment plugins resolution) به قبل از `configResolved` منتقل شود. این تغییر به منظور بهبود ساختار و پیش‌بینی‌پذیری فرایند پیکربندی در نظر گرفته شده است.

## محیط در هوک‌های بیلد

مشابه حالت توسعه، هوک‌های پلاگین در زمان بیلد نیز نمونه محیط را دریافت می‌کنند و جایگزین بولین `ssr` می‌شوند. این موضوع برای هوک‌هایی مانند `renderChunk` ، `generateBundle` و سایر هوک‌های مختص بیلد نیز کار می‌کند.

## پلاگین‌های مشترک در زمان بیلد

قبل از Vite 6، مسیر اجرا پلاگین‌ها در حالت توسعه و بیلد به صورت متفاوت عمل می‌کرد:

* **در زمان توسعه:** پلاگین‌ها مشترک بودند.
* **در زمان بیلد:** پلاگین‌ها برای هر محیط جداگانه بودند (در فرآیندهای مختلف: `vite build` سپس `vite build --ssr`).

این موضوع باعث می‌شد فریم‌ورک‌ها برای به اشتراک‌گذاری وضعیت بین بیلد `client` و بیلد `ssr` از فایل‌های مانیفست نوشته‌شده در فایل سیستم استفاده کنند. در Vite 6، اکنون تمام محیط‌ها در یک فرآیند واحد بیلد می‌شوند، بنابراین مسیر اجرا پلاگین‌ها و ارتباط بین محیط‌ها می‌تواند با حالت توسعه هماهنگ شود.

در یکی از نسخه‌های اصلی آینده، ممکن است به یک هماهنگی کامل برسیم:

* **در هر دو حالت توسعه و بیلد:** پلاگین‌ها مشترک خواهند بود، با [فیلتر کردن مخصوص هر محیط](#پلاگینهای-مخصوص-هر-محیط).

همچنین یک نمونه مشترک از `ResolvedConfig` در زمان بیلد وجود خواهد داشت که امکان کش کردن در سطح کل فرآیند بیلد برنامه را فراهم می‌کند، مشابه کاری که در زمان توسعه با `WeakMap<ResolvedConfig, CachedData>‎` انجام می‌دهیم.

برای Vite 6، ما نیاز داریم یک گام کوچک‌تر برداریم تا سازگاری با نسخه‌های قبلی حفظ شود. پلاگین‌های اکوسیستم در حال حاضر از `config.build` به جای `environment.config.build` برای دسترسی به تنظیمات استفاده می‌کنند، بنابراین به صورت پیش‌فرض باید یک `ResolvedConfig` جدید برای هر محیط ایجاد کنیم. یک پروژه می‌تواند با تنظیم `builder.sharedConfigBuild` روی `true`، به اشتراک‌گذاری کامل تنظیمات و  مسیر اجرا پلاگین‌ها را فعال کند.

این گزینه در ابتدا فقط برای یک زیرمجموعه کوچک از پروژه‌ها کار خواهد کرد، بنابراین نویسندگان پلاگین می‌توانند برای یک پلاگین خاص با تنظیم فلگ `sharedDuringBuild` روی `true`، اشتراک‌گذاری آن را فعال کنند. این امکان به راحتی به اشتراک‌گذاری وضعیت برای پلاگین‌های معمولی را فراهم می‌کند:

```js
function myPlugin() {
  // بین تمام محیط‌ها در حالت توسعه و بیلد state اشتراک‌گذاری

  const sharedState = ...
  return {
    name: 'shared-plugin',
    transform(code, id) { ... },

    // فعال‌سازی یک نمونه مشترک برای تمام محیط‌ها در زمان بیلد
    sharedDuringBuild: true,
  }
}
```

---

---
url: /guide/api-environment-runtimes.md
---
# API محیط برای رانتایم‌ها

:::warning آزمایشی
رابط Environment API هنوز در مرحله‌ی آزمایشی (experimental) هست. با این حال، ما تلاش می‌کنیم بین نسخه‌های اصلی (major) پایداری این APIها را حفظ کنیم تا جامعه‌ی توسعه‌دهندگان بتوانند با آن‌ها کار کرده و تجربیات خود را بر اساس آن‌ها توسعه دهند. ما قصد داریم این APIهای جدید را در یکی از نسخه‌های اصلی آینده به حالت پایدار (stable) برسانیم. البته ممکن است در این فرآیند تغییرات شکننده (breaking changes) نیز اعمال شود، اما این کار زمانی انجام خواهد شد که پروژه‌ها و کتابخانه‌های وابسته فرصت کافی برای آزمایش و ارزیابی این قابلیت‌های جدید را داشته باشند.

منابع:

* [بحث و گفتگو](https://github.com/vitejs/vite/discussions/16358) جایی که ما در حال جمع‌آوری نظرات درباره APIهای جدید هستیم.
* [PR مربوط به Environment API](https://github.com/vitejs/vite/pull/16471) جایی که API جدید پیاده‌سازی و بررسی شده است.

لطفاً نظرات و بازخوردهای خود را با ما به اشتراک بگذارید.
:::

## Environment Factories

سازنده‌های محیط (Environment Factories) قرار است توسط فراهم‌کنندگان رانتایم (مثل Cloudflare) پیاده‌سازی شوند، نه کاربران عادی. این سازنده‌ها در ساده‌ترین حالت، یک `EnvironmentOptions` را برمی‌گردانند که از رانتایم هدف هم برای محیط توسعه و هم بیلد استفاده می‌کند. همچنین می‌توان تنظیمات پیش‌فرض محیط را به‌گونه‌ای تعیین کرد که کاربر نیازی به انجام این کار نداشته باشد.

```ts
function createWorkerdEnvironment(
  userConfig: EnvironmentOptions,
): EnvironmentOptions {
  return mergeConfig(
    {
      resolve: {
        conditions: [
          /*...*/
        ],
      },
      dev: {
        createEnvironment(name, config) {
          return createWorkerdDevEnvironment(name, config, {
            hot: true,
            transport: customHotChannel(),
          })
        },
      },
      build: {
        createEnvironment(name, config) {
          return createWorkerdBuildEnvironment(name, config)
        },
      },
    },
    userConfig,
  )
}
```

سپس می‌توان فایل پیکربندی را به شکل زیر نوشت:

```js
import { createWorkerdEnvironment } from 'vite-environment-workerd'

export default {
  environments: {
    ssr: createWorkerdEnvironment({
      build: {
        outDir: '/dist/ssr',
      },
    }),
    rsc: createWorkerdEnvironment({
      build: {
        outDir: '/dist/rsc',
      },
    }),
  },
}
```

و فریم‌ورک‌ها می‌توانند برای انجام SSR از یک محیط با رانتایم workerd به این شکل استفاده کنند:

```js
const ssrEnvironment = server.environments.ssr
```

## ایجاد یک Environment Factory جدید

سرور توسعه Vite به طور پیش‌فرض دو محیط را ارائه می‌دهد: محیط `client` و محیط `ssr`. محیط کلاینت به طور پیش‌فرض یک محیط مرورگر است، و اجراکننده ماژول آن با ایمپورت کردن ماژول مجازی `‎/@vite/client` در برنامه‌های کلاینت پیاده‌سازی می‌شود. محیط SSR به طور پیش‌فرض در همان رانتایم Node که سرور Vite اجرا می‌شود، اجرا می‌شود و به سرورهای برنامه اجازه می‌دهد تا درخواست‌ها را در زمان توسعه با پشتیبانی کامل از HMR رندر کنند.

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

اجرا کننده ماژول در Vite اجازه می‌دهد هر کدی را با پردازش آن توسط پلاگین‌های Vite اجرا کنید. این با `server.ssrLoadModule` متفاوت است زیرا پیاده‌سازی اجراکننده از سرور جدا شده است. این موضوع به نویسندگان کتابخانه و فریم‌ورک اجازه می‌دهد لایه ارتباطی خود را بین سرور Vite و اجراکننده پیاده‌سازی کنند. مرورگر با استفاده از Web Socket سرور و از طریق درخواست‌های HTTP با محیط مربوطه خود ارتباط برقرار می‌کند. Node Module Runner می‌تواند به طور مستقیم فراخوانی‌های تابع را برای پردازش ماژول‌ها انجام دهد زیرا در همان فرآیند اجرا می‌شود. سایر محیط‌ها می‌توانند ماژول‌ها را با اتصال به یک رانتایم JS مانند workerd، یا یک Worker Thread همانطور که Vitest انجام می‌دهد، اجرا کنند.

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

```ts
import { DevEnvironment, HotChannel } from 'vite'

function createWorkerdDevEnvironment(
  name: string,
  config: ResolvedConfig,
  context: DevEnvironmentContext
) {
  const connection = /* ... */
  const transport: HotChannel = {
    on: (listener) => { connection.on('message', listener) },
    send: (data) => connection.send(data),
  }

  const workerdDevEnvironment = new DevEnvironment(name, config, {
    options: {
      resolve: { conditions: ['custom'] },
      ...context.options,
    },
    hot: true,
    transport,
  })
  return workerdDevEnvironment
}
```

## `ModuleRunner`

یک اجراکننده‌ی ماژول (Module Runner) در رانتایم هدف ساخته می‌شود. تمام APIهایی که در بخش بعدی آمده‌اند، مگر در مواردی که به‌طور دیگری ذکر شده باشد، از مسیر `vite/module-runner` ایمپورت می‌شوند. این نقطه ورود در حد ممکن سبک نگه داشته شده و تنها کمترین موارد لازم را برای ساخت اجراکننده ماژول را اکسپورت می‌کند.

**امضای تایپ:**

```ts
export class ModuleRunner {
  constructor(
    public options: ModuleRunnerOptions,
    public evaluator: ModuleEvaluator = new ESModulesEvaluator(),
    private debug?: ModuleRunnerDebugger,
  ) {}
  /**
   * URL to execute.
   * Accepts file path, server path, or id relative to the root.
   */
  public async import<T = any>(url: string): Promise<T>
  /**
   * Clear all caches including HMR listeners.
   */
  public clearCache(): void
  /**
   * Clear all caches, remove all HMR listeners, reset sourcemap support.
   * This method doesn't stop the HMR connection.
   */
  public async close(): Promise<void>
  /**
   * Returns `true` if the runner has been closed by calling `close()`.
   */
  public isClosed(): boolean
}
```

ارزیاب ماژول در `ModuleRunner` مسئول اجرای کد است. Vite به صورت پیش‌فرض `ESModulesEvaluator` را اکسپورت می‌کند که از `new AsyncFunction` برای اجرای کد استفاده می‌کند. اگر رانتایم جاوااسکریپت شما از ارزیابی ناامن پشتیبانی نمی‌کند، می‌توانید پیاده‌سازی اختصاصی خود را ارائه دهید.

اجراکننده‌ی ماژول متد `import` را ارائه می‌دهد. زمانی که سرور Vite رویداد HMR از نوع `full-reload` را اجرا می‌کند، تمام ماژول‌های تحت تأثیر دوباره اجرا خواهند شد. توجه داشته باشید که اجراکننده‌ی ماژول در این فرآیند آبجکت `exports` را به‌روزرسانی نمی‌کند، بلکه آن را بازنویسی می‌کند. بنابراین، اگر نیاز به جدیدترین مقدار `exports` دارید، باید دوباره `import` را اجرا کنید یا ماژول را از `evaluatedModules` دریافت کنید.

**مثال استفاده:**

```js
import { ModuleRunner, ESModulesEvaluator } from 'vite/module-runner'
import { transport } from './rpc-implementation.js'

const moduleRunner = new ModuleRunner(
  {
    transport,
  },
  new ESModulesEvaluator(),
)

await moduleRunner.import('/src/entry-point.js')
```

## `ModuleRunnerOptions`

```ts twoslash
import type {
  InterceptorOptions as InterceptorOptionsRaw,
  ModuleRunnerHmr as ModuleRunnerHmrRaw,
  EvaluatedModules,
} from 'vite/module-runner'
import type { Debug } from '@type-challenges/utils'

type InterceptorOptions = Debug<InterceptorOptionsRaw>
type ModuleRunnerHmr = Debug<ModuleRunnerHmrRaw>
/** see below */
type ModuleRunnerTransport = unknown

// ---cut---
interface ModuleRunnerOptions {
  /**
   * A set of methods to communicate with the server.
   */
  transport: ModuleRunnerTransport
  /**
   * Configure how source maps are resolved.
   * Prefers `node` if `process.setSourceMapsEnabled` is available.
   * Otherwise it will use `prepareStackTrace` by default which overrides
   * `Error.prepareStackTrace` method.
   * You can provide an object to configure how file contents and
   * source maps are resolved for files that were not processed by Vite.
   */
  sourcemapInterceptor?:
    | false
    | 'node'
    | 'prepareStackTrace'
    | InterceptorOptions
  /**
   * Disable HMR or configure HMR options.
   *
   * @default true
   */
  hmr?: boolean | ModuleRunnerHmr
  /**
   * Custom module cache. If not provided, it creates a separate module
   * cache for each module runner instance.
   */
  evaluatedModules?: EvaluatedModules
}
```

## `ModuleEvaluator`

**امضای تایپ:**

```ts twoslash
import type { ModuleRunnerContext as ModuleRunnerContextRaw } from 'vite/module-runner'
import type { Debug } from '@type-challenges/utils'

type ModuleRunnerContext = Debug<ModuleRunnerContextRaw>

// ---cut---
export interface ModuleEvaluator {
  /**
   * Number of prefixed lines in the transformed code.
   */
  startOffset?: number
  /**
   * Evaluate code that was transformed by Vite.
   * @param context Function context
   * @param code Transformed code
   * @param id ID that was used to fetch the module
   */
  runInlinedModule(
    context: ModuleRunnerContext,
    code: string,
    id: string,
  ): Promise<any>
  /**
   * evaluate externalized module.
   * @param file File URL to the external module
   */
  runExternalModule(file: string): Promise<any>
}
```

Vite به‌صورت پیش‌فرض `ESModulesEvaluator` را اکسپورت می‌کند که این اینترفیس را پیاده‌سازی می‌کند. این ماژول از `new AsyncFunction` برای اجرای کد استفاده می‌کند. بنابراین، اگر کد دارای سورس مپ داخلی (inlined source map) باشد، باید شامل یک [افست ۲ خطی](https://tc39.es/ecma262/#sec-createdynamicfunction) باشد تا فضای موردنیاز برای خطوط جدید اضافه‌شده را جبران کند. این کار به‌طور خودکار توسط `ESModulesEvaluator` انجام می‌شود. اما ارزیاب‌های سفارشی (Custom evaluators) خطوط اضافی را اضافه نخواهند کرد.

## `ModuleRunnerTransport`

**امضای تایپ:**

```ts twoslash
import type { ModuleRunnerTransportHandlers } from 'vite/module-runner'
/** an object */
type HotPayload = unknown
// ---cut---
interface ModuleRunnerTransport {
  connect?(handlers: ModuleRunnerTransportHandlers): Promise<void> | void
  disconnect?(): Promise<void> | void
  send?(data: HotPayload): Promise<void> | void
  invoke?(data: HotPayload): Promise<{ result: any } | { error: any }>
  timeout?: number
}
```

آبجکت Transport برای ارتباط با محیط از طریق RPC یا فراخوانی مستقیم توابع استفاده می‌شود. اگر متد `invoke` پیاده‌سازی نشده باشد، باید متدهای `send` و `connect` را پیاده‌سازی کنید. در این حالت، Vite خودش متد `invoke` را ایجاد می‌کند.

برای این کار، باید آن را با نمونه‌ای از `HotChannel` روی سرور ترکیب کنید، مانند مثالی که در آن ماژول رانر در یک (Worker Thread) ایجاد می‌شود:

::: code-group

```js [worker.js]
import { parentPort } from 'node:worker_threads'
import { fileURLToPath } from 'node:url'
import { ESModulesEvaluator, ModuleRunner } from 'vite/module-runner'

/** @type {import('vite/module-runner').ModuleRunnerTransport} */
const transport = {
  connect({ onMessage, onDisconnection }) {
    parentPort.on('message', onMessage)
    parentPort.on('close', onDisconnection)
  },
  send(data) {
    parentPort.postMessage(data)
  },
}

const runner = new ModuleRunner(
  {
    transport,
  },
  new ESModulesEvaluator(),
)
```

```js [server.js]
import { BroadcastChannel } from 'node:worker_threads'
import { createServer, RemoteEnvironmentTransport, DevEnvironment } from 'vite'

function createWorkerEnvironment(name, config, context) {
  const worker = new Worker('./worker.js')
  const handlerToWorkerListener = new WeakMap()

  const workerHotChannel = {
    send: (data) => worker.postMessage(data),
    on: (event, handler) => {
      if (event === 'connection') return

      const listener = (value) => {
        if (value.type === 'custom' && value.event === event) {
          const client = {
            send(payload) {
              worker.postMessage(payload)
            },
          }
          handler(value.data, client)
        }
      }
      handlerToWorkerListener.set(handler, listener)
      worker.on('message', listener)
    },
    off: (event, handler) => {
      if (event === 'connection') return
      const listener = handlerToWorkerListener.get(handler)
      if (listener) {
        worker.off('message', listener)
        handlerToWorkerListener.delete(handler)
      }
    },
  }

  return new DevEnvironment(name, config, {
    transport: workerHotChannel,
  })
}

await createServer({
  environments: {
    worker: {
      dev: {
        createEnvironment: createWorkerEnvironment,
      },
    },
  },
})
```

:::

یک مثال دیگر که از یک درخواست HTTP برای ارتباط بین رانر (Runner) و سرور استفاده می‌کند:

```ts
import { ESModulesEvaluator, ModuleRunner } from 'vite/module-runner'

export const runner = new ModuleRunner(
  {
    transport: {
      async invoke(data) {
        const response = await fetch(`http://my-vite-server/invoke`, {
          method: 'POST',
          body: JSON.stringify(data),
        })
        return response.json()
      },
    },
    hmr: false, // disable HMR as HMR requires transport.connect
  },
  new ESModulesEvaluator(),
)

await runner.import('/entry.js')
```

در این حالت، متد `handleInvoke` در `NormalizedHotChannel` قابل استفاده است.

```ts
const customEnvironment = new DevEnvironment(name, config, context)

server.onRequest((request: Request) => {
  const url = new URL(request.url)
  if (url.pathname === '/invoke') {
    const payload = (await request.json()) as HotPayload
    const result = customEnvironment.hot.handleInvoke(payload)
    return new Response(JSON.stringify(result))
  }
  return Response.error()
})
```

اما توجه داشته باشید که برای پشتیبانی از HMR، متدهای `send` و `connect` الزامی هستند. متد `send` معمولاً زمانی فراخوانی می‌شود که یک رویداد سفارشی فعال شود (مثلاً `import.meta.hot.send("my-event")`).

Vite متد `createServerHotChannel` را از نقطه ورود اصلی اکسپورت می‌کند تا از HMR در حین اجرای SSR در Vite پشتیبانی کند.

---

---
url: /guide/api-environment-frameworks.md
---
# API محیط برای فریم‌ورک‌ها

:::warning آزمایشی
رابط Environment API هنوز در مرحله‌ی آزمایشی (experimental) هست. با این حال، ما تلاش می‌کنیم بین نسخه‌های اصلی (major) پایداری این APIها را حفظ کنیم تا جامعه‌ی توسعه‌دهندگان بتوانند با آن‌ها کار کرده و تجربیات خود را بر اساس آن‌ها توسعه دهند. ما قصد داریم این APIهای جدید را در یکی از نسخه‌های اصلی آینده به حالت پایدار (stable) برسانیم. البته ممکن است در این فرآیند تغییرات شکننده (breaking changes) نیز اعمال شود، اما این کار زمانی انجام خواهد شد که پروژه‌ها و کتابخانه‌های وابسته فرصت کافی برای آزمایش و ارزیابی این قابلیت‌های جدید را داشته باشند.

منابع:

* [بحث و گفتگو](https://github.com/vitejs/vite/discussions/16358) جایی که ما در حال جمع‌آوری نظرات درباره APIهای جدید هستیم.
* [PR مربوط به Environment API](https://github.com/vitejs/vite/pull/16471) جایی که API جدید پیاده‌سازی و بررسی شده است.

لطفاً نظرات و بازخوردهای خود را با ما به اشتراک بگذارید.
:::

## محیط‌ها و فریم‌ورک‌ها

محیط `ssr` و سایر محیط‌های غیرکلاینت به طور پیش‌فرض در زمان توسعه از یک `RunnableDevEnvironment` استفاده می‌کنند. در حالی که این نیاز دارد که رانتایم مشابه با سرور Vite باشد، این روش مشابه با `ssrLoadModule` عمل می‌کند و به فریم‌ورک‌ها اجازه می‌دهد تا مهاجرت کرده و HMR را برای توسعه SSR خود فعال کنند. شما می‌توانید هر محیط اجرایی را با استفاده از تابع `isRunnableDevEnvironment` بررسی کنید.

```ts
export class RunnableDevEnvironment extends DevEnvironment {
  public readonly runner: ModuleRunner
}

class ModuleRunner {
  /**
   * برای اجرا URL
   * می‌تواند مسیر فایل، مسیر سرور، یا شناسه‌ای نسبی به ریشه را بپذیرد
   * ssrLoadModule یک ماژول نمونه‌سازی‌شده را برمی‌گرداند مشابه
   */
  public async import(url: string): Promise<Record<string, any>>
  /**
   * ModuleRunner سایر متدهای
   */
}

if (isRunnableDevEnvironment(server.environments.ssr)) {
  await server.environments.ssr.runner.import('/entry-point.js')
}
```

:::warning هشدار
`runner` زمانی که برای اولین بار به آن دسترسی پیدا کنید، بلافاصله مقداردهی می‌شود. توجه داشته باشید که وقتی `runner` با فراخوانی `process.setSourceMapsEnabled` ساخته می‌شود یا در صورت عدم دسترسی، با جایگزین کردن `Error.prepareStackTrace` ، Vite از پشتیبانی سورس مپ استفاده می‌کند.
:::

فریم‌ورک‌هایی که از طریق [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Window/fetch) با محیط اجرای خود ارتباط برقرار می‌کنند، می‌توانند از `FetchableDevEnvironment` استفاده کنند. این کلاس روشی استاندارد برای مدیریت درخواست‌ها از طریق متد `handleRequest` فراهم می‌کند.

```ts
import {
  createServer,
  createFetchableDevEnvironment,
  isFetchableDevEnvironment,
} from 'vite'

const server = await createServer({
  server: { middlewareMode: true },
  appType: 'custom',
  environments: {
    custom: {
      dev: {
        createEnvironment(name, config) {
          return createFetchableDevEnvironment(name, config, {
            handleRequest(request: Request): Promise<Response> | Response {
              // handle Request and return a Response
            },
          })
        },
      },
    },
  },
})

// Any consumer of the environment API can now call `dispatchFetch`
if (isFetchableDevEnvironment(server.environments.custom)) {
  const response: Response = await server.environments.custom.dispatchFetch(
    new Request('/request-to-handle'),
  )
}
```

:::warning هشدار
Vite ورودی و خروجی متد `dispatchFetch` را اعتبارسنجی می‌کند: درخواست (Request) باید نمونه‌ای از کلاس سراسری `Request` باشد و پاسخ (Response) نیز باید نمونه‌ای از کلاس سراسری `Response` باشد. اگر این شرایط برقرار نباشد، Vite یک خطای `TypeError` پرتاب می‌کند.

توجه داشته باشید که اگرچه `FetchableDevEnvironment` به‌صورت یک کلاس پیاده‌سازی شده است، تیم توسعه Vite آن را به‌عنوان یک جزئیات داخلی (implementation detail) در نظر می‌گیرد. به این معنی که ممکن است در آینده، بدون اعلام قبلی، تغییر کند.
:::

## محیط پیش‌فرض `RunnableDevEnvironment`

با توجه به سرور Vite که مطابق [راهنمای راه‌اندازی SSR](/guide/ssr#setting-up-the-dev-server) در حالت میان‌افزار (middleware) پیکربندی شده، بیایید با استفاده از API محیط، میان‌افزار SSR را پیاده‌سازی کنیم. به یاد داشته باشید که الزاماً نباید نام آن `ssr` باشد، بنابراین در این مثال آن را `server` می‌نامیم. (جزئیات مربوط به مدیریت خطا در این مثال نادیده گرفته شده است)

```js
import fs from 'node:fs'
import path from 'node:path'
import { fileURLToPath } from 'node:url'
import { createServer } from 'vite'

const __dirname = path.dirname(fileURLToPath(import.meta.url))

const viteServer = await createServer({
  server: { middlewareMode: true },
  appType: 'custom',
  environments: {
    server: {
// اجرا شده است Vite به طور پیش‌فرض، ماژول‌ها در همان فرآیندی اجرا می‌شوند که سرور
    },
  },
})

// تبدیل کنید RunnableDevEnvironment نیاز داشته باشید آن را به TypeScript شاید در
// استفاده کنید runner برای بررسی دسترسی به isRunnableDevEnvironment یا از
const serverEnvironment = viteServer.environments.server

app.use('*', async (req, res, next) => {
  const url = req.originalUrl

  // 1. index.html خواندن فایل
  const indexHtmlPath = path.resolve(__dirname, 'index.html')
  let template = fs.readFileSync(indexHtmlPath, 'utf-8')

  // 2. Vite به HTML تبدیل‌های مربوط به
  //    را اعمال می‌کند Vite را تزریق می‌کند و همچنین تبدیل‌های پلاگین‌های HMR Client
  //    @vitejs/plugin-react پیش‌درآمد از
  template = await viteServer.transformIndexHtml(url, template)

  // 3. را ESM کد import(url) ماژول ورودی سرور را بارگیری می‌کند. متد
  //    به صورت خودکار تبدیل می‌کند و نیاز به باندل ندارد Node.js برای استفاده در
  //    را فراهم می‌کند HMR همچنین پشتیبانی کامل از
  const { render } = await serverEnvironment.runner.import(
    '/src/entry-server.js',
  )

  // 4. از render برنامه را رندر می‌کند. فرض بر این است که تابع HTML محتوای
  //    فریم‌ورک استفاده می‌کند SSR های مربوط به API از entry-server.js
  //    ReactDOMServer.renderToString() مانند
  const appHtml = await render(url)

  // 5. محتوای رندر شده را وارد قالب می‌کند
  const html = template.replace(`<!--ssr-outlet-->`, appHtml)

  // 6. نهایی را برمی‌گرداند HTML محتوای
  res.status(200).set({ 'Content-Type': 'text/html' }).end(html)
})
```

## SSR بدون وابستگی به Runtime مشخص

از آنجا که `RunnableDevEnvironment` فقط در همان رانتایم سرور Vite کد را اجرا می‌کند، این رانتایم باید قادر به اجرای سرور Vite باشد (رانتایمی سازگار با Node.js). به این معناست که برای حذف وابستگی به رانتایم مشخص، باید از `DevEnvironment` به صورت خام استفاده کنید.

:::info پیشنهاد `FetchableDevEnvironment`

در طرح اولیه، متدی به نام `run` در کلاس `DevEnvironment` پیشنهاد شد که با استفاده از گزینه `transport`، امکان ایمپورت در بخش اجراکننده (runner) را فراهم می‌کرد. در آزمایش‌ها مشخص شد که این API به اندازه کافی فراگیر نیست تا توصیه شود. هم‌اکنون منتظر بازخورد در مورد [پیشنهاد `FetchableDevEnvironment`](https://github.com/vitejs/vite/discussions/18191) هستیم.

:::

در `RunnableDevEnvironment` متد `runner.import` وجود دارد که مقدار ماژول را برمی‌گرداند، اما در `DevEnvironment` خام در دسترس نیست و نیاز دارد کد استفاده‌کننده از APIهای Vite و ماژول‌های کاربر از یکدیگر جدا باشند.

مثال زیر، کد از ماژول کاربر در همان جایی استفاده می‌کند که از APIهای Vite نیز استفاده می‌شود:

```ts
// code using the Vite's APIs
import { createServer } from 'vite'

const server = createServer()
const ssrEnvironment = server.environment.ssr
const input = {}

const { createHandler } = await ssrEnvironment.runner.import('./entrypoint.js')
const handler = createHandler(input)
const response = handler(new Request('/'))

// -------------------------------------
// ./entrypoint.js
export function createHandler(input) {
  return function handler(req) {
    return new Response('hello')
  }
}
```

اگر کد شما می‌تواند در همان محیط اجرایی ماژول‌های کاربر اجرا شود (یعنی به APIهای مخصوص Node.js وابسته نیست)، می‌توانید از یک ماژول مجازی استفاده کنید. این روش نیاز به دسترسی به مقدار از طریق APIهای Vite را از بین می‌برد.

```ts
// Vite های API کد با استفاده از
import { createServer } from 'vite'

const server = createServer({
  plugins: [
    // `virtual:entrypoint` پلاگین برای رسیدگی به مسیر مجازی
    {
      name: 'virtual-module',
      /* پیاده‌سازی پلاگین */
    },
  ],
})
const ssrEnvironment = server.environment.ssr
const input = {}

// از توابعی که توسط فکتوری‌های هر محیط فراهم می‌شوند استفاده می‌کند
// بررسی می‌کند هر فکتوری محیط چه امکاناتی ارائه می‌دهد
if (ssrEnvironment instanceof RunnableDevEnvironment) {
  ssrEnvironment.runner.import('virtual:entrypoint')
} else if (ssrEnvironment instanceof CustomDevEnvironment) {
  ssrEnvironment.runEntrypoint('virtual:entrypoint')
} else {
  throw new Error(`Unsupported runtime for ${ssrEnvironment.name}`)
}

// -------------------------------------
// virtual:entrypoint
const { createHandler } = await import('./entrypoint.js')
const handler = createHandler(input)
const response = handler(new Request('/'))

// -------------------------------------
// ./entrypoint.js
export function createHandler(input) {
  return function handler(req) {
    return new Response('hello')
  }
}
```

برای مثال، برای فراخوانی `transformIndexHtml` روی ماژول کاربر، می‌توان از پلاگین زیر استفاده کرد:

```ts {13-21}
function vitePluginVirtualIndexHtml(): Plugin {
  let server: ViteDevServer | undefined
  return {
    name: vitePluginVirtualIndexHtml.name,
    configureServer(server_) {
      server = server_
    },
    resolveId(source) {
      return source === 'virtual:index-html' ? '\0' + source : undefined
    },
    async load(id) {
      if (id === '\0' + 'virtual:index-html') {
        let html: string
        if (server) {
          this.addWatchFile('index.html')
          html = fs.readFileSync('index.html', 'utf-8')
          html = await server.transformIndexHtml('/', html)
        } else {
          html = fs.readFileSync('dist/client/index.html', 'utf-8')
        }
        return `export default ${JSON.stringify(html)}`
      }
      return
    },
  }
}
```

اگر کد شما به APIهای Node.js نیاز دارد، می‌توانید برای ارتباط با کدی که از APIهای Vite در ماژول‌های کاربر استفاده می‌کند، از `hot.send` استفاده کنید. با این حال، دقت داشته باشید که پس از مرحله بیلد، این روش ممکن است همانند قبل کار نکند.

```ts
// Vite های API کد با استفاده از
import { createServer } from 'vite'

const server = createServer({
  plugins: [
    // `virtual:entrypoint` پلاگین برای رسیدگی به مسیر مجازی
    {
      name: 'virtual-module',
      /* پیاده‌سازی پلاگین */
    },
  ],
})
const ssrEnvironment = server.environment.ssr
const input = {}

// از توابعی که توسط فکتوری‌های هر محیط فراهم می‌شوند استفاده می‌کند
// بررسی می‌کند هر فکتوری محیط چه امکاناتی ارائه می‌دهد
if (ssrEnvironment instanceof RunnableDevEnvironment) {
  ssrEnvironment.runner.import('virtual:entrypoint')
} else if (ssrEnvironment instanceof CustomDevEnvironment) {
  ssrEnvironment.runEntrypoint('virtual:entrypoint')
} else {
  throw new Error(`Unsupported runtime for ${ssrEnvironment.name}`)
}

const req = new Request('/')

const uniqueId = 'a-unique-id'
ssrEnvironment.send('request', serialize({ req, uniqueId }))
const response = await new Promise((resolve) => {
  ssrEnvironment.on('response', (data) => {
    data = deserialize(data)
    if (data.uniqueId === uniqueId) {
      resolve(data.res)
    }
  })
})

// -------------------------------------
// virtual:entrypoint
const { createHandler } = await import('./entrypoint.js')
const handler = createHandler(input)

import.meta.hot.on('request', (data) => {
  const { req, uniqueId } = deserialize(data)
  const res = handler(req)
  import.meta.hot.send('response', serialize({ res: res, uniqueId }))
})

const response = handler(new Request('/'))

// -------------------------------------
// ./entrypoint.js
export function createHandler(input) {
  return function handler(req) {
    return new Response('hello')
  }
}
```

## محیط‌ها در زمان بیلد

در خط فرمان (CLI)، فراخوانی `vite build` و `vite build --ssr` همچنان به‌خاطر سازگاری با نسخه‌های قبلی فقط محیط کلاینت و محیط SSR را بیلد می‌کند.

زمانی که `builder` تعریف شده باشد (یا وقتی از `vite build --app` استفاده می‌کنید)، `vite build` برای بیلد کل اپلیکیشن فعال می‌شود. این کار در نسخه مهم بعدی به صورت پیش‌فرض خواهد بود. یک نمونه از `ViteBuilder` (معادل بیلدی `ViteDevServer`) ایجاد می‌شود تا تمام محیط‌های پیکربندی‌شده را برای پروداکشن بیلد کند. به صورت پیش‌فرض، بیلد محیط‌ها به صورت سری و بر اساس ترتیب رکورد `environments` اجرا می‌شود. یک فریم‌ورک یا کاربر می‌تواند با استفاده از تنظیمات زیر مشخص کند چگونه محیط‌ها بیلد شوند:

```js
export default {
  builder: {
    buildApp: async (builder) => {
      const environments = Object.values(builder.environments)
      return Promise.all(
        environments.map((environment) => builder.build(environment)),
      )
    },
  },
}
```

پلاگین‌ها همچنین می‌توانند یک هوک به نام `buildApp` تعریف کنند. هوک‌هایی با ترتیب `'pre'` و `null` قبل از اجرای `builder.buildApp` پیکربندی‌شده اجرا می‌شوند و هوک‌های با ترتیب `'post'` پس از آن اجرا خواهند شد. از ویژگی `environment.isBuilt` می‌توان برای بررسی اینکه آیا یک محیط از قبل ساخته شده است یا خیر، استفاده کرد.

## کد بدون وابستگی مستقیم به محیط

اغلب اوقات، نمونه محیط فعلی به عنوان بخشی از کانتکست کدی که اجرا می‌شود در دسترس است، بنابراین نیاز به دسترسی مستقیم از طریق `server.environments` معمولاً کم است. به عنوان مثال، در هوک‌های پلاگین، محیط به عنوان بخشی از `PluginContext` در دسترس قرار می‌گیرد و می‌توانید با `this.environment` به آن دسترسی داشته باشید. برای آشنایی با نحوه ساخت پلاگین‌های آگاه به محیط، به [Environment API for Plugins](./api-environment-plugins.md) مراجعه کنید.

---

---
url: /guide/comparisons.md
---
# Comparisons

## WMR

[WMR](https://github.com/preactjs/wmr) by the Preact team looked to provide a similar feature set. Vite's universal Rollup plugin API for dev and build was inspired by it.

WMR is no longer maintained. The Preact team now recommends Vite with [@preactjs/preset-vite](https://github.com/preactjs/preset-vite).

## @web/dev-server

[@web/dev-server](https://modern-web.dev/docs/dev-server/overview/) (previously `es-dev-server`) is a great project and Vite 1.0's Koa-based server setup was inspired by it.

`@web/dev-server` is a bit lower-level in terms of scope. It does not provide official framework integrations, and requires manually setting up a Rollup configuration for the production build.

Overall, Vite is a more opinionated / higher-level tool that aims to provide a more out-of-the-box workflow. That said, the `@web` umbrella project contains many other excellent tools that may benefit Vite users as well.

## Snowpack

[Snowpack](https://www.snowpack.dev/) was also a no-bundle native ESM dev server, very similar in scope to Vite. The project is no longer being maintained. The Snowpack team is now working on [Astro](https://astro.build/), a static site builder powered by Vite. The Astro team is now an active player in the ecosystem, and they are helping to improve Vite.

Aside from different implementation details, the two projects shared a lot in terms of technical advantages over traditional tooling. Vite's dependency pre-bundling is also inspired by Snowpack v1 (now [`esinstall`](https://github.com/snowpackjs/snowpack/tree/main/esinstall)). Some of the main differences between the two projects are listed in [the v2 Comparisons Guide](https://v2.vite.dev/guide/comparisons).

---

---
url: /guide/api-environment.md
---
# Environment API

:::warning آزمایشی
رابط Environment API هنوز در مرحله‌ی آزمایشی (experimental) هست. با این حال، ما تلاش می‌کنیم بین نسخه‌های اصلی (major) پایداری این APIها را حفظ کنیم تا جامعه‌ی توسعه‌دهندگان بتوانند با آن‌ها کار کرده و تجربیات خود را بر اساس آن‌ها توسعه دهند. ما قصد داریم این APIهای جدید را در یکی از نسخه‌های اصلی آینده به حالت پایدار (stable) برسانیم. البته ممکن است در این فرآیند تغییرات شکننده (breaking changes) نیز اعمال شود، اما این کار زمانی انجام خواهد شد که پروژه‌ها و کتابخانه‌های وابسته فرصت کافی برای آزمایش و ارزیابی این قابلیت‌های جدید را داشته باشند.

منابع:

* [بحث و گفتگو](https://github.com/vitejs/vite/discussions/16358) جایی که ما در حال جمع‌آوری نظرات درباره APIهای جدید هستیم.
* [PR مربوط به Environment API](https://github.com/vitejs/vite/pull/16471) جایی که API جدید پیاده‌سازی و بررسی شده است.

لطفاً نظرات و بازخوردهای خود را با ما به اشتراک بگذارید.
:::

## استانداردسازی محیط‌ها

Vite 6 مفهوم محیط‌ها را استانداردسازی می‌کند. تا نسخه‌ی Vite 5، دو محیط پیش‌فرض وجود داشت: (`client` و در صورت نیاز `ssr`). Environment API (رابط برنامه‌نویسی محیط) جدید به کاربران و توسعه‌دهندگان فریمورک‌ها اجازه می‌دهد تا به تعداد مورد نیاز محیط ایجاد کنند و آن را با نحوه‌ی عملکرد برنامه‌هایشان در محیط پروداکشن تطبیق دهند. این قابلیت جدید نیازمند بازنگری گسترده‌ای در ساختار داخلی بود، اما تلاش زیادی برای حفظ سازگاری با نسخه‌های قبلی صورت گرفته است. هدف اولیه‌ی Vite 6 این است که اکوسیستم را به‌آرامی به نسخه‌ی جدید منتقل کند و پذیرش این APIهای آزمایشی جدید را تا زمانی که تعداد کافی از کاربران مهاجرت کرده و توسعه‌دهندگانِ فریمورک‌ها و افزونه‌ها طراحی جدید را تأیید کنند، به تعویق بیندازد.

## کاهش فاصله بین ساخت و توسعه

برای یک SPA/MPA ساده، هیچ API جدیدی در مورد محیط‌ها به پیکربندی افزوده نشده است. از نظر داخلی، Vite گزینه‌ها را به محیط `client` اعمال خواهد کرد، اما نیازی به دانستن این مفهوم هنگام پیکربندی Vite نیست. پیکربندی و رفتار موجود در Vite 5 باید به‌طور یکپارچه در اینجا کار کند.

هنگامی که به سمت یک اپلیکیشن معمولی رندر شده در سمت سرور (SSR) می‌رویم، دو محیط خواهیم داشت:

* `client`: اپلیکیشن را در مرورگر اجرا می‌کند.
* `ssr`: اپلیکیشن را در Node (یا سایر رانتایم‌ها سرور) اجرا می‌کند که صفحات را قبل از ارسال به مرورگر رندر می‌کند.

در محیط توسعه (dev)، Vite کد سرور را در همان فرآیند Node که سرور توسعه Vite را اجرا می‌کند، اجرا می‌کند، که شبیه‌سازی نزدیکی به محیط پروداکشن ایجاد می‌کند. با این حال، ممکن است سرورها در رانتایم جاوااسکریپت دیگری مانند [Workerd Cloudflare](https://github.com/cloudflare/workerd) اجرا شوند که محدودیت‌های متفاوتی دارند. اپلیکیشن‌های مدرن همچنین ممکن است در بیشتر از دو محیط اجرا شوند، مثلاً یک مرورگر، یک سرور Node و یک سرور لبه. Vite 5 قادر به نمایاندن مناسب این محیط‌ها نبود.

Vite 6 به کاربران امکان می‌دهد برنامه خود را طوری پیکربندی کنند که همه محیط‌های اجرایی آن را در فرایند توسعه و ساخت پوشش دهد. در زمان توسعه، اکنون یک سرور توسعه Vite می‌تواند همزمان کد را در چندین محیط مختلف اجرا کند. سورس کد برنامه همچنان توسط سرور توسعه Vite تبدیل می‌شود. علاوه بر سرور HTTP مشترک، میان‌افزارها، تنظیمات پردازش‌شده و زنجیره پلاگین‌ها، سرور توسعه Vite اکنون دارای مجموعه‌ای از محیط‌های توسعه مستقل است. هر محیط توسعه طوری پیکربندی شده که تا حد امکان به محیط پروداکشن شبیه باشد و به یک رانتایم توسعه متصل است که کد در آن اجرا می‌شود (برای مثال در مورد Workerd، کد سرور اکنون می‌تواند به صورت محلی در Miniflare اجرا شود). در سمت کلاینت، مرورگر کد را ایمپورت و اجرا می‌کند، و در سایر محیط‌ها، یک اجراکننده ماژول، کد تبدیل‌شده را بارگیری و ارزیابی می‌کند.

![Vite Environments](/assets/vite-environments.DZyy20w5.svg)

## پیکربندی محیط‌ها

برای یک برنامه SPA/MPA، پیکربندی مشابه Vite 5 خواهد بود. به صورت داخلی، این گزینه‌ها برای پیکربندی محیط `client` استفاده می‌شوند.

```js
export default defineConfig({
  build: {
    sourcemap: false,
  },
  optimizeDeps: {
    include: ['lib'],
  },
})
```

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

اگر برنامه از چندین محیط تشکیل شده باشد، این محیط‌ها می‌توانند به صورت صریح با گزینه پیکربندی `environments` تنظیم شوند.

```js
export default {
  build: {
    sourcemap: false,
  },
  optimizeDeps: {
    include: ['lib'],
  },
  environments: {
    server: {},
    edge: {
      resolve: {
        noExternal: true,
      },
    },
  },
}
```

اگر به صورت صریح مستند نشده باشد، هر محیط از گزینه‌های پیکربندی سطح بالا ارث می‌برد (به عنوان مثال، محیط‌های جدید `server` و `edge` گزینه `build.sourcemap: false` را به ارث می‌برند). تعداد کمی از گزینه‌های سطح بالا، مانند `optimizeDeps`، فقط برای محیط `client` اعمال می‌شوند، زیرا زمانی که به عنوان پیش‌فرض به محیط‌های سرور اعمال می‌شوند، به خوبی کار نمی‌کنند. محیط `client` همچنین می‌تواند به صورت صریح از طریق `environments.client` پیکربندی شود، اما توصیه می‌کنیم این کار را با گزینه‌های سطح بالا انجام دهید تا پیکربندی کلاینت هنگام اضافه کردن محیط‌های جدید بدون تغییر باقی بماند.

رابط `EnvironmentOptions` تمام گزینه‌های مختص هر محیط را در اختیار قرار می‌دهد. برخی گزینه‌های محیطی هم برای `build` و هم برای `dev` اعمال می‌شوند، مانند `resolve`. همچنین `DevEnvironmentOptions` و `BuildEnvironmentOptions` برای گزینه‌های خاص توسعه و ساخت وجود دارند (مانند `dev.warmup` یا `build.outDir`). برخی گزینه‌ها مانند `optimizeDeps` فقط برای توسعه اعمال می‌شوند، اما برای حفظ سازگاری با نسخه‌های قبلی، به جای قرار گرفتن در `dev`، در سطح بالا نگه داشته شده‌اند.

```ts
interface EnvironmentOptions {
  define?: Record<string, any>
  resolve?: EnvironmentResolveOptions
  optimizeDeps: DepOptimizationOptions
  consumer?: 'client' | 'server'
  dev: DevOptions
  build: BuildOptions
}
```

رابط `UserConfig` از رابط `EnvironmentOptions` گسترش می‌یابد، که امکان پیکربندی کلاینت و پیش‌فرض‌ها را برای سایر محیط‌ها، از طریق گزینه `environments` فراهم می‌کند. محیط `client` و یک محیط سرور با نام `ssr` همیشه در زمان توسعه حاضر هستند. این امر باعث سازگاری با نسخه‌های قبلی برای `server.ssrLoadModule(url)` و `server.moduleGraph` می‌شود. در زمان بیلد، محیط `client` همیشه وجود دارد، و محیط `ssr` تنها در صورتی وجود خواهد داشت که به صورت صریح پیکربندی شده باشد (با استفاده از `environments.ssr` یا برای سازگاری با نسخه‌های قبلی `build.ssr`). یک برنامه لزوماً نیازی به استفاده از نام `ssr` برای محیط SSR خود ندارد، می‌تواند آن را به عنوان مثال `server` نام‌گذاری کند.

```ts
interface UserConfig extends EnvironmentOptions {
  environments: Record<string, EnvironmentOptions>
  // other options
}
```

توجه داشته باشید که ویژگی سطح بالای `ssr` پس از پایدار شدن API محیط، منسوخ خواهد شد. این گزینه نقشی مشابه با `environments` دارد، اما فقط برای محیط پیش‌فرض `ssr` است و تنها امکان پیکربندی مجموعه کوچکی از گزینه‌ها را فراهم می‌کند.

## نمونه‌های محیط سفارشی

APIهای پیکربندی سطح پایین در دسترس هستند تا ارائه‌دهندگان رانتایم بتوانند محیط‌هایی با پیش‌فرض‌های مناسب برای رانتایم خود فراهم کنند. این محیط‌ها همچنین می‌توانند فرآیندها یا نخ‌های دیگری را برای اجرای ماژول‌ها در زمان توسعه در یک رانتایم نزدیک‌تر به محیط تولید ایجاد کنند.

```js
import { customEnvironment } from 'vite-environment-provider'

export default {
  build: {
    outDir: '/dist/client',
  },
  environments: {
    ssr: customEnvironment({
      build: {
        outDir: '/dist/ssr',
      },
    }),
  },
}
```

## سازگاری با نسخه‌های قبلی

APIهای سرور فعلی Vite هنوز منسوخ نشده‌اند و با Vite 5 سازگار هستند. API محیط جدید در حالت آزمایشی است.

متد `server.moduleGraph` یک نمای ترکیبی از گراف‌های ماژول‌های کلاینت و SSR را باز می‌گرداند. نودهای ماژول ترکیبی که سازگاری با نسخه‌های قبلی دارند، از تمام متدهای این آبجکت باز می‌گردند. همین الگو برای نودهای ماژول‌هایی که به متد `handleHotUpdate` ارسال می‌شوند نیز استفاده می‌شود. به عبارت دیگر، این ویژگی به شما اجازه می‌دهد که هم ماژول‌های مرتبط با کلاینت و هم ماژول‌های مرتبط با SSR را به‌طور همزمان مدیریت کنید و نودهای مربوط به هرکدام را به‌طور یکپارچه در دسترس داشته باشید.

ما هنوز توصیه نمی‌کنیم که به API محیط تغییر دهید. هدف ما این است که بخش زیادی از کاربران قبل از این تغییرات، Vite 6 را پذیرفته و استفاده کنند تا پلاگین‌ها نیازی به نگهداری دو نسخه مختلف نداشته باشند. برای اطلاعات بیشتر در مورد تغییرات مخرب آینده و مسیر ارتقا، به بخش تغییرات مخرب آینده مراجعه کنید:

* [`this.environment` در Hooks](/changes/this-environment-in-hooks)
* [HMR `hotUpdate` Plugin Hook](/changes/hotupdate-hook)
* [انتقال به API‌های مخصوص هر محیط](/changes/per-environment-apis)
* [SSR با استفاده از `ModuleRunner` API](/changes/ssr-using-modulerunner)
* [پلاگین‌های مشترک در طول فرآیند ساخت](/changes/shared-plugins-during-build)

## کاربران هدف

این راهنما مفاهیم پایه‌ای درباره محیط‌ها را برای کاربران نهایی ارائه می‌دهد.

نویسندگان پلاگین‌ها یک API سازگارتر برای تعامل با پیکربندی محیط فعلی دارند. اگر شما بر روی Vite توسعه می‌دهید، راهنمای [API پلاگین‌های محیط](./api-environment-plugins.md) روش استفاده از API‌های اضافی پلاگین‌ها را توضیح می‌دهد که از محیط‌های سفارشی متعدد پشتیبانی می‌کنند.

فریم‌ورک‌ها می‌توانند تصمیم بگیرند که محیط‌ها را در سطوح مختلفی در دسترس قرار دهند. اگر شما نویسنده یک فریم‌ورک هستید، برای آشنایی با بخش برنامه‌نویسی API محیط، ادامه مطلب را در [راهنمای API محیط برای فریم‌ورک‌ها](./api-environment-frameworks) مطالعه کنید.

برای ارائه‌دهندگان رانتایم (Runtime providers)، [راهنمای API محیط برای رانتایم](./api-environment-runtimes.md) توضیح می‌دهد که چگونه می‌توان یک محیط سفارشی را برای استفاده توسط فریم‌ورک‌ها و کاربران ارائه داد.

---

---
url: /changes/ssr-using-modulerunner.md
---
# SSR با استفاده از API `ModuleRunner`

::: tip بازخورد
بازخورد خود را در [بحث بازخورد API محیط](https://github.com/vitejs/vite/discussions/16358) با ما در میان بگذارید.
:::

`server.ssrLoadModule` با وارد کردن از یک [Module Runner](/guide/api-environment#modulerunner) جایگزین شده است.

دامنه تأثیر: `نویسندگان افزونه‌های Vite`

::: warning منسوخ شدن در آینده
`ModuleRunner` برای اولین بار در نسخه `v6.0` معرفی شد. منسوخ شدن `server.ssrLoadModule` برای یک نسخه اصلی آینده برنامه‌ریزی شده است. برای شناسایی استفاده خود، `future.removeSsrLoadModule` را در تنظیمات Vite خود روی `"warn"` تنظیم کنید.
:::

## انگیزه

متد `server.ssrLoadModule(url)` فقط امکان وارد کردن ماژول‌ها در محیط `ssr` را فراهم می‌کند و تنها می‌تواند ماژول‌ها را در همان پروسه سرور توسعه Vite اجرا کند. برای اپلیکیشن‌هایی با محیط‌های سفارشی، هر کدام با یک `ModuleRunner` مرتبط هستند که ممکن است در یک نخ یا پروسه جداگانه اجرا شود. برای وارد کردن ماژول‌ها، اکنون از `moduleRunner.import(url)` استفاده می‌کنیم.

## راهنمای مهاجرت

به [راهنمای API محیط برای فریم‌ورک‌ها](../guide/api-environment-frameworks.md) مراجعه کنید.

---

---
url: /config/ssr-options.md
---
# آپشن‌های SSR

آپشن‌های این بخش هم در حالت توسعه (`dev`) و هم در مرحله ساخت (`build`) اعمال خواهند شد،مگر اینکه خلاف آن ذکر شده باشد.

## ssr.external

* **تایپ:** `string[]‎ | true`
* **مرتبط:** [SSR Externals](/guide/ssr#ssr-externals)

وابستگی‌های مشخص‌شده و وابستگی‌های وابسته به آن‌ها را برای SSR به حالت externalize در می‌آورد (مستقل کردن یا خارج کردن یک وابستگی از باندل اصلی). به‌طور پیش‌فرض، همه وابستگی‌ها به‌جز وابستگی‌های لینک‌شده (برای HMR) externalize می‌شوند. اگر می‌خواهید وابستگی لینک‌شده‌ای را نیز externalize کنید، می‌توانید نام آن را در این آپشن مشخص کنید.

اگر `true` باشد، تمام وابستگی‌ها از جمله وابستگی‌های لینک‌شده externalized می‌شوند.

توجه کنید که وابستگی‌هایی که به‌طور مشخص و صریح لیست شده‌اند (با استفاده از تایپ `string[]‎`) در هر حالتی اولویت دارند، حتی اگر در `ssr.noExternal` (با هر تایپی) نیز تعریف شده باشند.

## ssr.noExternal

* **تایپ:** `string | RegExp | (string | RegExp)[] | true`
* **مرتبط:** [SSR Externals](/guide/ssr#ssr-externals)

از مستقل شدن (externalized) وابستگی‌های فهرست‌شده برای SSR جلوگیری کنید، زیرا آن‌ها در مرحله ساخت (build) باندل خواهند شد. به‌طور پیش‌فرض، فقط وابستگی‌های لینک‌شده (linked) مستقل نمی‌شوند (برای HMR). اگر ترجیح می‌دهید که وابستگی‌های لینک‌شده نیز externalized شوند (مستقل کردن یا خارج کردن یک وابستگی از باندل اصلی)، می‌توانید نام آن‌ها را به گزینه `ssr.external` اضافه کنید.

اگر `true` باشد، هیچ وابستگی‌ای مستقل (externalized) نخواهد شد. با این حال، وابستگی‌هایی که به‌طور صریح در `ssr.external` (با استفاده از تایپ `string[]‎`) فهرست شده‌اند، می‌توانند اولویت داشته باشند و همچنان externalized شوند. اگر `ssr.target: 'node'` تنظیم شده باشد، ماژول‌های داخلی Node.js نیز به‌طور پیش‌فرض externalized خواهند شد.

توجه داشته باشید که اگر هر دو گزینه `ssr.noExternal: true` و `ssr.external: true` کانفیگ شده باشند، `ssr.noExternal` اولویت دارد و هیچ وابستگی‌ای مستقل (externalized) نخواهد شد.

## ssr.target

* **تایپ:** `'node' | 'webworker'`
* **پیش‌فرض:** `node`

بیلد target برای سرور SSR.

## ssr.resolve.conditions

* **تایپ:** `string[]‎`
* **پیش‌فرض:** `['module', 'node', 'development|production']` (`defaultServerConditions`) (`['module', 'browser', 'development|production']` (`defaultClientConditions`) برای `ssr.target === 'webworker'`)
* **مرتبط:** [Resolve Conditions](./shared-options.md#resolve-conditions)

این شرایط در مسیر پلاگین‌ها استفاده می‌شوند و فقط بر وابستگی‌های non-externalized در زمان ساخت SSR تأثیر می‌گذارند. برای تأثیرگذاری بر ایمپورت های externalized، از `ssr.resolve.externalConditions` استفاده کنید.

## ssr.resolve.externalConditions

* **تایپ:** `string[]‎`
* **پیش‌فرض:** `['node']`

شرایطی که در هنگام ایمپورت SSR (شامل `ssrLoadModule`) برای وابستگی‌های مستقیم externalized (وابستگی‌های خارجی که توسط Vite ایمپورت شده‌اند) اعمال می‌شوند.

:::tip نکته

هنگام استفاده از این آپشن، مطمئن شوید که Node را با [`flag --conditions`](https://nodejs.org/docs/latest/api/cli.html#-c-condition---conditionscondition) وبا مقادیر یکسان در هر دو حالت dev و build اجرا کنید تا رفتار یکسانی داشته باشید.

برای مثال، وقتی `['node', 'custom']` را تنظیم می‌کنید، باید در حالت dev دستور `NODE_OPTIONS='--conditions custom' vite` و پس از بیلد دستور `NODE_OPTIONS="--conditions custom" node ./dist/server.js` را اجرا کنید.

:::

## ssr.resolve.mainFields

* **تایپ:** `string[]‎`
* **پیش‌فرض:** `['module', 'jsnext:main', 'jsnext']`

فهرستی از فیلدهای `package.json` که هنگام تشخیص entry pointهای یک پکیج بررسی می‌شوند. توجه داشته باشید که این گزینه نسبت به اکسپورت شرطی که از فیلد `exports` شناسایی می‌شود، اولویت کم‌تری دارد: اگر entry point با موفقیت از `exports` تشخیص داده شود، فیلد `main` نادیده گرفته خواهد شد. این تنظیم فقط بر وابستگی‌های غیرمستقل (non-externalized) تأثیر می‌گذارد.

---

---
url: /config/worker-options.md
---
# آپشن‌های Worker

آپشن‌های این بخش برای همه‌ی حالت‌های dev، build و preview اعمال می‌شوند مگر آنکه بطور مشخص ذکر شده باشد.

## worker.format

* **تایپ:** `'es' | 'iife'`
* **مقدار پیش فرض:** `'iife'`

فرمت خروجی برای باندل worker.

## worker.plugins

* **تایپ:** [`() => (Plugin | Plugin[])[]`](./shared-options#plugins)

پلاگین های vite که بر باندل های worker اعمال می‌شوند. توجه کنید که [config.plugins](./shared-options#plugins) فقط در حالت dev بر روی باندل های worker اعمال خواهند شد و برای حالت build باید از این گزینه استفاده کنید.
این تابع باید نمونه‌های جدیدی از پلاگین‌ها را بازگرداند چون آن‌ها به‌صورت موازی در build های rollup اجرا می‌شوند. به همین دلیل، تغییر گزینه‌های config.worker در هوک config نادیده گرفته می‌شود.

## worker.rollupOptions

* **تایپ:** [`RollupOptions`](https://rollupjs.org/configuration-options/)

آپشن‌های Rollup برای ساخت باندل worker.

---

---
url: /guide/using-plugins.md
---
# استفاده از پلاگین‌ها

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

## اضافه کردن یک پلاگین

برای استفاده از یک پلاگین، باید آن را به `devDependencies` پروژه اضافه کرده و در آرایه `plugins` در فایل کانفیگ `vite.config.js` قرار دهید. به عنوان مثال، برای پشتیبانی از مرورگرهای قدیمی، می‌توان از پلاگین رسمی [‎@vitejs/plugin-legacy](https://github.com/vitejs/vite/tree/main/packages/plugin-legacy) استفاده کرد:

```
$ npm add -D @vitejs/plugin-legacy
```

```js twoslash [vite.config.js]
import legacy from '@vitejs/plugin-legacy'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    legacy({
      targets: ['defaults', 'not IE 11'],
    }),
  ],
})
```

آرایه `plugins` همچنین می‌تواند پیش‌تنظیماتی را بپذیرد که شامل چندین پلاگین به عنوان یک عنصر واحد هستند. این ویژگی برای موارد پیچیده‌تر (مثل یکپارچه‌سازی فریم‌ورک‌ها) که با استفاده از چندین پلاگین پیاده‌سازی می‌شوند، مفید است. آرایه‌ی پلاگین‌ها به طور داخلی به صورت تخت (flat) پردازش خواهد شد.

پلاگین‌های نادرست نادیده گرفته خواهند شد. این ویژگی می‌تواند برای فعال یا غیرفعال کردن راحت پلاگین‌ها مورد استفاده قرار گیرد.

## یافتن پلاگین‌ها

:::tip نکته
Vite هدف دارد تا پشتیبانی آماده از الگوهای رایج توسعه وب را فراهم کند. قبل از جستجو برای یک پلاگین Vite یا پلاگین سازگار با Rollup، پیشنهاد می‌شود راهنمای [ویژگی‌ها](../guide/features.md) را بررسی کنید. بسیاری از قابلیت‌هایی که در پروژه‌های Rollup نیاز به پلاگین دارند، در Vite به طور پیش‌فرض پشتیبانی می‌شوند.
:::

بخش [پلاگین‌ها](../plugins/) را برای اطلاعات بیشتر درباره پلاگین‌های رسمی بررسی کنید. پلاگین‌های جامعه (community) در [awesome-vite](https://github.com/vitejs/awesome-vite#plugins) لیست شده‌اند.

همچنین می‌توانید پلاگین‌هایی که از [کنوانسیون‌های توصیه‌شده](./api-plugin.md#conventions) پیروی می‌کنند را با استفاده از [جستجوی npm برای vite-plugin](https://www.npmjs.com/search?q=vite-plugin\&ranking=popularity) برای پلاگین‌های Vite یا [جستجوی npm برای rollup-plugin](https://www.npmjs.com/search?q=rollup-plugin\&ranking=popularity) برای پلاگین‌های Rollup پیدا کنید.

## ترتیب اعمال پلاگین

برای سازگاری با برخی از پلاگین‌های Rollup، ممکن است نیاز باشد ترتیب پلاگین‌ها را تغییر دهید یا آن‌ها را فقط در زمان بیلد اعمال کنید. این باید جزئیات پیاده‌سازی در سطح پلاگین‌های Vite باشد. شما می‌توانید موقعیت یک پلاگین را با استفاده از اصلاح‌کننده `enforce` تنظیم کنید:

* `pre`: اجرای پلاگین قبل از پلاگین‌های اصلی Vite
* پیش‌فرض: اجرای پلاگین بعد از پلاگین‌های اصلی Vite
* `post`: اجرای پلاگین بعد از پلاگین‌های build Vite

```js twoslash [vite.config.js]
import image from '@rollup/plugin-image'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    {
      ...image(),
      enforce: 'pre',
    },
  ],
})
```

برای اطلاعات دقیق، راهنمای [API پلاگین‌ها](./api-plugin.md#plugin-ordering) را بررسی کنید.

## فراخوانی شرطی

به طور پیش‌فرض، پلاگین‌ها برای هر دو حالت serve و build فراخوانی می‌شوند. در مواردی که نیاز است یک پلاگین به صورت شرطی فقط در زمان serve یا build اعمال شود، از ویژگی `apply` استفاده کنید تا فقط در زمان `'build'` یا `'serve'` فراخوانی شوند:

```js twoslash [vite.config.js]
import typescript2 from 'rollup-plugin-typescript2'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    {
      ...typescript2(),
      apply: 'build',
    },
  ],
})
```

## بیلد پلاگین‌ها

برای مشاهده مستندات مربوط به ایجاد پلاگین‌ها، راهنمای [API پلاگین‌ها](./api-plugin.md) را بررسی کنید.

---

---
url: /guide/api-environment-instances.md
---
# استفاده از نمونه‌های `Environment`

:::warning Experimental
رابط Environment API هنوز در مرحله‌ی آزمایشی (experimental) هست. با این حال، ما تلاش می‌کنیم بین نسخه‌های اصلی (major) پایداری این APIها را حفظ کنیم تا جامعه‌ی توسعه‌دهندگان بتوانند با آن‌ها کار کرده و تجربیات خود را بر اساس آن‌ها توسعه دهند. ما قصد داریم این APIهای جدید را در یکی از نسخه‌های اصلی آینده به حالت پایدار (stable) برسانیم. البته ممکن است در این فرآیند تغییرات شکننده (breaking changes) نیز اعمال شود، اما این کار زمانی انجام خواهد شد که پروژه‌ها و کتابخانه‌های وابسته فرصت کافی برای آزمایش و ارزیابی این قابلیت‌های جدید را داشته باشند.

منابع:

* [بحث و گفتگو](https://github.com/vitejs/vite/discussions/16358) جایی که ما در حال جمع‌آوری نظرات درباره APIهای جدید هستیم.
* [PR مربوط به Environment API](https://github.com/vitejs/vite/pull/16471) جایی که API جدید پیاده‌سازی و بررسی شده است.

لطفاً نظرات و بازخوردهای خود را با ما به اشتراک بگذارید.
:::

## دسترسی به محیط‌ها

در حالت توسعه (dev)، می‌توان با استفاده از `server.environments` به محیط‌های موجود در یک سرور توسعه دسترسی داشت:

```js
// دریافت کنید configureServer سرور را ایجاد کنید یا آن را از هوک
const server = await createServer(/* options */)

const clientEnvironment = server.environments.client
clientEnvironment.transformRequest(url)
console.log(server.environments.ssr.moduleGraph)
```

همچنین می‌توانید از طریق پلاگین‌ها به محیط فعلی دسترسی داشته باشید. برای جزئیات بیشتر، به [API محیط برای پلاگین‌ها](./api-environment-plugins.md#accessing-the-current-environment-in-hooks) مراجعه کنید.

## کلاس `DevEnvironment`

در حالت توسعه (dev)، هر محیط یک نمونه از کلاس `DevEnvironment` است:

```ts
class DevEnvironment {
  /**
   * Vite شناسه‌ی منحصربه‌فرد برای محیط در یک سرور
   * را در دسترس قرار می‌دهد 'ssr' و 'client' محیط‌های Vite ، به‌طور پیش‌فرض
   */
  name: string
  /**
   * کانال ارتباطی برای ارسال و دریافت پیام‌ها از
   * اجراکننده ماژول مرتبط در رانتام هدف
   */
  hot: NormalizedHotChannel
  /**
   * گراف نودهای ماژول، با روابط وارد شده بین
   * ماژول‌های پردازش شده و نتیجه کش شده کد پردازش شده
   */
  moduleGraph: EnvironmentModuleGraph
  /**
   * پلاگین‌های اضافه شده برای این محیط، از جمله پلاگین‌هایی که
   * مخصوص هر محیط ایجاد شده‌اند `create` با استفاده از هوک
   */
  plugins: Plugin[]
  /**
   * امکان حل و فصل، بارگذاری و تبدیل کد را از طریق
   * مسیر پردازش پلاگین های محیط فراهم می‌کند
   */
  pluginContainer: EnvironmentPluginContainer
  /**
   * گزینه های تنظیمات اضافه شده برای این محیط. گزینه‌های موجود در
   * دامنه‌ی کلی سرور به‌عنوان پیش‌فرض برای تمام محیط‌ها درنظر گرفته می‌شوند
   * optimizedDeps و external ، resolve conditions می‌توانند بازنویسی شوند. مانند
   */
  config: ResolvedConfig & ResolvedDevEnvironmentOptions

  constructor(
    name: string,
    config: ResolvedConfig,
    context: DevEnvironmentContext,
  )

  /**
   * را به یک شناسه تبدیل می‌کند، آن را بارگذاری کرده و URL آدرس
   * کد را از طریق مسیر پردازش پلاگین‌ها پردازش می‌کند
   * گراف ماژول نیز به‌روزرسانی می‌شود
   */
  async transformRequest(url: string): Promise<TransformResult | null>

  /**
   * یک درخواست را برای پردازش با اولویت پایین ثبت می‌کند. این کار
   * اطلاعاتی Vite برای جلوگیری از وابستگی‌های زنجیره‌ای مفید است. سرور
   * درباره‌ی ماژول‌های ایمپورت شده توسط درخواست‌های دیگر دارد، بنابراین می‌تواند
   * گراف ماژول را از پیش آماده کند تا ماژول‌ها هنگام درخواست، پردازش‌ شده باشند
   */
  async warmupRequest(url: string): Promise<void>
}
```

با `DevEnvironmentContext` به صورت زیر است:

```ts
interface DevEnvironmentContext {
  hot: boolean
  transport?: HotChannel | WebSocketServer
  options?: EnvironmentOptions
  remoteRunner?: {
    inlineSourceMap?: boolean
  }
  depsOptimizer?: DepsOptimizer
}
```

و با `TransformResult` به صورت زیر است:

```ts
interface TransformResult {
  code: string
  map: SourceMap | { mappings: '' } | null
  etag?: string
  deps?: string[]
  dynamicDeps?: string[]
}
```

یک نمونه از محیط در سرور Vite به شما امکان می‌دهد که یک URL را با استفاده از متد `environment.transformRequest(url)` پردازش کنید. این تابع از خط پردازش پلاگین‌ها برای تبدیل `url` به یک شناسه‌ی ماژول (`id`) استفاده می‌کند، آن را بارگذاری می‌کند (با خواندن فایل از فایل سیستم یا از طریق پلاگینی که یک ماژول مجازی را پیاده‌سازی کرده است) و سپس کد را تبدیل می‌کند. در حین تبدیل ماژول،ایمپورت‌های آن و دیگر اطلاعات متادیتا در گراف ماژول محیط ثبت می‌شوند، با ایجاد یا به‌روزرسانی نود ماژول مربوطه. پس از اتمام پردازش، نتیجه‌ی تبدیل نیز در ماژول ذخیره می‌شود.

:::info نام‌گذاری transformRequest
در نسخه‌ی کنونی این پیشنهاد، از `transformRequest(url)` و `warmupRequest(url)` استفاده می‌کنیم تا درک و بحث درباره‌ی آن برای کاربرانی که به API فعلی Vite عادت دارند، آسان‌تر باشد. پیش از انتشار، می‌توانیم فرصت را برای بازبینی این نام‌ها نیز غنیمت بشماریم. برای مثال، ممکن است نام آن را به `environment.processModule(url)` یا `environment.loadModule(url)` تغییر دهیم، مشابه `context.load(id)` در پلاگین‌های Rollup. در حال حاضر، حفظ نام‌های فعلی و به تعویق انداختن این بحث را بهتر می‌دانیم.
:::

## گراف‌های ماژول مجزا

هر محیط یک گراف ماژول ایزوله دارد. همه گراف‌های ماژول امضای یکسانی دارند، بنابراین می‌توان الگوریتم‌های کلی برای پیمایش یا پیمایش گراف بدون وابستگی به محیط پیاده‌سازی کرد. مثال خوب آن `hotUpdate` است. وقتی یک فایل تغییر می‌کند، گراف ماژول هر محیط بررسی می‌شود تا ماژول‌های تحت تأثیر را پیدا کند و HMR را به صورت مستقل برای هر محیط انجام دهد.

::: info نکته
Vite نسخه ۵ یک گراف ماژول مشترک بین کلاینت و SSR داشت. اگر یک نود هنوز پردازش نشده یا باطل شده باشد، نمی‌توان تشخیص داد که مربوط به محیط کلاینت، SSR، یا هر دو است. نودهای ماژول دارای برخی ویژگی‌های پیشونددار هستند، مانند `clientImportedModules` و `ssrImportedModules` (به‌علاوه `importedModules` که اجتماع هر دو را برمی‌گرداند). فیلد `importers` همه ایمپورترهای مربوط به هر دو محیط کلاینت و SSR را برای هر نود ماژول شامل می‌شود. هر نود ماژول همچنین دارای `transformResult` و `ssrTransformResult` است. لایه‌ای برای حفظ سازگاری به اکوسیستم اجازه می‌دهد تا از `server.moduleGraph` منسوخ شده به این مدل جدید مهاجرت کند.
:::

هر ماژول توسط یک نمونه از `EnvironmentModuleNode` نشان داده می‌شود. ممکن است ماژول‌ها در گراف بدون پردازش اولیه ثبت شوند (در این حالت، مقدار `transformResult` برابر `null` خواهد بود). فیلدهای `importers` و `importedModules` نیز پس از پردازش ماژول به‌روزرسانی می‌شوند.

```ts
class EnvironmentModuleNode {
  environment: string

  url: string
  id: string | null = null
  file: string | null = null

  type: 'js' | 'css'

  importers = new Set<EnvironmentModuleNode>()
  importedModules = new Set<EnvironmentModuleNode>()
  importedBindings: Map<string, Set<string>> | null = null

  info?: ModuleInfo
  meta?: Record<string, any>
  transformResult: TransformResult | null = null

  acceptedHmrDeps = new Set<EnvironmentModuleNode>()
  acceptedHmrExports: Set<string> | null = null
  isSelfAccepting?: boolean
  lastHMRTimestamp = 0
  lastInvalidationTimestamp = 0
}
```

`environment.moduleGraph` is an instance of `EnvironmentModuleGraph`:

```ts
export class EnvironmentModuleGraph {
  environment: string

  urlToModuleMap = new Map<string, EnvironmentModuleNode>()
  idToModuleMap = new Map<string, EnvironmentModuleNode>()
  etagToModuleMap = new Map<string, EnvironmentModuleNode>()
  fileToModulesMap = new Map<string, Set<EnvironmentModuleNode>>()

  constructor(
    environment: string,
    resolveId: (url: string) => Promise<PartialResolvedId | null>,
  )

  async getModuleByUrl(
    rawUrl: string,
  ): Promise<EnvironmentModuleNode | undefined>

  getModuleById(id: string): EnvironmentModuleNode | undefined

  getModulesByFile(file: string): Set<EnvironmentModuleNode> | undefined

  onFileChange(file: string): void

  onFileDelete(file: string): void

  invalidateModule(
    mod: EnvironmentModuleNode,
    seen: Set<EnvironmentModuleNode> = new Set(),
    timestamp: number = monotonicDateNow(),
    isHmr: boolean = false,
  ): void

  invalidateAll(): void

  async ensureEntryFromUrl(
    rawUrl: string,
    setIsSelfAccepting = true,
  ): Promise<EnvironmentModuleNode>

  createFileOnlyEntry(file: string): EnvironmentModuleNode

  async resolveUrl(url: string): Promise<ResolvedUrl>

  updateModuleTransformResult(
    mod: EnvironmentModuleNode,
    result: TransformResult | null,
  ): void

  getModuleByEtag(etag: string): EnvironmentModuleNode | undefined
}
```

---

---
url: /releases.md
---
# انتشارها

انتشارهای Vite از نسخه‌گذاری معنایی ([Semantic Versioning](https://semver.org/)) پیروی می‌کنند. آخرین نسخه‌ی پایدار Vite را می‌توانید در صفحه‌ی [npm](https://www.npmjs.com/package/vite) در npm ببینید.

فهرست کامل تغییرات نسخه‌های گذشته در [GitHub](https://github.com/vitejs/vite/blob/main/packages/vite/CHANGELOG.md) در دسترس است.

## چرخه انتشار

دروقع Vite چرخه‌ی انتشار ثابتی ندارد.

* نسخه‌های **پچ (Patch)** در صورت نیاز منتشر می‌شوند (معمولاً هر هفته).
* نسخه‌های **فرعی (Minor)** همیشه شامل ویژگی‌های جدید هستند و در صورت نیاز منتشر می‌شوند. این نسخه‌ها همیشه یک مرحله پیش‌انتشار بتا (pre-release) دارند (معمولاً هر دو ماه یک‌بار).
* نسخه‌های **اصلی (Major)** معمولاً با [برنامه پایان عمر (EOL) Node.js](https://endoflife.date/nodejs) هماهنگ هستند و از قبل اعلام می‌شوند. این نسخه‌ها پس از بحث‌های بلندمدت با اکوسیستم منتشر شده و مراحل پیش‌انتشار آلفا و بتا را طی می‌کنند (معمولاً هر سال یک‌بار).

بازه‌های نسخه‌ی Vite که توسط تیم Vite پشتیبانی می‌شوند به‌صورت خودکار بر اساس موارد زیر تعیین می‌شوند:

* نسخه‌ی **Current Minor** به‌طور منظم رفع اشکال (bug fixe) می‌شود.
* نسخه‌ی **Previous Major** (فقط آخرین نسخه‌ی Minor آن) و **Previous Minor** اصلاحات مهم و پچ‌های امنیتی دریافت می‌کنند.
* نسخه‌های  **Second-to-last Major** و **Second-to-last Minor** فقط پچ‌های امنیتی دریافت می‌کنند.
* تمام نسخه‌های قبل از این بازه‌ها دیگر پشتیبانی نمی‌شوند.

برای مثال، اگر آخرین نسخه‌ی Vite برابر با ۵.۳.۱۰ باشد:

* پچ‌های معمولی برای `vite@5.3.` منتشر می‌شوند.
* اصلاحات مهم و پچ‌های امنیتی به `vite@4` و `.vite@5.2` منتقل می‌شوند.
* پچ‌های امنیتی همچنین به `vite@3` و `vite@5.1` منتقل می‌شوند.
* نسخه‌های `vite@2` و `v‍ite@5.0` دیگر پشتیبانی نمی‌شوند. کاربران باید برای دریافت به‌روزرسانی‌ها، نسخه‌ی خود را ارتقا (upgrade) دهند.

ما توصیه می‌کنیم Vite را به‌صورت منظم به‌روزرسانی کنید. هنگام ارتقا به هر نسخه‌ی اصلی (Major)، [راهنمای مهاجرت](https://vite.dev/guide/migration.html) را بررسی کنید. تیم Vite با پروژه‌های اصلی اکوسیستم همکاری نزدیکی دارد تا کیفیت نسخه‌های جدید را تضمین کند. نسخه‌های جدید Vite قبل از انتشار، از طریق پروژه [vite-ecosystem-ci project](https://github.com/vitejs/vite-ecosystem-ci) تست می‌شوند. بیشتر پروژه‌هایی که از Vite استفاده می‌کنند، باید بتوانند سریعاً پشتیبانی ارائه دهند یا به نسخه‌های جدید مهاجرت کنند.

## حالات خاص در نسخه‌گذاری معنایی

### تعاریف تایپ اسکریپت

ممکن است بین نسخه‌های Minor تغییرات ناسازگار در تعاریف تایپ اسکریپت ارائه دهیم. دلیل این موضوع این است که:

* گاهی خود تایپ اسکریپت بین نسخه‌های Minor تغییرات ناسازگار دارد و ما ممکن است برای پشتیبانی از نسخه‌های جدیدتر، تایپ‌ها را تغییر دهیم.
* گاهی لازم است از ویژگی‌هایی استفاده کنیم که فقط در نسخه‌های جدیدتر تایپ اسکریپت وجود دارند، بنابراین حداقل نسخه‌ی موردنیاز تایپ‌اسکریپت را افزایش می‌دهیم.
* اگر از تایپ اسکریپت استفاده می‌کنید، می‌توانید بازه نسخه semver را قفل کنید روی نسخه فرعی فعلی و هنگام انتشار نسخه Minor جدید Vite به‌صورت دستی ارتقا دهید.

### esbuild

[esbuild](https://esbuild.github.io/) هنوز به نسخه ۱.۰.۰ نرسیده و گاهی تغییرات ناسازگار دارد که برای دسترسی به ویژگی‌ها و بهبودهای عملکردی جدید باید آن‌ها را در Vite بگنجانیم. ممکن است نسخه esbuild را در یک نسخه‌ی Minor در Vite افزایش دهیم.

### نسخه‌های ناپایدار Node.js

نسخه‌های ناپایدار Node.js (شماره فرد) به‌عنوان بخشی از تست‌های CI Vite آزمایش نمی‌شوند، اما تا قبل از [پایان عمر](https://endoflife.date/nodejs) آن‌ها باید کار کنند.

## پیش‌انتشارها

نسخه‌های Minor معمولاً از چندین نسخه‌ی بتا (با تعداد غیرثابت) عبور می‌کنند. نسخه‌های Major نیز یک مرحله آلفا و یک مرحله بتا خواهند داشت.

پیش‌انتشارها به پذیرندگان اولیه و نگهدارندگان اکوسیستم اجازه می‌دهند تا تست‌های یکپارچگی و پایداری انجام دهند و بازخورد بدهند. هیچوقت از پیش‌انتشارها در محیط production استفاده نکنید. همه پیش‌انتشارها ناپایدار محسوب می‌شوند و ممکن است تغییرات ناسازگار داشته باشند. همیشه هنگام استفاده از پیش‌انتشارها نسخه دقیق را قفل کنید.

## فرایند منسوخ شدن

ما به‌صورت دوره‌ای ویژگی‌هایی که در نسخه‌های Minor با گزینه‌های بهتر جایگزین شده‌اند را منسوخ می‌کنیم. ویژگی‌های منسوخ‌شده همچنان با یک هشدار یا لاگ کار می‌کنند و در نسخه‌ی Minor بعدی پس از اعلام منسوخ‌شدن حذف خواهند شد. [راهنمای مهاجرت](https://vite.dev/guide/migration.html) هر نسخه‌ی Major، این حذف‌ها را فهرست کرده و مسیر ارتقا را مستند می‌کند.ض

## ویژگی‌های آزمایشی

برخی ویژگی‌ها هنگام انتشار در نسخه پایدار Vite به‌عنوان آزمایشی علامت‌گذاری می‌شوند. ویژگی‌های آزمایشی به ما کمک می‌کنند تا تجربه‌ی واقعی کاربران را جمع‌آوری کنیم و طراحی نهایی آن‌ها را بهبود دهیم. هدف این است که کاربران با استفاده در محیط تولید بازخورد دهند. خود ویژگی‌های آزمایشی ناپایدار هستند و فقط باید به‌صورت کنترل‌شده استفاده شوند. این ویژگی‌ها ممکن است بین نسخه‌های Minor تغییر کنند، بنابراین کاربران هنگام استفاده باید نسخه Vite خود را قفل کنند. برای هر ویژگی آزمایشی، [بحثی در GitHub](https://github.com/vitejs/vite/discussions/categories/feedback?discussions_q=is%3Aopen+label%3Aexperimental+category%3AFeedback) ایجاد خواهیم کرد.

---

---
url: /changes/per-environment-apis.md
---
# انتقال به APIهای مخصوص هر محیط

::: tip بازخورد
بازخورد خود را در [بحث بازخورد API محیط](https://github.com/vitejs/vite/discussions/16358) با ما در میان بگذارید.
:::

چندین API از `ViteDevServer` که به گراف ماژول‌ها و تبدیل ماژول‌ها مرتبط بودند، به نمونه‌های `DevEnvironment` منتقل شده‌اند.

دامنه تأثیر: `نویسندگان افزونه‌های Vite`

::: warning منسوخ شدن در آینده
نمونه `Environment` برای اولین بار در نسخه `v6.0` معرفی شد. منسوخ شدن `server.moduleGraph` و سایر متدهایی که اکنون در محیط‌ها قرار دارند، برای یکی از نسخه‌های اصلی (major) آینده برنامه‌ریزی شده است. هنوز توصیه نمی‌کنیم از متدهای سرور فاصله بگیرید. برای شناسایی استفاده خود، این موارد را در تنظیمات Vite خود تنظیم کنید:

```ts
future: {
  removeServerModuleGraph: 'warn',
  removeServerTransformRequest: 'warn',
}
```

:::

## انگیزه

در Vite نسخه ۵ و قبل از آن، یک سرور توسعه Vite همیشه دو محیط (`client` و `ssr`) داشت. گراف `server.moduleGraph` شامل ماژول‌هایی از هر دو این محیط‌ها به‌صورت مخلوط بود. گره‌ها از طریق لیست‌های `clientImportedModules` و `ssrImportedModules` به هم متصل بودند (اما یک لیست واحد `importers` برای هر کدام نگهداری می‌شد). یک ماژول تبدیل‌شده با یک `id` و یک مقدار بولین `ssr` نمایش داده می‌شد. این مقدار بولین باید به APIها منتقل می‌شد، به عنوان مثال `server.moduleGraph.getModuleByUrl(url, ssr)` و `server.transformRequest(url, { ssr })`.

در Vite نسخه ۶، اکنون امکان ایجاد هر تعداد محیط سفارشی (`client`، `ssr`، `edge` و غیره) وجود دارد. یک مقدار بولین ساده `ssr` دیگر کافی نیست. به جای تغییر APIها به شکلی مانند `server.transformRequest(url, { environment })`، این متدها را به نمونه محیط منتقل کردیم تا بتوان آن‌ها را بدون نیاز به سرور توسعه Vite فراخوانی کرد.

## راهنمای مهاجرت

* `server.moduleGraph` -> [`environment.moduleGraph`](/guide/api-environment-instances#separate-module-graphs)
* `server.transformRequest(url, ssr)` -> `environment.transformRequest(url)`
* `server.warmupRequest(url, ssr)` -> `environment.warmupRequest(url)`

---

---
url: /plugins.md
---
# پلاگین‌ها

:::tip نکته
Vite هدف دارد پشتیبانی پیش‌فرض از الگوهای رایج توسعه وب را ارائه دهد. قبل از جست‌وجو برای یافتن پلاگین‌های Vite یا پلاگین‌های سازگار با Rollup، [راهنمای ویژگی‌ها](../guide/features.md) را بررسی کنید. بسیاری از مواردی که در پروژه‌های Rollup نیاز به استفاده از پلاگین دارند، در Vite به‌صورت پیش‌فرض پوشش داده شده‌اند.
:::

برای کسب اطلاعات بیشتر درباره نحوه استفاده از پلاگین‌ها، بخش [استفاده از پلاگین‌ها](../guide/using-plugins) را مطالعه کنید.

## Official Plugins

### [@vitejs/plugin-vue](https://github.com/vitejs/vite-plugin-vue/tree/main/packages/plugin-vue)

* از Vue 3 Single File Components پشتیبانی می‌کند .

### [@vitejs/plugin-vue-jsx](https://github.com/vitejs/vite-plugin-vue/tree/main/packages/plugin-vue-jsx)

* از Vue 3 JSX پشتیبانی می‌کند (با استفاده از [تبدیل اختصاصی Babel](https://github.com/vuejs/jsx-next)).

### [@vitejs/plugin-vue2](https://github.com/vitejs/vite-plugin-vue2)

* از Vue 2.7 Single File Components پشتیبانی می‌کند.

### [@vitejs/plugin-vue2-jsx](https://github.com/vitejs/vite-plugin-vue2-jsx)

* از Vue 2.7 JSX پشتیبانی می‌کند (با استفاده از [تبدیل اختصاصی Babel](https://github.com/vuejs/jsx-vue2/)).

### [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/tree/main/packages/plugin-react)

* با استفاده از esbuild و Babeldدر نهایت HMR سریع و پکیجی کم‌حجم ارائه می‌دهد، در حالی که امکان استفاده از پایپ‌لاین تبدیل Babel را هم دارد. در فرآیند ساخت (build)، اگر پلاگین‌های اضافی Babel اضافه نشوند، تنها از esbuild استفاده می‌شود.

### [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react-swc)

* در مرحله توسعه، Babel با SWC جایگزین می‌شود. در مرحله بیلد پرواکشن، اگر از پلاگین‌ها استفاده شود، SWC+esbuild به کار گرفته می‌شوند و در غیر این صورت فقط از esbuild استفاده می‌شود. برای پروژه‌های بزرگ که به اکسننشن های غیراستاندارد React نیازی ندارند، زمان راه‌اندازی اولیه (cold start) و تعویض ماژول‌ها در حین توسعه (HMR) می‌توانند به طور قابل توجهی سریع‌تر باشند.

### [@vitejs/plugin-legacy](https://github.com/vitejs/vite/tree/main/packages/plugin-legacy)

* پشتیبانی از مرورگرهای قدیمی برای بیلد پرواکشن فراهم می‌کند.

## Community Plugins

[awesome-vite](https://github.com/vitejs/awesome-vite#plugins) را بررسی کنید - شما همچنین می‌توانید یک درخواست PR ارسال کنید تا پلاگین‌های خود را در آنجا اضافه کنید.

## Rollup Plugins

[پلاگین‌های Vite](../guide/api-plugin) توسعه یافته از اینترفیس پلاگین‌های Rollup هستند. برای جزئیات بیشتر، به بخش [سازگاری با پلاگین‌های Rollup](../guide/api-plugin#rollup-plugin-compatibility) مراجعه کنید.

---

---
url: /changes/shared-plugins-during-build.md
---
# پلاگین‌های مشترک در زمان Build

::: tip بازخورد
نظرات خود را در [بازخورد درباره Environment API](https://github.com/vitejs/vite/discussions/16358) با ما به اشتراک بگذارید.
:::

برای اطلاعات بیشتر به بخش [Shared plugins during build](/guide/api-environment-plugins.md#shared-plugins-during-build) مراجعه کنید.

**دامنه تأثیر:** نویسندگان افزونه‌های Vite

::: warning تغییر پیش‌فرض در آینده
ویژگی `builder.sharedConfigBuild` برای اولین بار در نسخه `v6.0` معرفی شد. می‌توانید آن را روی `true` تنظیم کنید تا بررسی کنید افزونه‌هایتان با پیکربندی مشترک چگونه کار می‌کنند. ما به دنبال بازخورد هستیم تا پس از آمادگی اکوسیستم افزونه‌ها، این مقدار پیش‌فرض را در نسخه‌ای اصلی از Vite تغییر دهیم.
:::

## انگیزه

هماهنگ کردن مسیر پلاگین‌ها در محیط توسعه و ساخت.

## راهنمای مهاجرت

برای اینکه بتوانید پلاگین‌ها را در محیط‌های مختلف به اشتراک بگذارید، وضعیت پلاگین باید بر اساس محیط جاری کلیدگذاری شود. پلاگینی به شکل زیر تعداد ماژول‌های تبدیل‌شده در همه محیط‌ها را محاسبه می‌کند.

```js
function CountTransformedModulesPlugin() {
  let transformedModules
  return {
    name: 'count-transformed-modules',
    buildStart() {
      transformedModules = 0
    },
    transform(id) {
      transformedModules++
    },
    buildEnd() {
      console.log(transformedModules)
    },
  }
}
```

اگر به جای آن بخواهیم تعداد ماژول‌های تبدیل‌شده را برای هر محیط شمارش کنیم، باید یک Map نگه داریم:

```js
function PerEnvironmentCountTransformedModulesPlugin() {
  const state = new Map<Environment, { count: number }>()
  return {
    name: 'count-transformed-modules',
    perEnvironmentStartEndDuringDev: true,
    buildStart() {
      state.set(this.environment, { count: 0 })
    }
    transform(id) {
      state.get(this.environment).count++
    },
    buildEnd() {
      console.log(this.environment.name, state.get(this.environment).count)
    }
  }
}
```

برای ساده‌سازی این الگو، Vite یک ابزار کمکی به نام `perEnvironmentState` را اکسپورت می‌کند:

```js
function PerEnvironmentCountTransformedModulesPlugin() {
  const state = perEnvironmentState<{ count: number }>(() => ({ count: 0 }))
  return {
    name: 'count-transformed-modules',
    perEnvironmentStartEndDuringDev: true,
    buildStart() {
      state(this).count = 0
    }
    transform(id) {
      state(this).count++
    },
    buildEnd() {
      console.log(this.environment.name, state(this).count)
    }
  }
}
```

---

---
url: /guide/dep-pre-bundling.md
---
# پیش‌بسته‌بندی(پیش‌باندل) وابستگی

زمانی‌که شما `vite` را برای اولین بار اجرا می‌کنید Vite وابستگی‌های پروژه شما را قبل از لود لوکال سایت شما، پیش‌بسته‌بندی می‌کند. این فرایند به صورت پیشفرض، اتوماتیک و شفاف انجام می‌شود.

## چرایی

این چیزی‌است که در Vite "پیش‌بسته‌بندی وابستگی" می‌نامیم. این فرایند دو هدف دارد:

1. **سازگاری CommonJS and UMD:**  در زمان توسعه، در حالت Vite dev تمام کدها به شکل ماژول native ESM آماده می‌شوند. پس Vite باید وابستگی‌هایی که به شکل CommonJs یا UMD هستند را ابتدا به ESM تبدیل کند.

   زمانی که Vite دارد وابستگی‌های CommonJsای را  تبدیل می‌کند،  آنالیز هوشمندانه‌ی import را اجرا می‌کند تا importهای نامگذاری شده‌ی ماژول‌های CommonJS همانطور که انتظار می‌رود بتوانند کار کنند حتی اگر export ها به صورت داینامیک نسبت داده شده باشند (مانند React):

   ```js
   // مطابق انتظار کار می‌کند
   import React, { useState } from 'react'
   ```

2. **بازدهی:** Vite وابستگی‌های ESM با ماژول‌های داخلی بسیار را تبدیل به یک ماژول می‌کند تا بازدهی‌ لودهای بعدی صفحه را بهبود دهد.

   بعضی از پکیج‌ها، ماژول‌های ES خود را به شکل چندین فایل جداگانه که یکدیگر را import کرده‌اند بیلد کرده و همراه خود می‌آورند. برای مثال، [`lodash-es` بیش از ۶۰۰ ماژول داخلی دارد](https://unpkg.com/browse/lodash-es/)! وقتی ما این کار را می‌کنیم`import { debounce } from 'lodash-es'‎`، مرورگر بیش از ۶۰۰ درخواست HTTP را همزمان ارسال می‌کند! حتی با وجود اینکه سرور مشکلی با هندل کردن آنها ندارد، تعداد زیاد درخواست‌ها باعث ازدحام در سمت مرورگر می‌شود که همین امر باعث کندتر لود شدن صفحه به شکل قابل‌ ملاحظه‌ای می‌گردد.

   به جای این، با پیش‌بسته‌بندیِ `lodash-es` در یک ماژول حالا ما تنها به یک HTTP درخواست نیاز داریم!

::: tip نکته
پیش‌بسته‌بندی وابستگی فقط در حالت توسعه(development) اعمال می‌شود و از `esbuild` برای تبدیل وابستگی‌ها به ESM استفاده می‌شود. در حالت production به جای آن از ‎`@rollup/plugin-commonjs` استفاده می‌شود.
:::

## یافتن خودکار وابستگی

اگر کشی موجود نباشد، Vite کد شما را می‌کاود و به صورت اتوماتیک وابستگی‌های importها را پیدا می‌کند(مانند "bare imports" که انتظار می‌رود از `node_modules` خوانده شود) و از این importهای پیدا شده به عنوان نقاط ورودی پیش‌بسته‌بندی استفاده کند. فرایند پیش‌بسته‌بندی از `esbuild` استفاده می‌کند پس معمولا بسیار سریع است.

بعد از شروع به‌کار سرور، اگر یک وابستگی import جدید مشاهده شود که در کش موجود نیست، Vite دوباره فرایند پیش‌بسته‌بندی وابستگی را اجرا کرده و در صورت نیاز صفحه را مجددا لود می‌کند.

## مخزن یکپارچه (Monorepos) و وابستگی‌های مرتبط(Linked Dependencies)

در یک مخزن یکپارچه، یک وابستگی ممکن است به یک پکیج در همان مخزن مرتبط باشد. Vite به صورت خودکار وابستگی‌هایی که از `node_modules` فراخوانی نمی‌شوند را شناسایی کرده و با آن وابستگی مانند یک سورس کد عمل می‌کند. این کار تلاشی برای بسته‌بندی کردن آن وابستگی مرتبط نیست بلکه آنالیز لیست وابستگی‌ِ آن وابستگی مرتبط است.

گرچه، این امر نیازمند این است که وابستگی مرتبط به صورت ESM export شده باشد. اگر به این شکل نبود شما می‌توانید وابستگی را در تنظیماتتان به [`optimizeDeps.include`](/config/dep-optimization-options.md#optimizedeps-include)و[`build.commonjsOptions.include`](/config/build-options.md#build-commonjsoptions) اضافه کنید.

```js twoslash [vite.config.js]
import { defineConfig } from 'vite'
// ---cut---
export default defineConfig({
  optimizeDeps: {
    include: ['linked-dep'],
  },
  build: {
    commonjsOptions: {
      include: [/linked-dep/, /node_modules/],
    },
  },
})
```

هنگامی که تغییراتی در وابستگیِ مرتبط می‌دهید، dev server را با قابلیت دستور ‎`--force` ریست کنید تا تغییرات اعمال شوند.

## اختصاصی‌کردن رفتار

روش‌های پیشفرض کشف وابستگی ممکن است همیشه مطلوب نباشند. در مواردی که شما مشخصا می‌خواهید وابستگی ها را از لیست include/exclude کنید از [`optimizeDeps` config options](/config/dep-optimization-options.md) استفاده کنید.

یک مورد مرسوم برای `optimizeDeps.include` یا `optimizeDeps.exclude` زمانی است که شما یک importای دارید که مستقیما قابل کشف در سورس کد نیست. برای مثال، شاید آن import در نتیجه‌ی تغییر پلاگینی بوجود آمده است. این به این معنا است که Vite قادر به یافتن آن import در اسکن اولیه نخواهد بود - بلکه تنها زمانی که  توسط مرورگر درخواست داده شود و تغییر(transformed) پیدا کند قابل مشاهده می‌گردد. این موضوع باعث می‌شود سرور بلافاصله بعد از شروع، دوباره بسته‌بندی را انجام دهد.

هر دو حالت `include` و `exclude` می‌توانند برای این هدف مورد استفاده قرار گیرند. اگر وابستگی بزرگ باشد (به همراه ماژول‌های داخلی بسیاری) یا CommonJS باشد، پس شما باید آنرا include کنید؛ اگر وابستگی کوچک است و همین حالا هم ماژول ESM معتبری است، می‌توانید آنرا exclude کنید و اجازه دهید که مرورگر مستقیما آن‌ را لود کند.

همچنین شما می‌توانید esbuild را بیشتر نیز با [قابلیت`optimizeDeps.esbuildOptions`](/config/dep-optimization-options.md#optimizedeps-esbuildoptions) سفارشی‌سازی کنید. برای مثال، اضافه کردن یک پلاگین esbuild برای هندل کردن فایل‌های مخصوص در وابستگی‌ها یا تغییر [build `target`](https://esbuild.github.io/api/#target).

## کش‌کردن

### کش فایل‌سیستم (File System)

Vite وابستگی‌های پیش‌بسته‌بندی را در `node_modules/.vite` کش می‌کند. Vite اینکه نیاز به اجرای مجدد مرحله پیش‌بسته‌بندی هست یا نه را بر اساس چند منبع تشخیص می‌دهد:

* محتوای package manager lockfile مثل: `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml` یا `bun.lockb`.
* زمان تغییر پوشه patches.
* فیلدهای مرتبط در `vite.config.js`، در صورت وجود.
* مقدار `NODE_ENV`.

مرحله پیش‌بسته‌بندی تنها زمانی نیاز به اجرای مجدد دارد که یکی از موارد بالا تغییر کرده باشد.

اگر به دلایلی می‌خواهید که Vite را مجبور به انجام پیش‌بسته‌بندی وابستگی‌ کنید، یا می‌توانید سرور dev را با گزینه دستور ‎`--force` اجرا کنید یا اینکه فایل `node_modules/.vite` پوشه کش را به صورت دستی پاک کنید.

### کش مرورگر {#browser-cache}

فراخوانی درخواست‌های وابستگی به خوبی با هدرهای HTTP `max-age=31536000,immutable` کش می‌شوند تا بازدهی بارگیری مجدد صفحه در حالت dev افزایش پیدا کند. وقتی که کش شدند، این درخواست‌ها دیگر هرگز به سرور dev ارسال نمی‌شوند. آنها زمانی که یک نسخه دیگر نصب شود به صورت خودکار با اضافه شدن ورژن کوئری (version query) ، غیرمعتبر می‌شوند(همانند آنچه که در لاک‌فایل پکیج منیجر شما دیده می‌شود). اگر می‌خواهید که وابستگی‌های خود را با تغییرات لوکال دیباگ کنید می‌توانید:

1. غیرفعال کردن موقت کش در تب Network در devtools مرورگر خود.
2. اجرای مجدد سرور dev با علامت ‎`--force` برای پیش‌بسته‌بندی مجدد وابستگی‌ها.
3. بارگیری مجدد صفحه.

---

---
url: /config.md
---

# پیکربندی Vite

هنگام اجرای `vite` از خط فرمان، Vite به‌طور خودکار تلاش می‌کند تا فایلی با نام `vite.config.js` را در [ریشه پروژه](/guide/#index-html-و-ریشه-root-پروژه) پیدا کند (پسوندهای دیگر JS و TS نیز پشتیبانی می‌شوند).

ساده‌ترین فایل پیکربندی به این شکل است:

```js [vite.config.js]
export default {
  // گزینه‌های پیکربندی
}
```

Vite از سینتکس ماژول‌های ES در فایل پیکربندی پشتیبانی می‌کند، حتی اگر پروژه از ESM بومی Node استفاده نکند، مثلاً `"type": "module"` در `package.json` نباشد. در این حالت، فایل پیکربندی پیش از بارگذاری به‌طور خودکار پیش‌پردازش می‌شود.

همچنین می‌توانید با استفاده از گزینه `config--` در CLI، فایل پیکربندی خاصی را مشخص کنید (فایل با توجه به مسیر کاری جاری (`cwd`) تفسیر و خوانده می‌شود):

```bash
vite --config my-config.js
```

::: tip بارگذاری پیکربندی
به‌طور پیش‌فرض، Vite از `esbuild` برای باندل کردن پیکربندی به یک فایل موقت و بارگذاری آن استفاده می‌کند. این ممکن است در مونوریپوها هنگام ایمپورت فایل‌های TypeScript مشکل ایجاد کند. اگر با این روش مشکلی داشتید، می‌توانید با `configLoader runner--` از [module runner](/guide/api-environment-runtimes.html#modulerunner) استفاده کنید که فایل موقتی ایجاد نمی‌کند و فایل‌ها را در لحظه تبدیل می‌کند. توجه کنید که module runner از CJS در فایل‌های پیکربندی پشتیبانی نمی‌کند، اما پکیج‌های خارجی CJS باید به‌طور عادی کار کنند.

همچنین، اگر از محیطی استفاده می‌کنید که TypeScript را پشتیبانی می‌کند (مثلاً `node --experimental-strip-types`) یا فقط جاوااسکریپت ساده می‌نویسید، می‌توانید با `configLoader native--` از ران‌تایم بومی محیط برای بارگذاری فایل پیکربندی استفاده کنید. توجه داشته باشید که تغییرات در ماژول‌های ایمپورت‌شده توسط فایل پیکربندی تشخیص داده نمی‌شوند و سرور Vite به‌طور خودکار ری‌استارت نمی‌شود.
:::

## هوشمندی پیکربندی (Intellisense)

از آنجا که Vite با تایپ‌های TypeScript ارائه می‌شود، می‌توانید از هوشمندی IDE خود با استفاده از نکات تایپ jsdoc بهره ببرید:

```js
/** @type {import('vite').UserConfig} */
export default {
  // ...
}
```

یا می‌توانید از تابع کمکی `defineConfig` استفاده کنید که بدون نیاز به توضیحات jsdoc، هوشمندی را فراهم می‌کند:

```js
import { defineConfig } from 'vite'

export default defineConfig({
  // ...
})
```

Vite همچنین از فایل‌های پیکربندی TypeScript پشتیبانی می‌کند. می‌توانید از `vite.config.ts` با تابع کمکی `defineConfig` یا عملگر `satisfies` استفاده کنید:

```ts
import type { UserConfig } from 'vite'

export default {
  // ...
} satisfies UserConfig
```

## پیکربندی شرطی

اگر پیکربندی نیاز به تعیین شرطی گزینه‌ها بر اساس دستور (`serve` یا `build`)، [حالت](/guide/env-and-mode#modes) استفاده‌شده، ساخت SSR (`isSsrBuild`) یا پیش‌نمایش ساخت (`isPreview`) داشته باشد، می‌تواند به جای آبجکت، یک تابع صادر کند:

```js twoslash
import { defineConfig } from 'vite'
// ---cut---
export default defineConfig(({ command, mode, isSsrBuild, isPreview }) => {
  if (command === 'serve') {
    return {
      // پیکربندی خاص توسعه
    }
  } else {
    // command === 'build'
    return {
      // پیکربندی خاص ساخت
    }
  }
})
```

در API Vite، مقدار `command` در طول توسعه `serve` است (همچنین در CLI نام‌های مستعار [`vite`](/guide/cli#vite) و `vite dev` و `vite serve` را داریم) و هنگام ساخت برای تولید، `build` است ([`vite build`](/guide/cli#vite-build)).

`isSsrBuild` و `isPreview` پرچم‌های اختیاری اضافی برای تمایز نوع دستورهای `build` و `serve` هستند. برخی ابزارهایی که پیکربندی Vite را بارگذاری می‌کنند ممکن است از این پرچم‌ها پشتیبانی نکنند و به جای آن `undefined` ارسال کنند. بنابراین توصیه می‌شود از مقایسه صریح با `true` و `false` استفاده کنید.

## پیکربندی ناهمگام

اگر پیکربندی نیاز به فراخوانی توابع ناهمگام داشته باشد، می‌تواند یک تابع ناهمگام صادر کند. این تابع ناهمگام همچنین می‌تواند از طریق `defineConfig` برای پشتیبانی بهتر از هوشمندی منتقل شود:

```js twoslash
import { defineConfig } from 'vite'
// ---cut---
export default defineConfig(async ({ command, mode }) => {
  const data = await asyncFunction()
  return {
    // vite پیکربندی
  }
})
```

## استفاده از متغیرهای محیطی در پیکربندی

متغیرهای محیطی به‌طور معمول از `process.env` قابل دسترسی هستند.

توجه داشته باشید که Vite به‌طور پیش‌فرض فایل‌های `‎.env` را بارگذاری نمی‌کند، زیرا فایل‌های قابل بارگذاری تنها پس از ارزیابی پیکربندی Vite مشخص می‌شوند، مثلاً گزینه‌های `root` و `envDir` بر رفتار بارگذاری تأثیر می‌گذارند. با این حال، می‌توانید از تابع کمکی صادرشده `loadEnv` برای بارگذاری فایل `env.` خاص در صورت نیاز استفاده کنید.

```js twoslash
import { defineConfig, loadEnv } from 'vite'

export default defineConfig(({ mode }) => {
  // .در دایرکتوری کاری جاری بارگذاری کن `mode` را بر اساس env فایل
  // ،`VITE_` ها بدون توجه به پیشوند env برای بارگذاری همه
  // .پارامتر سوم را به '' تنظیم کن
  const env = loadEnv(mode, process.cwd(), '')
  return {
    // پیکربندی vite
    define: {
      __APP_ENV__: JSON.stringify(env.APP_ENV),
    },
  }
})
```

## دیباگ کردن فایل پیکربندی در VS Code

وقتی از رفتار پیش‌فرض `configLoader bundle--`استفاده می‌شه، Vite فایل پیکربندی موقتی تولیدشده را در پوشه `node_modules/.vite-temp` می‌نویسد و هنگام تنظیم نقاط توقف برای دیباگ در فایل پیکربندی Vite، خطای "فایل پیدا نشد" رخ می‌دهد. برای رفع این مشکل، پیکربندی زیر را به `vscode/settings.json.` اضافه کنید:

```json
{
  "debug.javascript.terminalOptions": {
    "resolveSourceMapLocations": [
      "${workspaceFolder}/**",
      "!**/node_modules/**",
      "**/node_modules/.vite-temp/**"
    ]
  }
}
```

---

---
url: /changes.md
---
# تغییرات اساسی

لیست تغییرات اساسی در Vite شامل منسوخ شدن API‌ها، حذف‌ها، و تغییرات. بیشتر تغییرات زیر را می‌توانید با استفاده از [گزینه `آینده`](/config/shared-options.html#future) در تنظیمات Vite خود به‌صورت اختیاری فعال کنید.

## برنامه‌ریزی شده

این تغییرات برای نسخه اصلی بعدی Vite برنامه‌ریزی شده‌اند. هشدارهای مربوط به منسوخ شدن یا استفاده در صورت امکان شما را راهنمایی خواهند کرد و ما با نویسندگان فریم‌ورک‌ها، افزونه‌ها و کاربران در ارتباط هستیم تا این تغییرات را اعمال کنیم.

* *هنوز هیچ تغییر برنامه‌ریزی شده‌ای وجود ندارد*

## قابل توجه

این تغییرات در حال بررسی هستند و اغلب شامل API‌های آزمایشی می‌باشند که هدف آن‌ها بهبود الگوهای استفاده فعلی است. از آنجا که تمامی تغییرات در اینجا ذکر نشده‌اند، لطفاً برای مشاهده لیست کامل به [Experimental Label in Vite GitHub Discussions](https://github.com/vitejs/vite/discussions/categories/feedback?discussions_q=label%3Aexperimental+category%3AFeedback) مراجعه کنید.

ما توصیه نمی‌کنیم که هنوز به این API‌ها سوئیچ کنید. این API‌ها در Vite گنجانده شده‌اند تا به ما در جمع‌آوری بازخورد کمک کنند. لطفاً این پیشنهادها را بررسی کنید و در بحث‌های مرتبط در GitHub به ما اطلاع دهید که چگونه در موارد استفاده شما کار می‌کنند.

* [`this.environment` در هوک‌ها](/changes/this-environment-in-hooks)
* [هوک پلاگین `hotUpdate`برای HMR](/changes/hotupdate-hook)
* [انتقال به API‌های مخصوص هر محیط](/changes/per-environment-apis)
* [SSR با استفاده از `ModuleRunner` API](/changes/ssr-using-modulerunner)
* [اشتراک‌گذاری پلاگین‌ها در حین ساخت (build)](/changes/shared-plugins-during-build)

## گذشته

تغییرات زیر اعمال شده یا لغو گردیده‌اند. این تغییرات در نسخه اصلی فعلی دیگر معتبر یا قابل استفاده نیستند.

* *هنوز هیچ تغییر گذشته‌ای وجود ندارد*

---

---
url: /guide/why.md
---
# چرا Vite

## مشکلات

قبل از اینکه ماژول‌های ES در مرورگرها در دسترس باشند، توسعه‌دهندگان مکانیزم بومی برای نوشتن جاوااسکریپت به صورت ماژولار نداشتند. به همین دلیل همه با مفهوم "bundling (بسته بندی)" آشنا هستیم: استفاده از ابزارهایی که ماژول‌های سورس کد ما را جستجو، پردازش و در فایل‌هایی که می‌توانند در مرورگر اجرا شوند، ادغام می‌کنند.

با گذشت زمان، ما ابزارهایی مانند [Rollup](https://rollupjs.org) ، [webpack](https://webpack.js.org/)  و [Parcel](https://parceljs.org/) را دیده‌ایم که تجربه توسعه برای توسعه‌دهندگان فرانت‌اند را بهبود بخشیده‌اند.

با این حال، همان‌طور که برنامه‌های بلندپروازانه‌تری می‌سازیم، میزان جاوااسکریپتی که با آن سروکار داریم نیز به طور چشمگیری افزایش می‌یابد. در پروژه‌های بزرگ مقیاس، داشتن هزاران ماژول غیرمعمول نیست. ما در حال رسیدن به یک گلوگاه عملکردی برای ابزارهای مبتنی بر جاوااسکریپت هستیم: اغلب ممکن است زمان انتظار غیرمعقولی (گاهی تا چند دقیقه!) طول بکشد تا یک سرور توسعه راه‌اندازی شود، و حتی با جایگزینی سریع ماژول (HMR)، ویرایش فایل‌ها ممکن است چند ثانیه طول بکشد تا در مرورگر منعکس شوند. این بازخورد کند می‌تواند به شدت بر بهره‌وری و رضایت توسعه‌دهندگان تأثیر بگذارد.

Vite هدف دارد این مشکلات را با بهره‌گیری از پیشرفت‌های جدید در اکوسیستم حل کند: در دسترس بودن ماژول‌های ES بومی در مرورگر، و ظهور ابزارهای جاوااسکریپت نوشته‌شده با زبان‌هایی که به باینری کامپایل می‌شوند.

### شروع کُند سرور

وقتی سرور توسعه به صورت cold-starting اجرا می‌شود، قبل از اینکه برنامه بتواند ارائه شود باید یک راه‌اندازی ساخت مبتنی بر باندلر به طور پیش‌فرض تمام برنامه شما را پیمایش و بیلد کند.

Vite در زمان شروع، سرور توسعه را با تقسیم ماژول‌های یک برنامه به دو دسته بهبود می‌بخشد: **وابستگی‌ها** و **سورس کد**.

* **وابستگی‌ها** عمدتاً جاوااسکریپت ساده هستند که در طول توسعه تغییر نمی‌کنند. برخی وابستگی‌های بزرگ (مثلاً کتابخانه‌های کامپوننت با صدها ماژول) نیز دارای پردازش بسیار گران هستند. وابستگی‌ها ممکن است در انواع مختلف فرمت‌های ماژول (مثلاً ESM یا CommonJS) ارائه شوند.

  Vite با استفاده از [esbuild](https://esbuild.github.io/) می‌تواند [وابستگی‌ها را پیش‌باندل](./dep-pre-bundling.md) کند. esbuild با زبان Go نوشته شده و وابستگی‌ها را 10 تا 100 برابر سریع‌تر از باندلرهای مبتنی بر جاوااسکریپت پیش‌باندل می‌کند.

* **سورس کد** اغلب حاوی جاوااسکریپت غیر‌ساده‌ای است که نیاز به تبدیل دارد (مثلاً JSX ، CSS یا کامپوننت‌های Vue/Svelte)، و بسیار زیاد ویرایش می‌شود. همچنین، نیازی نیست تمام سورس کد به طور همزمان بارگذاری شود (مثلاً با تقسیم کد مبتنی بر مسیر).

  Vite سورس کد را از طریق [ESM بومی](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) ارائه می‌دهد. این اساساً اجازه می‌دهد تا مرورگر بخشی از کار یک باندلر را انجام دهد: Vite فقط نیاز دارد سورس کد را بر اساس تقاضا تبدیل کند و سرویس دهد، همان‌طور که مرورگر آن را درخواست می‌کند. کدی که پشت ایمپورت داینامیک شرطی است تنها در صورت استفاده واقعی در صفحه فعلی پردازش می‌شود.

### به‌روزرسانی‌های کند

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

در برخی باندلرها، سرور توسعه باندلینگ را در حافظه (memory) انجام می‌دهد تا فقط نیاز باشد بخشی از گراف ماژول خود را هنگام تغییر یک فایل نامعتبر کند، اما همچنان نیاز است کل باندل را بازسازی کرده و صفحه وب را دوباره بارگذاری کند. بازسازی باندل می‌تواند پرهزینه باشد، و بارگذاری مجدد صفحه وضعیت فعلی برنامه را از بین می‌برد. به همین دلیل است که برخی باندلرها از جایگزینی سریع ماژول (Hot Module Replacement (HMR)) پشتیبانی می‌کنند: اجازه می‌دهد یک ماژول بدون تأثیر بر بقیه صفحه به صورت "سریع" جایگزین شود. این به طور قابل توجهی تجربه توسعه (DX) را بهبود می‌بخشد - با این حال، در عمل ما متوجه شده‌ایم که حتی سرعت به‌روزرسانی HMR نیز با رشد اندازه برنامه به طور قابل توجهی کاهش می‌یابد.

در Vite، عملیات HMR بر روی ESM بومی انجام می‌شود. وقتی فایلی ویرایش می‌شود، Vite تنها زنجیره‌ی بین ماژول ویرایش‌شده و نزدیک‌ترین مرز HMR را نامعتبر می‌کند (که معمولاً فقط خود ماژول است). این فرآیند باعث می‌شود که به‌روزرسانی‌های HMR، بدون توجه به اندازه‌ی برنامه، همواره با سرعت بالا انجام شوند.

Vite همچنین از هدرهای HTTP برای سرعت بخشیدن به بارگذاری مجدد کامل صفحه استفاده می‌کند (باز هم، اجازه دهید مرورگر کار بیشتری برای ما انجام دهد): درخواست‌های ماژول سورس کد به‌صورت مشروط با وضعیت `304 Not Modified` انجام می‌شوند، در حالی که ماژول‌های وابستگی با هدر `Cache-Control: max-age=31536000, immutable` به‌شدت کش می‌شوند. به همین دلیل، پس از یک‌بار کش شدن، دیگر نیازی به ارسال درخواست به سرور ندارند.

پس از تجربه سرعت Vite، بعید است که بخواهید دوباره به توسعه مبتنی بر باندل برگردید.

## چرا برای پروداکشن باندل کنیم

حتی با وجود اینکه ESM بومی اکنون به طور گسترده پشتیبانی می‌شود، به دلیل رفت‌و‌آمدهای اضافی شبکه که توسط ایمپورت‌های تودرتو ایجاد می‌شود، ارسال ESM بدون باندل در محیط پروداکشن همچنان ناکارآمد است (حتی با HTTP/2) . برای دستیابی به بهترین عملکرد بارگذاری در پروداکشن، همچنان بهتر است کد خود را با استفاده از tree-shaking، بارگذاری تنبل (lazy-loading) و تقسیم‌بندی بخش‌های مشترک (برای بهبود کش) باندل کنید.

اطمینان از خروجی بهینه و سازگاری رفتاری بین سرور توسعه و بیلد ساخته شده برای پروداکشن آسان نیست. به همین دلیل است که Vite با یک [کامند بیلد](./build.md) از پیش پیکربندی‌شده ارائه می‌شود که بسیاری از [بهینه‌سازی‌های عملکرد](./features.md#build-optimizations) را به صورت پیش‌فرض در خود دارد.

## چرا با esbuild باندل نکنیم؟

در حالی که Vite از esbuild برای [پیش‌باندل کردن برخی وابستگی‌ها در زمان توسعه](./dep-pre-bundling.md) استفاده می‌کند، Vite از esbuild به عنوان یک باندلر برای بیلدهای پروداکشن استفاده نمی‌کند.

API فعلی پلاگین Vite با استفاده از `esbuild` به عنوان باندلر سازگار نیست. با وجود اینکه `esbuild` سریع‌تر است، پذیرش API انعطاف‌پذیر پلاگین و زیرساخت Rollup توسط Vite به موفقیت آن در اکوسیستم کمک بزرگی کرده است. در حال حاضر، ما معتقدیم که Rollup توازن بهتری بین عملکرد و انعطاف‌پذیری ارائه می‌دهد.

Rollup همچنین در حال کار بر روی بهبودهای عملکردی است، [تغییر پارسر خود به SWC در نسخه 4](https://github.com/rollup/rollup/pull/5073) و تلاش‌هایی در حال انجام است برای ساخت نسخه‌ای به زبان Rust از Rollup به نام Rolldown. زمانی که Rolldown آماده شود، می‌تواند هر دو Rollup و esbuild را در Vite جایگزین کند، عملکرد بیلد را به طرز قابل توجهی بهبود بخشد و ناسازگاری‌های بین توسعه و بیلد را از بین ببرد. می‌توانید [سخنرانی کلیدی Evan You در ViteConf 2023 برای جزئیات بیشتر تماشا کنید](https://youtu.be/hrdwQHoAp0M).

## Vite چگونه با سایر ابزارهای ساخت بدون باندل مقایسه می‌شود؟

ابزار [WMR](https://github.com/preactjs/wmr) که توسط تیم Preact توسعه داده شده بود، هدفش ارائه مجموعه‌ای از قابلیت‌های مشابه با Vite بود. رابط افزونه‌ی مشترک Vite برای محیط توسعه و ساخت (build) از WMR الهام گرفته است. اما WMR دیگر پشتیبانی نمی‌شود و تیم Preact اکنون استفاده از Vite همراه با بسته‌ی [‎@preactjs/preset-vite](https://github.com/preactjs/preset-vite) را پیشنهاد می‌دهد.

[Snowpack](https://www.snowpack.dev/) نیز یک سرور توسعه ESM بومی بدون باندل بود که بسیار شبیه به Vite بود. پیش‌باندل کردن وابستگی‌های Vite نیز از Snowpack v1 (اکنون [`esinstall`](https://github.com/snowpackjs/snowpack/tree/main/esinstall)) الهام گرفته شده است. Snowpack دیگر نگهداری نمی‌شود. تیم Snowpack اکنون روی [Astro](https://astro.build/) کار می‌کند، یک سازنده سایت استاتیک که از Vite قدرت گرفته است.

پروژه [‎@web/dev-server](https://modern-web.dev/docs/dev-server/overview/) (که قبلاً با نام `es-dev-server` شناخته می‌شد) یکی از پروژه‌های عالی است که معماری سرور مبتنی بر Koa در Vite نسخه 1.0 از آن الهام گرفته شده است. پروژه‌ی جامع `‎@web` به‌صورت فعال نگهداری می‌شود و شامل ابزارهای فوق‌العاده‌ی دیگری نیز هست که می‌توانند برای کاربران Vite مفید باشند.

---

---
url: /guide/static-deploy.md
---
# دیپلوی یک سایت استاتیک

راهنماهای زیر بر اساس برخی فرضیات مشترک نوشته شده‌اند:

* شما از مسیر پیش‌فرض برای خروجی فایل‌های بیلد شده (`dist`) استفاده می‌کنید. این مسیر را می‌توانید با استفاده از گزینه `build.outDir` تغییر دهید. اگر مسیر خروجی را تغییر داده‌اید، می‌توانید دستورالعمل‌های زیر را بر اساس نیاز خود تنظیم و تطبیق دهید.
* شما از npm به عنوان پکیج منیجر استفاده می‌کنید. اگر از Yarn یا دیگر پکیج منیجرها استفاده می‌کنید، می‌توانید از دستورات معادل برای اجرای اسکریپت‌ها استفاده کنید.
* Vite به عنوان یک وابستگی توسعه (dev dependency) به صورت محلی در پروژه شما نصب شده است و شما اسکریپت‌های npm زیر را در پروژه خود تنظیم کرده‌اید:

```json [package.json]
{
  "scripts": {
    "build": "vite build",
    "preview": "vite preview"
  }
}
```

توجه داشته باشید که دستور `vite preview` فقط برای پیش‌نمایش فایل‌های build شده به کار می‌رود و نمی‌توان از آن به عنوان یک پروداکشن سرور استفاده کرد.

::: tip توجه
این راهنماها دستورالعمل‌هایی برای انجام پیاده سازی استاتیک (Static Deployment) سایت شما با استفاده از Vite ارائه می‌دهند. Vite همچنین از رندرینگ سمت سرور (Server-Side Rendering یا SSR) پشتیبانی می‌کند. SSR به فریم‌ورک‌های فرانت‌اندی اشاره دارد که قابلیت اجرای یک برنامه یکسان در Node.js، پیش‌رندر کردن آن به HTML و در نهایت Hydrate آن در سمت کلاینت را فراهم می‌کنند. برای یادگیری بیشتر درباره این قابلیت، به [راهنمای SSR](./ssr) مراجعه کنید. از طرف دیگر، اگر به دنبال ادغام با فریم‌ورک‌های سنتی سمت سرور هستید، به جای آن [راهنمای ادغام با backend](./backend-integration) را بررسی کنید.
:::

## بیلد برنامه

می‌توانید از دستور `npm run build` برای بیلد برنامه استفاده کنید.

```bash
$ npm run build
```

به طور پیش‌فرض، خروجی بیلد در پوشه `dist` ذخیره می‌شود. شما می‌توانید این پوشه `dist` را روی هر پلتفرم دلخواهی که مدنظر دارید، دیپلوی کنید.

### تست برنامه به صورت لوکال

پس از بیلد کردن برنامه، می‌توانید آن را به صورت لوکال با استفاده از دستور `npm run preview` تست کنید.

```bash
$ npm run preview
```

دستور `vite preview`،این دستور یک وب سرور استاتیک لوکال راه‌اندازی می‌کند که فایل‌های داخل پوشه `dist` را در آدرس `http://localhost:4173` سرو می‌دهد. این روشی ساده برای بررسی این است که production build در محیط لوکال شما به درستی نمایش داده می‌شود.

می‌توانید پورت سرور را با استفاده از فلگ `‎--port` به عنوان آرگومان تنظیم کنید.

```json [package.json]
{
  "scripts": {
    "preview": "vite preview --port 8080"
  }
}
```

اکنون دستور `preview` سرور را در آدرس `http://localhost:8080` راه‌اندازی می‌کند.

## GitHub Pages

1. مقدار `base` را در فایل `vite.config.js` به درستی تنظیم کنید.

   * اگر قصد دارید پروژه را در `https://<USERNAME>.github.io/‎` یا روی یک دامنه سفارشی از طریق GitHub Pages (مثلاً `www.example.com`) مستقر کنید، `base` را روی `'/'` تنظیم کنید. همچنین می‌توانید `base` را از تنظیمات حذف کنید، زیرا به طور پیش‌فرض مقدار آن `'/'` است.

   * اگر قصد دارید پروژه را در `https://<USERNAME>.github.io/<REPO>/‎` مستقر کنید (مثلاً اگر مخزن شما در آدرس `https://github.com/<USERNAME>/<REPO>‎` قرار دارد)، `base` را روی `'/<REPO>/'` تنظیم کنید.

2. به بخش تنظیمات GitHub Pages در صفحه تنظیمات مخزن بروید و منبع استقرار را به عنوان **GitHub Actions** انتخاب کنید. این کار شما را به ایجاد یک workflow هدایت می‌کند که پروژه شما را بیلد و مستقر می‌کند. یک workflow نمونه که وابستگی‌ها را نصب کرده و با استفاده از npm پروژه را بیلد می‌کند، ارائه شده است:

   <<< ./static-deploy-github-pages.yaml#content

## GitLab Pages و GitLab CI

1. مقدار `base` را در فایل `vite.config.js` به درستی تنظیم کنید.

   * اگر قصد دارید پروژه خود را در آدرس `‎https://<USERNAME or GROUP>.gitlab.io/‎` دیپلوی کنید، می‌توانید `base` را نادیده بگیرید، زیرا به طور پیش‌فرض مقدار آن `'/'` است.

   * اگر قصد دارید پروژه خود را در آدرس `https://<USERNAME or GROUP>.gitlab.io/<REPO>/‎` دیپلوی کنید (مثلاً اگر مخزن شما در آدرس `https://gitlab.com/<USERNAME>/<REPO>‎` قرار دارد)، باید `base` را به `'/<REPO>/'` تنظیم کنید.

2. در root پروژه خود، یک فایل با نام `‎.gitlab-ci.yml` ایجاد کنید و محتوای زیر را به آن اضافه کنید. این فایل باعث می‌شود هر زمان که تغییراتی در محتوای پروژه ایجاد کنید، به‌طور خودکار سایت شما ساخته شده (build) و دیپلوی شود:

   ```yaml [.gitlab-ci.yml]
   image: node:lts
   pages:
     stage: deploy
     cache:
       key:
         files:
           - package-lock.json
         prefix: npm
       paths:
         - node_modules/
     script:
       - npm install
       - npm run build
       - cp -a dist/. public/
     artifacts:
       paths:
         - public
     rules:
       - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
   ```

## Netlify

### Netlify CLI

1. [Netlify CLI](https://cli.netlify.com/) را نصب کنید.
2. با استفاده از دستور `ntl init` یک سایت جدید ایجاد کنید.
3. با دستور `ntl deploy` دیپلوی کنید.

```bash
# Install the Netlify CLI
$ npm install -g netlify-cli

# Create a new site in Netlify
$ ntl init

# Deploy to a unique preview URL
$ ntl deploy
```

CLI Netlify یک preview URL در اختیار شما قرار می‌دهد تا بتوانید آن را بررسی کنید. زمانی که آماده هستید به مرحله production بروید، از فلگ `prod` استفاده کنید:

```bash
# Deploy the site into production
$ ntl deploy --prod
```

### Netlify با Git

1. کد خود را به یک ریپازیتوری Git (مثل GitHub، GitLab، BitBucket، Azure DevOps) پوش کنید.
2. [پروژه را به Netlify ایمپورت کنید](https://app.netlify.com/start).
3. برنچ (Branch)، پوشه خروجی و متغیرهای محیطی را در صورت نیاز تنظیم کنید.
4. روی **Deploy** کلیک کنید.
5. اپلیکیشن Vite شما دیپلوی شد!

بعد از اینکه پروژه شما ایمپورت و دیپلوی شد، تمام پوش‌های بعدی به برنچ‌های غیر از برنچ اصلی (Production Branch) و همچنین Pull Request‌ها، [Preview Deployments](https://docs.netlify.com/site-deploys/deploy-previews/) ایجاد می‌کنند و تمام تغییرات اعمال شده روی برنچ اصلی (معمولاً “main”) منجر به یک [Production Deployment](https://docs.netlify.com/site-deploys/overview/#definitions) خواهند شد.

## Vercel

### Vercel CLI

1. [Vercel CLI](https://vercel.com/cli) را نصب کنید و دستور `vercel` را اجرا کنید تا دیپلوی انجام شود.
2. Vercel تشخیص می‌دهد که شما از Vite استفاده می‌کنید و تنظیمات صحیح را برای دیپلوی فعال می‌کند.
3. اپلیکیشن شما دیپلوی شد! (مثال: [vite-vue-template.vercel.app](https://vite-vue-template.vercel.app/))

```bash
$ npm i -g vercel
$ vercel init vite
Vercel CLI
> Success! Initialized "vite" example in ~/your-folder.
- To deploy, `cd vite` and run `vercel`.
```

### Vercel برای Git

1. کد خود را به ریپازیتوری Git (مثل GitHub، GitLab، Bitbucket) پوش کنید.
2. [پروژه Vite خود را به Vercel ایمپورت کنید](https://vercel.com/new).
3. Vercel تشخیص می‌دهد که شما از Vite استفاده می‌کنید و تنظیمات صحیح را برای دیپلوی فعال می‌کند.
4. اپلیکیشن شما دیپلوی شد! (مثال: [vite-vue-template.vercel.app](https://vite-vue-template.vercel.app/))

بعد از اینکه پروژه شما ایمپورت و دیپلوی شد، تمام پوش‌های بعدی به برنچ‌ها، [Preview Deployments](https://vercel.com/docs/concepts/deployments/environments#preview) ایجاد می‌کنند و تمام تغییرات اعمال شده روی برنچ اصلی (معمولاً “main”) منجر به یک [Production Deployment](https://vercel.com/docs/concepts/deployments/environments#production) خواهند شد.

برای اطلاعات بیشتر، می‌توانید درباره [Git Integration در Vercel](https://vercel.com/docs/concepts/git) مطالعه کنید.

## Cloudflare Pages

### Cloudflare Pages از طریق Wrangler

1. [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/get-started/) را نصب کنید.
2. Wrangler را با حساب Cloudflare خود احراز هویت کنید. برای این کار از دستور `wrangler login` استفاده کنید.
3. دستور build خود را اجرا کنید.
4. با استفاده از دستور `npx wrangler pages deploy dist` دیپلوی کنید.

```bash
# Install Wrangler CLI
$ npm install -g wrangler

# Login to Cloudflare account from CLI
$ wrangler login

# Run your build command
$ npm run build

# Create new deployment
$ npx wrangler pages deploy dist
```

بعد از آپلود فایل‌ها، Wrangler یک preview URL در اختیار شما قرار می‌دهد تا سایت خود را بررسی کنید. وقتی وارد داشبورد Cloudflare Pages می‌شوید، پروژه جدید خود را مشاهده خواهید کرد.

### Cloudflare Pages با Git

1. کد خود را به ریپازیتوری Git (مثل GitHub، GitLab) پوش کنید.
2. وارد داشبورد Cloudflare شوید و حساب خود را در **Account Home** > **Pages** انتخاب کنید.
3. **Create a new Project** و گزینه **Connect Git** را انتخاب کنید.
4. پروژه Git که می‌خواهید دیپلوی کنید را انتخاب کرده و روی **Begin setup** کلیک کنید.
5. در تنظیمات build، پریست فریم‌ورک مربوطه را بسته به فریم‌ورک Vite انتخاب‌شده تنظیم کنید.
6. سپس ذخیره کرده و دیپلوی کنید!
7. اپلیکیشن شما دیپلوی شد! (مثال: `https://<PROJECTNAME>.pages.dev/‎`)

بعد از اینکه پروژه شما ایمپورت و دیپلوی شد، تمام پوش‌های بعدی به برنچ‌ها، [Preview Deployments](https://developers.cloudflare.com/pages/platform/preview-deployments/) ایجاد می‌کنند (مگر اینکه در [branch build controls](https://developers.cloudflare.com/pages/platform/branch-build-controls/) غیرفعال شده باشد). تمام تغییرات در برنچ اصلی (معمولاً “main”) منجر به یک Production Deployment خواهد شد.

همچنین می‌توانید دامنه‌های سفارشی اضافه کنید و تنظیمات build سفارشی را در Pages مدیریت کنید. برای اطلاعات بیشتر، [Cloudflare Pages Git Integration](https://developers.cloudflare.com/pages/get-started/#manage-your-site) را مطالعه کنید.

## Google Firebase

1. مطمئن شوید که [firebase-tools](https://www.npmjs.com/package/firebase-tools) نصب شده است.

2. در root پروژه خود فایل‌های `firebase.json` و `.firebaserc` را با محتوای زیر ایجاد کنید:

   ```json [firebase.json]
   {
     "hosting": {
       "public": "dist",
       "ignore": [],
       "rewrites": [
         {
           "source": "**",
           "destination": "/index.html"
         }
       ]
     }
   }
   ```

   ```js [.firebaserc]
   {
     "projects": {
       "default": "<YOUR_FIREBASE_ID>"
     }
   }
   ```

3. بعد از اجرای دستور `npm run build`، با استفاده از دستور `firebase deploy` دیپلوی کنید.

## Surge

ابتدا اگر surge را نصب نکرده‌اید، آن را نصب کنید.

دستور `npm run build` را اجرا کنید.

برای دیپلوی روی surge، دستور `surge dist` را وارد کنید.

همچنین می‌توانید با استفاده از دستور `surge dist yourdomain.com` روی یک دامنه سفارشی دیپلوی کنید.

## Azure Static Web Apps

می‌توانید اپلیکیشن Vite خود را به سرعت با سرویس [Static Web Apps](https://aka.ms/staticwebapps) مایکروسافت Azure دیپلوی کنید. برای این کار به موارد زیر نیاز دارید:

* یک حساب Azure و کلید اشتراک. می‌توانید [یک حساب Azure رایگان ایجاد کنید](https://azure.microsoft.com/free).
* کد اپلیکیشن شما که به [GitHub](https://github.com) پوش شده باشد.
* [افزونه SWA](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-azurestaticwebapps) در [Visual Studio Code](https://code.visualstudio.com).

افزونه را در VS Code نصب کنید و به root پروژه خود بروید. افزونه Static Web Apps را باز کنید، به Azure وارد شوید و روی علامت '+' کلیک کنید تا یک Static Web App جدید ایجاد کنید. از شما خواسته می‌شود که کلید اشتراک مورد نظر خود را انتخاب کنید.

مراحل راهنمای ارائه‌شده توسط افزونه را دنبال کنید تا نام اپلیکیشن خود را انتخاب کنید، پریست فریم‌ورک را تنظیم کنید و مسیر root اپلیکیشن (معمولاً `/`) و مسیر فایل‌های ساخته‌شده (`‎/dist`) را مشخص کنید. راهنما اجرا می‌شود و یک GitHub Action در ریپازیتوری شما در پوشه `‎.github` ایجاد می‌کند.

این Action برای دیپلوی اپلیکیشن شما کار می‌کند (پیشرفت آن را در تب Actions ریپازیتوری خود مشاهده کنید) و پس از تکمیل موفقیت‌آمیز، می‌توانید اپلیکیشن خود را در آدرس ارائه‌شده در پنجره پیشرفت افزونه مشاهده کنید. برای این کار، روی دکمه 'Browse Website' که پس از اجرای GitHub Action ظاهر می‌شود، کلیک کنید.

## Render

می‌توانید اپلیکیشن Vite خود را به عنوان یک سایت استاتیک در [Render](https://render.com/) دیپلوی کنید.

1. یک [حساب Render](https://dashboard.render.com/register) ایجاد کنید.

2. در [داشبورد](https://dashboard.render.com/)، روی دکمه **New** کلیک کنید و **Static Site** را انتخاب کنید.

3. حساب GitHub/GitLab خود را متصل کنید یا از یک ریپازیتوری عمومی استفاده کنید.

4. یک نام پروژه و برنچ مشخص کنید.
   * **Build Command**: `npm install && npm run build`
   * **Publish Directory**: `dist`

5. روی **Create Static Site** کلیک کنید.

   اپلیکیشن شما باید در `https://<PROJECTNAME>.onrender.com/‎` دیپلوی شود.

به طور پیش‌فرض، هر کامیت جدیدی که به برنچ مشخص‌شده پوش شود، به طور خودکار یک دیپلوی جدید ایجاد می‌کند. [Auto-Deploy](https://render.com/docs/deploys#toggling-auto-deploy-for-a-service) را می‌توان در تنظیمات پروژه پیکربندی کرد.

همچنین می‌توانید یک [دامنه سفارشی](https://render.com/docs/custom-domains) به پروژه خود اضافه کنید.

## Flightcontrol

سایت استاتیک خود را با استفاده از [Flightcontrol](https://www.flightcontrol.dev/?ref=docs-vite) و با دنبال کردن این [دستورالعمل‌ها](https://www.flightcontrol.dev/docs/reference/examples/vite?ref=docs-vite) دیپلوی کنید.

## Kinsta Static Site Hosting

سایت استاتیک خود را با استفاده از [Kinsta](https://kinsta.com/static-site-hosting/) و با دنبال کردن این [دستورالعمل‌ها](https://kinsta.com/docs/react-vite-example/) دیپلوی کنید.

## xmit Static Site Hosting

سایت استاتیک خود را با استفاده از [xmit](https://xmit.co) و با دنبال کردن این [راهنما](https://xmit.dev/posts/vite-quickstart/) دیپلوی کنید.

---

---
url: /guide/api-javascript.md
---
# ‌رابط برنامه‌نویسی اپلیکیشن (API) جاوا اسکریپت

رابط‌های جاوااسکریپت در Vite به‌طور کامل تایپ شده‌اند (typed) و توصیه می‌شود برای بهره‌مندی از قابلیت‌هایی مانند IntelliSense و اعتبارسنجی (validation)، از TypeScript استفاده کنید یا بررسی تایپ (type checking) را در VS Code برای فایل‌های JS فعال نمایید.

## تابع `createServer`

**امضای تایپ:**

```ts
async function createServer(inlineConfig?: InlineConfig): Promise<ViteDevServer>
```

**مثال استفاده:**

```ts twoslash
import { fileURLToPath } from 'node:url'
import { createServer } from 'vite'

const __dirname = fileURLToPath(new URL('.', import.meta.url))

const server = await createServer({
  // any valid user config options, plus `mode` and `configFile`
  configFile: false,
  root: __dirname,
  server: {
    port: 1337,
  },
})
await server.listen()

server.printUrls()
server.bindCLIShortcuts({ print: true })
```

:::tip نکته
هنگامی که از `createServer` و `build` در یک پردازش (process) مشترک Node.js استفاده می‌کنید، هر دو تابع برای عملکرد صحیح به مقدار `process.env.NODE_ENV` وابسته هستند، که این مقدار نیز به گزینه‌ی پیکربندی `mode` بستگی دارد. برای جلوگیری از بروز رفتارهای متناقض، مقدار `process.env.NODE_ENV` یا `mode` در هر دو API را روی `development` تنظیم کنید. در غیر این صورت، می‌توانید با ایجاد یک پردازش فرزند (child process) این دو API را به‌صورت جداگانه اجرا کنید.
:::

:::tip نکته
زمانی که از [حالت میدلور (middleware mode)](/config/server-options.html#server-middlewaremode) به همراه [پیکربندی پراکسی برای WebSocket](/config/server-options.html#server-proxy) استفاده می‌کنید، باید **سرور HTTP والد** (parent http server) را در گزینه‌ی `middlewareMode` مشخص کنید تا پروکسی به‌درستی به سرور متصل شود.

```ts twoslash
import http from 'http'
import { createServer } from 'vite'

const parentServer = http.createServer() // or express, koa, etc.

const vite = await createServer({
  server: {
    // Enable middleware mode
    middlewareMode: {
      // Provide the parent http server for proxy WebSocket
      server: parentServer,
    },
    proxy: {
      '/ws': {
        target: 'ws://localhost:3000',
        // Proxying WebSocket
        ws: true,
      },
    },
  },
})

// @noErrors: 2339
parentServer.use(vite.middlewares)
```

## کانفیگ درون خطی (`InlineConfig`)

رابط `InlineConfig` نسخه‌ای توسعه‌یافته از `UserConfig` است که چند ویژگی اضافی دارد:

* `کانفیگ‌فایل (configFile)`: مشخص می‌کند از کدام فایل پیکربندی استفاده شود. اگر تنظیم نشود، Vite به‌صورت خودکار به‌دنبال فایل پیکربندی در ریشه پروژه می‌گردد. برای غیرفعال کردن این رفتار، مقدار آن را `false` قرار دهید.

## پیکربندی درست شده (`ResolvedConfig`)

رابط `ResolvedConfig` شامل تمام ویژگی‌های `UserConfig` است، با این تفاوت که بیشتر این ویژگی‌ها **به‌طور کامل resolve شده و مقداردهی شده‌اند** (undefined نیستند). همچنین شامل ابزارهایی (utilities) مانند موارد زیر نیز می‌شود:

* `تابع config.assetsInclude`: تابعی برای بررسی اینکه آیا یک `id` به‌عنوان یک asset در نظر گرفته می‌شود یا نه.
* `تابع config.logger`: آبجکت لاگر داخلی Vite (برای ثبت و نمایش پیام‌ها و گزارش‌ها در طول اجرا).

## اینتر فیس `ViteDevServer`

```ts
interface ViteDevServer {
  /**
   * The resolved Vite config object.
   */
  config: ResolvedConfig
  /**
   * A connect app instance
   * - Can be used to attach custom middlewares to the dev server.
   * - Can also be used as the handler function of a custom http server
   *   or as a middleware in any connect-style Node.js frameworks.
   *
   * https://github.com/senchalabs/connect#use-middleware
   */
  middlewares: Connect.Server
  /**
   * Native Node http server instance.
   * Will be null in middleware mode.
   */
  httpServer: http.Server | null
  /**
   * Chokidar watcher instance. If `config.server.watch` is set to `null`,
   * it will not watch any files and calling `add` or `unwatch` will have no effect.
   * https://github.com/paulmillr/chokidar/tree/3.6.0#api
   */
  watcher: FSWatcher
  /**
   * Web socket server with `send(payload)` method.
   */
  ws: WebSocketServer
  /**
   * Rollup plugin container that can run plugin hooks on a given file.
   */
  pluginContainer: PluginContainer
  /**
   * Module graph that tracks the import relationships, url to file mapping
   * and hmr state.
   */
  moduleGraph: ModuleGraph
  /**
   * The resolved urls Vite prints on the CLI (URL-encoded). Returns `null`
   * in middleware mode or if the server is not listening on any port.
   */
  resolvedUrls: ResolvedServerUrls | null
  /**
   * Programmatically resolve, load and transform a URL and get the result
   * without going through the http request pipeline.
   */
  transformRequest(
    url: string,
    options?: TransformOptions,
  ): Promise<TransformResult | null>
  /**
   * Apply Vite built-in HTML transforms and any plugin HTML transforms.
   */
  transformIndexHtml(
    url: string,
    html: string,
    originalUrl?: string,
  ): Promise<string>
  /**
   * Load a given URL as an instantiated module for SSR.
   */
  ssrLoadModule(
    url: string,
    options?: { fixStacktrace?: boolean },
  ): Promise<Record<string, any>>
  /**
   * Fix ssr error stacktrace.
   */
  ssrFixStacktrace(e: Error): void
  /**
   * Triggers HMR for a module in the module graph. You can use the `server.moduleGraph`
   * API to retrieve the module to be reloaded. If `hmr` is false, this is a no-op.
   */
  reloadModule(module: ModuleNode): Promise<void>
  /**
   * Start the server.
   */
  listen(port?: number, isRestart?: boolean): Promise<ViteDevServer>
  /**
   * Restart the server.
   *
   * @param forceOptimize - force the optimizer to re-bundle, same as --force cli flag
   */
  restart(forceOptimize?: boolean): Promise<void>
  /**
   * Stop the server.
   */
  close(): Promise<void>
  /**
   * Bind CLI shortcuts
   */
  bindCLIShortcuts(options?: BindCLIShortcutsOptions<ViteDevServer>): void
  /**
   * Calling `await server.waitForRequestsIdle(id)` will wait until all static imports
   * are processed. If called from a load or transform plugin hook, the id needs to be
   * passed as a parameter to avoid deadlocks. Calling this function after the first
   * static imports section of the module graph has been processed will resolve immediately.
   * @experimental
   */
  waitForRequestsIdle: (ignoredId?: string) => Promise<void>
}
```

:::info اطلاعات
تابع `waitForRequestsIdle` به‌عنوان یک راه‌حل اضطراری طراحی شده است تا تجربه توسعه (DX) را برای ویژگی‌هایی که نمی‌توانند با طبیعت درخواستی سرور توسعه Vite پیاده‌سازی شوند، بهبود بخشد. این تابع می‌تواند در زمان راه‌اندازی توسط ابزارهایی مانند Tailwind استفاده شود تا تولید کلاس‌های CSS اپلیکیشن تا زمانی که کد اپلیکیشن دیده نشده است به تعویق بیفتد و از تغییرات ناگهانی استایل جلوگیری کند. زمانی که این تابع در یک هوک بارگذاری یا تبدیل استفاده می‌شود و از سرور پیش‌فرض HTTP1 استفاده می‌شود، یکی از شش کانال HTTP مسدود خواهد شد تا زمانی که سرور تمام ایمپورت‌های استاتیک را پردازش کند. بهینه‌ساز وابستگی‌های Vite هم‌اکنون از این تابع برای جلوگیری از بارگذاری مجدد کامل صفحه در صورت کمبود وابستگی‌ها استفاده می‌کند و بارگذاری وابستگی‌های پیش‌بسته را تا زمانی که تمام وابستگی‌های ایمپورتی از منابع ایمپورت استاتیک جمع‌آوری شوند، به تأخیر می‌اندازد. ممکن است Vite در نسخه‌های اصلی آینده استراتژی متفاوتی اتخاذ کند و به‌طور پیش‌فرض مقدار `optimizeDeps.crawlUntilStaticImports: false` را تنظیم کند تا از تاثیر منفی عملکرد در برنامه‌های بزرگ در هنگام راه‌اندازی سرد (cold start) جلوگیری کند.
:::

## `build`

**امضای تایپ:**

```ts
async function build(
  inlineConfig?: InlineConfig,
): Promise<RollupOutput | RollupOutput[]>
```

**مثال استفاده:**

```ts twoslash [vite.config.js]
import path from 'node:path'
import { fileURLToPath } from 'node:url'
import { build } from 'vite'

const __dirname = fileURLToPath(new URL('.', import.meta.url))

await build({
  root: path.resolve(__dirname, './project'),
  base: '/foo/',
  build: {
    rollupOptions: {
      // ...
    },
  },
})
```

## `preview`

**امضای تایپ:**

```ts
async function preview(inlineConfig?: InlineConfig): Promise<PreviewServer>
```

**مثال استفاده:**

```ts twoslash
import { preview } from 'vite'

const previewServer = await preview({
  // any valid user config options, plus `mode` and `configFile`
  preview: {
    port: 8080,
    open: true,
  },
})

previewServer.printUrls()
previewServer.bindCLIShortcuts({ print: true })
```

## اینترفیس `PreviewServer`

```ts
interface PreviewServer {
  /**
   * The resolved vite config object
   */
  config: ResolvedConfig
  /**
   * A connect app instance.
   * - Can be used to attach custom middlewares to the preview server.
   * - Can also be used as the handler function of a custom http server
   *   or as a middleware in any connect-style Node.js frameworks
   *
   * https://github.com/senchalabs/connect#use-middleware
   */
  middlewares: Connect.Server
  /**
   * native Node http server instance
   */
  httpServer: http.Server
  /**
   * The resolved urls Vite prints on the CLI (URL-encoded). Returns `null`
   * if the server is not listening on any port.
   */
  resolvedUrls: ResolvedServerUrls | null
  /**
   * Print server urls
   */
  printUrls(): void
  /**
   * Bind CLI shortcuts
   */
  bindCLIShortcuts(options?: BindCLIShortcutsOptions<PreviewServer>): void
}
```

## تابع `resolveConfig`

**امضای تایپ:**

```ts
async function resolveConfig(
  inlineConfig: InlineConfig,
  command: 'build' | 'serve',
  defaultMode = 'development',
  defaultNodeEnv = 'development',
  isPreview = false,
): Promise<ResolvedConfig>
```

مقدار `command` در حالت توسعه (dev) و پیش‌نمایش (preview)، برابر با `serve` است و در حالت ساخت (build)، برابر با `build` می‌باشد.

## تابع `mergeConfig`

**امضای تایپ:**

```ts
function mergeConfig(
  defaults: Record<string, any>,
  overrides: Record<string, any>,
  isRoot = true,
): Record<string, any>
```

دو پیکربندی Vite را به‌طور عمیق با هم ترکیب می‌کند. مقدار `isRoot` نمایانگر سطحی است که در پیکربندی Vite در حال ترکیب آن هستید. به‌عنوان مثال، اگر در حال ترکیب دو گزینه `build` هستید، مقدار آن را `false` قرار دهید.

:::tip نکته
تابع `mergeConfig` تنها پیکربندی‌هایی که به‌صورت آبجکت هستند را می‌پذیرد. اگر پیکربندی شما به‌صورت تابع callback است، باید آن را قبل از ارسال به `mergeConfig` فراخوانی کنید.

شما می‌توانید از تابع‌کمکی `defineConfig` برای ترکیب یک پیکربندی به‌صورت callback با یک پیکربندی دیگر استفاده کنید:

```ts twoslash
import {
  defineConfig,
  mergeConfig,
  type UserConfigFnObject,
  type UserConfig,
} from 'vite'
declare const configAsCallback: UserConfigFnObject
declare const configAsObject: UserConfig

// ---cut---
export default defineConfig((configEnv) =>
  mergeConfig(configAsCallback(configEnv), configAsObject),
)
```

:::

## تابع `searchForWorkspaceRoot`

**امضای تایپ:**

```ts
function searchForWorkspaceRoot(
  current: string,
  root = searchForPackageRoot(current),
): string
```

**مرتبط:** [server.fs.allow](/config/server-options.md#server-fs-allow)

ریشه‌ی workspace احتمالی را جست‌وجو کن اگر شرایط زیر برقرار باشند؛ در غیر این صورت، به مقدار `root` بازمی‌گردد:

* وجود فیلد `workspaces` در فایل `package.json`
* وجود یکی از فایل‌های زیر:
  * فایل `lerna.json`
  * و یا فایل `pnpm-workspace.yaml`

## تابع `loadEnv`

**امضای تایپ:**

```ts
function loadEnv(
  mode: string,
  envDir: string,
  prefixes: string | string[] = 'VITE_',
): Record<string, string>
```

**مرتبط:** [`‎.env` Files](./env-and-mode.md#env-files)

فایل‌های `‎.env` را درون دایرکتوری `envDir` بارگذاری کنید؛ به‌طور پیش‌فرض، فقط متغیرهای محیطی با پیشوند `VITE_‎` بارگذاری می‌شوند، مگر اینکه پیشوندها (`prefixes`) تغییر داده شوند.

## تابع `normalizePath`

**امضای تایپ:**

```ts
function normalizePath(id: string): string
```

**مرتبط:** [Path Normalization](./api-plugin.md#path-normalization)

مسیر (path) را نرمال‌سازی می‌کند تا بین افزونه‌های Vite قابل تعامل باشد.

## `transformWithEsbuild`

**امضای تایپ:**

```ts
async function transformWithEsbuild(
  code: string,
  filename: string,
  options?: EsbuildTransformOptions,
  inMap?: object,
): Promise<ESBuildTransformResult>
```

تبدیل JavaScript یا TypeScript با استفاده از esbuild. این کار برای افزونه‌هایی مفید است که ترجیح می‌دهند با فرآیند تبدیل داخلی Vite هماهنگ باشند.

## تابع `loadConfigFromFile`

**امضای تایپ:**

```ts
async function loadConfigFromFile(
  configEnv: ConfigEnv,
  configFile?: string,
  configRoot: string = process.cwd(),
  logLevel?: LogLevel,
  customLogger?: Logger,
): Promise<{
  path: string
  config: UserConfig
  dependencies: string[]
} | null>
```

بارگذاری دستی فایل تنظیمات Vite با استفاده از esbuild.

## تابع `preprocessCSS`

* **آزمایشی:** [Give Feedback](https://github.com/vitejs/vite/discussions/13815)

**امضای تایپ:**

```ts
async function preprocessCSS(
  code: string,
  filename: string,
  config: ResolvedConfig,
): Promise<PreprocessCSSResult>

interface PreprocessCSSResult {
  code: string
  map?: SourceMapInput
  modules?: Record<string, string>
  deps?: Set<string>
}
```

پیش‌پردازش فایل‌های `‎.css` ، `‎.scss` ، `‎.sass` ، `‎.less` ، `‎.styl` و `‎.stylus` به CSS ساده، به‌طوری‌که بتوان آن را در مرورگرها استفاده کرد یا توسط ابزارهای دیگر پردازش کرد. مشابه [پشتیبانی داخلی از پیش‌پردازش CSS](/guide/features#css-pre-processors)، پیش‌پردازش‌گر مربوطه باید به‌صورت جداگانه نصب شده باشد تا قابل استفاده باشد.

پیش‌پردازش‌گر مورد استفاده از روی پسوند `filename` تشخیص داده می‌شود. اگر نام فایل با `‎.module.{ext}` به پایان برسد، به‌عنوان یک [CSS module](https://github.com/css-modules/css-modules) در نظر گرفته می‌شود و نتیجه‌ی بازگشتی شامل یک آبجکت `modules` خواهد بود که نام کلاس‌های اصلی را به نام‌های تبدیل‌شده نگاشت می‌کند.

توجه داشته باشید که پیش‌پردازش، آدرس‌های موجود در `url()‎` یا `image-set()‎` را resolve نخواهد کرد.

---

---
url: /guide/cli.md
---
# رابط خط فرمان - CLI

## سرور توسعه

### `vite`

برای اجرای سرور توسعه Vite در دایرکتوری فعلی، دستور `‌vite‌` را اجرا کنید. همچنین `‌vite dev`‌ و `‌vite serve‌` به‌عنوان نام‌های مستعار آن عمل می‌کنند.

#### استفاده

```bash
vite [root]
```

#### گزینه‌ها

| گزینه‌ها                    |                                                                                                                |
| --------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `‎--host [host]`            | مشخص کردن نام هاست (`string`)                                                                                  |
| `‎--port <port>‎`           | مشخص کردن پورت (`number`)                                                                                      |
| `‎--open [path]‎`           | باز کردن مرورگر در هنگام راه‌اندازی (`boolean \| string`)                                                                  |
| `‎--cors`                   | فعال کردن CORS ؛(`boolean`)                                                                                   |
| `‎--strictPort`             | خروج اگر پورت مشخص شده در حال استفاده باشد (`boolean`)                                                         |
| `‎--force`                | مجبور کردن بهینه‌ساز برای نادیده گرفتن کش و دوباره بیلد گرفتن (`boolean`)                                      |
| `‎-c, --config <file>‎`     | استفاده از فایل کانفیگ مشخص شده (`string`)                                                                     |
| `‎--base <path>‎`           | مسیر پایه public (پیش‌فرض: `/`) (`string`)                                                                     |
| `‎-l, --logLevel <level>‎`  | info | warn | error | silent (`string`)                                                                     |
| `‎--clearScreen`            | اجازه/غیرفعال کردن پاک کردن صفحه هنگام لاگ‌گیری (`boolean`)                                                    |
| `‎--configLoader <loader>‎` | استفاده از `bundle` برای باندل کردن کانفیگ با esbuild یا `runner` (آزمایشی) برای پردازش آن به صورت آنی، یا از `native` (آزمایشی) برای بارگذاری با استفاده از runtime بومی (پیش‌فرض: `bundle`) |
| `‎--profile`                | شروع inspector داخلی Node.js ؛([گلوگاه‌های عملکرد](/guide/troubleshooting#performance-bottlenecks))     |
| `‎-d, --debug [feat]‎`      | نمایش لاگ‌های دیباگ (`string \| boolean`)                                                                      |
| `‎-f, --filter <filter>‎`   | فیلتر کردن لاگ‌های دیباگ (`string`)                                                                            |
| `‎-m, --mode <mode>‎`       | تنظیم حالت env ؛(`string`)                                                                                    |
| `‎-h, --help`               | نمایش گزینه‌های موجود CLI                                                                                      |
| `‎-v, --version`            | نمایش شماره نسخه                                                                                               |

## بیلد

### `vite build`

بیلد برای پروداکشن

#### استفاده

```bash
vite build [root]
```

#### گزینه‌ها

| گزینه‌ها                         |                                                                                                                        |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `‎--target <target>‎`            | هدف ترنسپایل (پیش‌فرض: `"modules"`) (`string`)                                                                         |
| `‎--outDir <dir>‎`               | دایرکتوری خروجی (پیش‌فرض: `dist`) (`string`)                                                                           |
| `‎--assetsDir <dir>‎`            | دایرکتوری زیر outDir برای قرار دادن asset ها (پیش‌فرض: `"assets"`) (`string`)                                          |
| `‎--assetsInlineLimit <number>‎` | حد آستانه inline دارایی‌های استاتیک به صورت base64 بر حسب بایت (پیش‌فرض: `4096`) (`number`)                            |
| `‎--ssr [entry]‎`                | ورودی مشخص شده برای رندرینگ سمت سرور (SSR) (`string`)                                                             |
| `‎--sourcemap [output]‎`         | خروجی source map برای بیلد (پیش‌فرض: `false`) (`boolean \| "inline" \| "hidden"`)                                    |
| `‎--minify [minifier]‎`          | فعال/غیرفعال کردن فشرده‌سازی، یا مشخص کردن فشرده‌سازی برای استفاده (پیش‌فرض: `"esbuild"`) (`boolean \| "terser" \| "esbuild"`)    |
| `‎--manifest [name]‎`            | تولید فایل json مانیفست بیلد (`boolean \| string`)                                                                     |
| `‎--ssrManifest [name]‎`         | تولید فایل json مانیفست ssr ؛(`boole   an \| string`)                                                                     |
| `‎--emptyOutDir‎`                | خالی کردن اجباری outDir وقتی که خارج از root است (`boolean`)                                                           |
| `‎-w, --watch`                   | اجرای مجدد بیلد هنگام تغییر در فایل‌ها یا ماژول‌ها (`boolean`)                                                                 |
| `‎-c, --config <file>‎`          | استفاده از فایل کانفیگ مشخص شده (`string`)                                                                             |
| `‎--base <path>‎`                | مسیر پایه عمومی (پیش‌فرض: `/`) (`string`)                                                                              |
| `‎-l, --logLevel <level>‎`       | Info | warn | error | silent (`string`)                                                                             |
| `‎--clearScreen`                 | اجازه/غیرفعال کردن پاک کردن صفحه هنگام لاگ‌گیری (`boolean`)                                                            |
| `‎--configLoader <loader>‎`      | استفاده از `bundle` برای باندل کردن کانفیگ با esbuild یا `runner` (آزمایشی) برای پردازش آن به صورت آنی (پیش‌فرض: `bundle`) |
| `‎--profile`               | شروع inspector داخلی Node.js ؛([گلوگاه‌های عملکرد](/guide/troubleshooting#performance-bottlenecks))    |
| `‎-d, --debug [feat]‎`           | نمایش لاگ‌های دیباگ (`string \| boolean`)                                                                              |
| `‎-f, --filter <filter>‎`        | فیلتر کردن لاگ‌های دیباگ (`string`)                                                                                    |
| `‎-m, --mode <mode>‎`            | تنظیم حالت env ؛(`string`)                                                                                             |
| `‎-h, --help`                    | نمایش گزینه‌های موجود CLI                                                                                              |
| `‎--app`                         | بیلد همه محیط‌ها، مشابه `builder: {}` (`boolean`, آزمایشی)                                                |

## سایر موارد

### `vite optimize`

پیش‌باندل وابستگی‌ها.

**منسوخ شده**: فرآیند پیش‌باندل به‌صورت خودکار اجرا می‌شود و نیازی به فراخوانی ندارد.

#### استفاده

```bash
vite optimize [root]
```

#### گزینه‌ها

| گزینه‌ها                    |                                                      توضیحات                                                                   |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `‎--force`                  | مجبور کردن بهینه‌ساز برای نادیده گرفتن کش و دوباره بیلد گرفتن (`boolean`)                                                      |
| `‎-c, --config <file>‎`     | استفاده از فایل کانفیگ مشخص شده (`string`)                                                                                     |
| `‎--base <path>‎`           | مسیر پایه public (پیش‌فرض: `/`) (`string`)                                                                                     |
| `‎-l, --logLevel <level>‎`  | Info | warn | error | silent (`string`)                                                                                     |
| `‎--clearScreen`            | اجازه/غیرفعال کردن پاک کردن صفحه هنگام لاگ‌گیری (`boolean`)                                                                    |
| `‎--configLoader <loader>‎` | استفاده از `bundle` برای باندل کردن کانفیگ با esbuild یا `runner` (آزمایشی) برای پردازش آن به صورت آنی (پیش‌فرض: `bundle`) |
| `‎-d, --debug [feat]‎`      | نمایش لاگ‌های دیباگ (`string \| boolean`)                                                                                      |
| `‎-f, --filter <filter>‎`   | فیلتر کردن لاگ‌های دیباگ (`string`)                                                                                            |
| `‎-m, --mode <mode>‎`       | تنظیم حالت env ؛(`string`)                                                                                                     |
| `‎-h, --help`               | نمایش گزینه‌های موجود CLI                                                                                                      |

### `vite preview`

پیش‌نمایش محلی بیلد پروداکشن. از این به عنوان سرور پروداکشن استفاده نکنید زیرا برای این منظور طراحی نشده است.

#### استفاده

```bash
vite preview [root]
```

#### گزینه‌ها

| گزینه‌ها                    |                                                                                                                               |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `‎--host [host]`            | مشخص کردن نام هاست (`string`)                                                                                                 |
| `‎--port <port>‎`           | مشخص کردن پورت (`number`)                                                                                                     |
| `‎--strictPort`             | خروج اگر پورت مشخص شده در حال استفاده باشد (`boolean`)                                                                        |
| `‎--open [path]‎`           | باز کردن مرورگر در هنگام راه‌اندازی (`boolean \| string`)                                                                                                                                |
| `‎--outDir <dir>‎`          | دایرکتوری خروجی (پیش‌فرض: `dist`) (`string`)                                                                                  |
| `‎-c, --config <file>‎`     | استفاده از فایل کانفیگ مشخص شده (`string`)                                                                                    |
| `‎--base <path>‎`           | مسیر پایه عمومی (پیش‌فرض: `/`) (`string`)                                                                                     |
| `‎-l, --logLevel <level>‎`  | Info | warn | error | silent (`string`)                                                                                    |
| `‎--clearScreen`            | اجازه/غیرفعال کردن پاک کردن صفحه هنگام لاگ‌گیری (`boolean`)                                                                   |
| `‎--configLoader <loader>‎` | استفاده از `bundle` برای باندل کردن کانفیگ با esbuild یا `runner` (آزمایشی) برای پردازش آن به صورت آنی (پیش‌فرض: `bundle`) |
| `‎-d, --debug [feat]‎`      | نمایش لاگ‌های دیباگ (`string \| boolean`)                                                                                     |
| `‎-f, --filter <filter>‎`   | فیلتر کردن لاگ‌های دیباگ (`string`)                                                                                           |
| `‎-m, --mode <mode>‎`       | تنظیم حالت env ؛(`string`)                                                                                                    |
| `‎-h, --help`               | نمایش گزینه‌های موجود CLI                                                                                                     |

---

---
url: /guide/ssr.md
---
# رندر سمت سرور (SSR)

:::tip نکته
رندر سمت سرور یا SSR، به قابلیتی در فریم‌ورک‌های فرانت‌اند مانند React ، Preact ، Vue و Svelte گفته می‌شود که اجازه می‌دهد همان اپلیکیشن در محیط Node.js اجرا شود، خروجی HTML تولید کند و سپس در مرورگر کاربر فرآیند "hydration" (فعال‌سازی تعاملی) را انجام دهد. اگر به دنبال یکپارچه‌سازی با فریم‌ورک‌های سنتی سمت سرور هستید، پیشنهاد می‌شود به [راهنمای اتصال به بک‌اند](./backend-integration) مراجعه کنید.

این راهنما فرض را بر آن دارد که شما پیش‌تر با مفاهیم SSR در فریم‌ورک انتخابی‌تان آشنا هستید، و تمرکز آن صرفاً بر نکات خاص و کاربردی SSR در Vite است.
:::

:::warning API سطح پایین
این رابط برنامه‌نویسی (API) مخصوص توسعه‌دهندگان کتابخانه‌ها و سازندگان فریم‌ورک‌هاست، و جزو ابزارهای سطح پایین Vite محسوب می‌شود. اگر هدف شما ساخت یک اپلیکیشن است، توصیه می‌کنیم ابتدا ابزارها و افزونه‌های سطح بالاتری که در [بخش SSR پروژه Awesome Vite](https://github.com/vitejs/awesome-vite#ssr) معرفی شده‌اند را بررسی کنید. با این حال، اپلیکیشن‌های بسیاری تاکنون با تکیه بر همین API بومی و سطح پایین Vite به‌خوبی توسعه یافته‌اند.

در حال حاضر، Vite در حال توسعه یک API پیشرفته‌تر برای SSR مبتنی بر [Environment API](https://github.com/vitejs/vite/discussions/16358) است. برای آگاهی بیشتر می‌توانید به لینک مورد نظر مراجعه کنید.
:::

## پروژه‌های نمونه

Vite به‌صورت داخلی از رندر سمت سرور (SSR) پشتیبانی می‌کند. پروژه [`create-vite-extra`](https://github.com/bluwy/create-vite-extra) مجموعه‌ای از تنظیمات آماده‌ی SSR را فراهم کرده که می‌توانید به‌عنوان مرجع در این راهنما از آن‌ها استفاده کنید:

* [Vanilla (بدون فریم‌ورک خاص)](https://github.com/bluwy/create-vite-extra/tree/master/template-ssr-vanilla)
* [Vue](https://github.com/bluwy/create-vite-extra/tree/master/template-ssr-vue)
* [React](https://github.com/bluwy/create-vite-extra/tree/master/template-ssr-react)
* [Preact](https://github.com/bluwy/create-vite-extra/tree/master/template-ssr-preact)
* [Svelte](https://github.com/bluwy/create-vite-extra/tree/master/template-ssr-svelte)
* [Solid](https://github.com/bluwy/create-vite-extra/tree/master/template-ssr-solid)

همچنین می‌توانید این پروژه‌ها را به‌صورت محلی با اجرای [دستور `create-vite`](./index.md#scaffolding-your-first-vite-project) راه‌اندازی کنید. در بخش انتخاب فریم‌ورک، گزینه‌ی `Others > create-vite-extra` را انتخاب نمایید.

## ساختار پروژه

یک اپلیکیشن معمولی با پشتیبانی از SSR (رندر سمت سرور) معمولاً دارای ساختاری مشابه زیر است:

```
- index.html
- server.js           # سرور اصلی اپلیکیشن
- src/
  - main.js           # کد عمومی برنامه که مستقل از محیط اجراست
  - entry-client.js   # در مرورگر DOM مسئول نصب برنامه روی
  - entry-server.js   # در فریم‌ورک SSR مربوط به API مسئول رندر کردن برنامه در سمت سرور با استفاده از
```

در فایل `index.html` باید به `entry-client.js` اشاره شود و همچنین محلی برای جای‌گذاری خروجی رندر شده توسط سرور در نظر گرفته شود:

```html [index.html]
<div id="app"><!--ssr-outlet--></div>
<script type="module" src="/src/entry-client.js"></script>
```

می‌توانید به‌جای `‎<!--ssr-outlet-->‎` از هر نشانه‌گذاری دلخواه دیگری استفاده کنید، فقط کافی است که قابل شناسایی و جایگزینی دقیق باشد.

## منطق شرطی

اگه نیاز دارید کد شرطی بر اساس SSR یا کلاینت بنویسید، می‌تونید از این کد استفاده کنید:

```js twoslash
import 'vite/client'
// ---cut---
if (import.meta.env.SSR) {
  // ... فقط کد مخصوص سرور
}
```

این شرط در زمان build به‌صورت استاتیک جایگزین می‌شود، بنابراین کدهایی که استفاده نمی‌شوند حذف می‌شوند (tree-shaking)، که باعث سبک‌تر شدن باندل نهایی می‌شود.

## راه‌اندازی سرور توسعه (Dev Server)

وقتی دارید یک برنامه SSR می‌سازید، احتمالاً می‌خواهید کنترل کامل روی سرور اصلی‌تان داشته باشید و Vite را از محیط پروداکشن (production) جدا کنید. به همین دلیل، توصیه می‌شود از Vite در حالت middleware استفاده کنید. در ادامه یک نمونه با [Express](https://expressjs.com/) آورده شده است:

```js{15-18} twoslash [server.js]
import fs from 'node:fs'
import path from 'node:path'
import { fileURLToPath } from 'node:url'
import express from 'express'
import { createServer as createViteServer } from 'vite'

const __dirname = path.dirname(fileURLToPath(import.meta.url))

async function createServer() {
  const app = express()

  // ایجاد کنید و نوع اپلیکیشن را به middleware را در حالت Vite سرور
  // غیرفعال شود و سرور والد Vite داخلی HTML تنظیم کنید تا سرو 'custom'
  // بتواند کنترل را به دست بگیرد
  const vite = await createViteServer({
    server: { middlewareMode: true },
    appType: 'custom'
  })

  // خودتان express استفاده کنید. اگر از روتر middleware به عنوان vite مربوط connect از نمونه
  // .استفاده کنید router.use استفاده می‌کنید، باید از (express.Router())
  // زمانی که سرور مجدداً راه‌اندازی می‌شود )برای مثال بعد از اینکه کاربر فایل
  // همچنان همان ارجاع `vite.middlewares` (را تغییر می‌دهد، vite.config.js
  // .(های تزریق‌شده توسط پلاگین‌ها middleware‌ و Vite با یک پشته داخلی جدید از) خواهد بود
  // مورد زیر حتی پس از راه‌اندازی مجدد معتبر است
  app.use(vite.middlewares)

  app.use('*all', async (req, res) => {
    // را سرو می‌کنیم - در ادامه به این موضوع خواهیم پرداخت index.html فایل
  })

  app.listen(5173)
}

createServer()
```

در اینجا `vite` یک نمونه از [ViteDevServer](./api-javascript#vitedevserver) است. `vite.middlewares` یک نمونه از [Connect](https://github.com/senchalabs/connect) است که می‌توان از آن به عنوان یک middleware در هر فریم‌ورک Node.js که با connect سازگار است استفاده کرد.

گام بعدی پیاده‌سازی یک handler کلی (`*`) برای سرو HTML رندر شده در سمت سرور است:

```js twoslash [server.js]
// @noErrors
import fs from 'node:fs'
import path from 'node:path'
import { fileURLToPath } from 'node:url'

/** @type {import('express').Express} */
var app
/** @type {import('vite').ViteDevServer}  */
var vite

// ---cut---
app.use('*all', async (req, res, next) => {
  const url = req.originalUrl

  try {
    // 1. index.html خواندن فایل
    let template = fs.readFileSync(
      path.resolve(__dirname, 'index.html'),
      'utf-8',
    )

    // 2. مربوط به HMR شامل تزریق کلاینت .Vite توسط HTML اعمال تغییرات
    //    است Vite توسط پلاگین‌های HTML و همچنین انجام ترنسفورم‌های Vite
    //    @vitejs/plugin-react های سراسری از preamble مثل
    template = await vite.transformIndexHtml(url, template)

    // 3. را طوری تبدیل می‌کند ESM به‌طور خودکار کد ssrLoadModule .بارگذاری ورودی سمت سرور
    //    مشابه، کارایی در HMR قابل اجرا باشد! نیازی به باندل نیست و با Node.js که در
    //    کردن ماژول‌ها دارد invalidate
    const { render } = await vite.ssrLoadModule('/src/entry-server.js')

    // 4. entry-server.js خروجی `render` اپلیکیشن. فرض شده که تابع HTML رندر کردن
    //    فریم‌ورک استفاده می‌کند، SSR های API از
    //    ReactDOMServer.renderToString() مثلاً
    const appHtml = await render(url)

    // 5. HTML رندرشده در قالب HTML قرار دادن
    const html = template.replace(`<!--ssr-outlet-->`, () => appHtml)

    // 6. نهایی به مرورگر HTML ارسال
    res.status(200).set({ 'Content-Type': 'text/html' }).end(html)
  } catch (e) {
    // استک‌ترِیس را اصلاح می‌کند Vite ،در صورت بروز خطا،
    // تا به کد اصلی شما ارجاع دهد
    vite.ssrFixStacktrace(e)
    next(e)
  }
})
```

اسکریپت `dev` در فایل `package.json` نیز باید طوری تغییر داده شود که به‌جای آن از اسکریپت سرور استفاده کند.

```diff [package.json]
  "scripts": {
-   "dev": "vite"
+   "dev": "node server"
  }
```

## ساخت(build) برای محیط پروداکشن

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

1. یک بیلد (build) برای کلاینت مثل همیشه تولید شود؛
2. یک بیلد SSR نیز تولید شود که مستقیماً با `import()‎` بارگذاری شود، تا نیازی به استفاده از `ssrLoadModule` در Vite نباشد.

اسکریپت‌های ما در فایل `package.json` به شکل زیر خواهند بود:

```json [package.json]
{
  "scripts": {
    "dev": "node server",
    "build:client": "vite build --outDir dist/client",
    "build:server": "vite build --outDir dist/server --ssr src/entry-server.js"
  }
}
```

به فلگ `‎--ssr` توجه کنید که نشان می‌دهد این بیلد مخصوص SSR است. همچنین باید ورودی (entry) مربوط به SSR را مشخص کند.

سپس در فایل `server.js` باید منطق مخصوص پروداکشن را اضافه کنیم با بررسی مقدار `process.env.NODE_ENV`:

* به جای خواندن فایل `index.html` از ریشه پروژه، از فایل `dist/client/index.html` به عنوان قالب استفاده کنید، چون این فایل شامل لینک‌های درست برای فایل‌های خروجی کلاینت است.

* به جای استفاده از `await vite.ssrLoadModule('/src/entry-server.js')`، از `import('./dist/server/entry-server.js')` استفاده کنید (این فایل خروجی بیلد SSR است).

* ساخت و استفاده از سرور توسعه `vite` را فقط در حالت توسعه (dev) انجام دهید و در حالت پروداکشن، از میان افزارهای سرو فایل‌های استاتیک برای ارائه فایل‌ها از مسیر `dist/client` استفاده کنید.

برای مشاهده نمونه پیاده‌سازی، به [پروژه‌های نمونه](#example-projects) مراجعه کنید.

## تولید دستورهای پیش بارگذاری

دستور `vite build` از فلگ `‎--ssrManifest` پشتیبانی می‌کند که یک فایل به نام `.vite/ssr-manifest.json` در دایرکتوری خروجی بیلد ایجاد می‌کند:

```diff
- "build:client": "vite build --outDir dist/client",
+ "build:client": "vite build --outDir dist/client --ssrManifest",
```

اسکریپت بالا حالا فایل `dist/client/.vite/ssr-manifest.json` را برای بیلد کلاینت تولید می‌کند (بله، مانیفست SSR از بیلد کلاینت ایجاد می‌شود چون هدف این است که ID های ماژول‌ها را به فایل‌های مربوط به کلاینت متصل کنیم). این مانیفست شامل اطلاعاتی است که به ما می‌گوید هر ID ماژول به کدام بخش‌ها (chunks) و فایل‌های مرتبط با آن ماژول در بیلد کلاینت اشاره دارد.

برای استفاده از مانیفست، فریمورک‌ها باید روشی فراهم کنند تا ID ماژول‌های کامپوننت‌هایی که در هنگام رندر سرور استفاده شده‌اند، جمع‌آوری شوند.

`‎@vitejs/plugin-vue` این قابلیت را به طور پیش‌فرض ارائه می‌دهد و به طور خودکار ID های ماژول کامپوننت‌هایی که در هنگام رندر سرور استفاده شده‌اند را در SSR context مربوط به Vue ثبت می‌کند:

```js [src/entry-server.js]
const ctx = {}
const html = await vueServerRenderer.renderToString(app, ctx)
// ماژول‌هایی است که در طول رندر شدن استفاده شده‌اند ID یک مجموعه از ctx.modules حالا
```

در بخش پروداکشن فایل `server.js`، باید فایل manifest را بخوانیم و آن را به تابع `render` که از `src/entry-server.js` اکسپورت شده، بدهیم. این کار اطلاعات کافی برای تولید دستورهای preload مربوط به فایل‌هایی که در مسیرهای async استفاده شده‌اند را فراهم می‌کند. برای نمونه‌ی کامل، [کد دمو](https://github.com/vitejs/vite-plugin-vue/blob/main/playground/ssr-vue/src/entry-server.js) را ببینید. همچنین می‌توان از این اطلاعات برای ارسال [103 Early Hints](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/103) استفاده کرد.

## پیش‌رندرینگ / تولید سایت ایستا (SSG)

اگر مسیرها (routes) و داده‌های مورد نیاز آن‌ها از قبل مشخص باشند، می‌توان آن‌ها را با استفاده از همان منطق SSR در حالت production، به صورت HTML ایستا (static) پیش‌پردازش کرد. این روش را می‌توان نوعی از تولید سایت ایستا یا SSG نیز در نظر گرفت. برای نمونه‌ی عملی، به [اسکریپت pre-render دمو](https://github.com/vitejs/vite-plugin-vue/blob/main/playground/ssr-vue/prerender.js) مراجعه کنید.

## وابستگی‌های خارجی در SSR

در حالت SSR، وابستگی‌ها به‌صورت پیش‌فرض از سیستم تبدیل ماژول Vite خارج (externalize) می‌شوند. این کار باعث افزایش سرعت در هر دو زمان توسعه (dev) و ساخت (build) پروژه می‌شود.

اگر یک وابستگی نیاز داشته باشد که توسط زنجیره‌ی تبدیل Vite پردازش شود (مثلاً چون از قابلیت‌های Vite به‌صورت مستقیم و بدون تبدیل در آن استفاده شده)، می‌توانید آن را به گزینه‌ی [`ssr.noExternal`](../config/ssr-options.md#ssr-noexternal) اضافه کنید.

وابستگی‌هایی که لینک شده‌اند (مثل آن‌هایی که با `npm link` یا در محیط‌های monorepo استفاده شده‌اند)، به‌صورت پیش‌فرض external نمی‌شوند تا Vite بتواند از HMR استفاده کند. اگر نمی‌خواهید این رفتار اتفاق بیفتد (مثلاً برای شبیه‌سازی شرایطی که انگار وابستگی‌ها لینک نشده‌اند) می‌توانید آن‌ها را به گزینه‌ی [`ssr.external`](../config/ssr-options.md#ssr-external) اضافه کنید.

:::warning کار با aliasها
اگر aliasهایی تعریف کرده‌اید که یک پکیج را به پکیج دیگری هدایت می‌کنند، ممکن است بهتر باشد به‌جای آن، خود پکیج‌های داخل `node_modules` را alias کنید تا قابلیت external شدن آن‌ها در SSR به درستی عمل کند. هر دو ابزار [Yarn](https://classic.yarnpkg.com/en/docs/cli/add/#toc-yarn-add-alias) و [pnpm](https://pnpm.io/aliases/) از alias کردن با پیشوند `npm:‎` پشتیبانی می‌کنند.
:::

## منطق افزونه مخصوص SSR

برخی فریم‌ورک‌ها مثل Vue یا Svelte، کامپوننت‌ها را بسته به این‌که برای کلاینت باشند یا SSR، به شکل‌های مختلفی کامپایل می‌کنند. با استفاده از این ویژگی، افزونه‌ها می‌توانند رفتار متفاوتی در حالت SSR نسبت به کلاینت داشته باشند. برای پشتیبانی از این تبدیل‌های شرطی، Vite یک ویژگی اضافی به نام `ssr` را در آبجکت `options` به هوک‌های زیر از افزونه‌ها منتقل می‌کند:

* `resolveId`
* `load`
* `transform`

**مثال:**

```js twoslash
/** @type {() => import('vite').Plugin} */
// ---cut---
export function mySSRPlugin() {
  return {
    name: 'my-ssr',
    transform(code, id, options) {
      if (options?.ssr) {
        // ... SSR انجام تبدیل مخصوص
      }
    },
  }
}
```

آبجکت `options` که در توابع `load` و `transform` استفاده می‌شود، اختیاری است. Rollup در حال حاضر از این آبجکت استفاده نمی‌کند، اما ممکن است در آینده برای افزودن اطلاعات بیشتر به این hookها از آن استفاده شود.

:::tip نکته
قبل از نسخه 2.7 از Vite، اطلاعات مربوط به SSR به جای اینکه در آبجکت `options` قرار بگیرد، به صورت یک پارامتر جداگانه به توابع پلاگین داده می‌شد. الان بیشتر فریم‌ورک‌ها و پلاگین‌ها به‌روز شده‌اند، ولی ممکن است هنوز در برخی منابع قدیمی نسخه قبلی این روش را ببینید.
:::

## هدف SSR

هدف پیش‌فرض برای ساخت SSR، محیط Node است، اما شما همچنین می‌توانید سرور را در یک Web Worker اجرا کنید. نحوه حل ارجاعات پکیج‌ها برای هر پلتفرم متفاوت است. شما می‌توانید هدف را به Web Worker تغییر دهید با تنظیم `ssr.target` به `'webworker'`.

## بسته‌بندی SSR

در برخی موارد مانند رانتایم `webworker`، ممکن است بخواهید بیلد SSR خود را به در یک فایل جاوا اسکریپت واحد بسته‌بندی (bundle) کنید. شما می‌توانید این رفتار را با تنظیم `ssr.noExternal` به `true` فعال کنید. این کار دو چیز انجام می‌دهد:

* تمام وابستگی‌ها را به عنوان `noExternal` در نظر می‌گیرد.
* اگر هرکدام از کتابخانه‌های داخلی Node.js ایمپورت شوند، یک خطا ایجاد می‌کند.

## شرایط حل بسته برای SSR

به طور پیش‌فرض، برای ساخت SSR، Vite از شرایطی که در [`resolve.conditions`](../config/shared-options.md#resolve-conditions) تنظیم شده است، برای حل ورودی بسته‌ها استفاده می‌کند. شما می‌توانید با استفاده از گزینه‌های [`ssr.resolve.conditions`](../config/ssr-options.md#ssr-resolve-conditions) و [`ssr.resolve.externalConditions`](../config/ssr-options.md#ssr-resolve-externalconditions)، این رفتار را تغییر داده و سفارشی‌سازی کنید.

## Vite CLI

دستورات CLI مانند `‎$ vite dev` و `‎$ vite preview` می‌توانند برای برنامه‌های SSR نیز استفاده شوند. شما می‌توانید میدل‌ورهای SSR خود را با استفاده از [`configureServer`](/guide/api-plugin#configureserver) به سرور توسعه و با استفاده از [`configurePreviewServer`](/guide/api-plugin#configurepreviewserver) به سرور پیش‌نمایش اضافه کنید.

:::tip نکته
از هوک پس از عملیات استفاده کنید تا میانه‌افزار SSR شما *پس از* میدل‌ورهای Vite اجرا شود.
:::

---

---
url: /guide/build.md
---
# ساخت برای محیط پروداکشن

هنگامی که زمان استقرار اپلیکیشن برای محیط پروداکشن فرا می‌رسد، کافی است دستور `vite build` را اجرا کنید. به طور پیش‌فرض، این دستور از فایل `root>/index.html>` به عنوان نقطه ورود ساخت استفاده می‌کند و یک بسته اپلیکیشن تولید می‌کند که برای میزبانی روی سرویس‌های میزبانی استاتیک مناسب است. برای راهنمایی درباره سرویس‌های محبوب، بخش [استقرار سایت استاتیک](./static-deploy) را بررسی کنید.

## سازگاری با مرورگرها

به‌صورت پیش‌فرض، بسته تولید (production bundle) فرض می‌کند که مرورگر مدرن و رایجی استفاده می‌شود که در [Baseline](https://web-platform-dx.github.io/web-features/) (قابل‌دسترس به‌طور گسترده) قرار دارد.
محدوده پیش‌فرض پشتیبانی مرورگرها به شرح زیر است:

* Chrome >=107
* Edge >=107
* Firefox >=104
* Safari >=16

می‌توانید هدف‌های سفارشی را از طریق [گزینه تنظیمات `build.target`](/config/build-options.md#build-target) مشخص کنید، که پایین‌ترین هدف `es2015` است. اگر هدف پایین‌تری تنظیم شود، Vite همچنان به حداقل محدوده پشتیبانی مرورگرها نیاز دارد، زیرا به [ایمپورت پویای ESM بومی](https://caniuse.com/es6-module-dynamic-import) و [`import.meta`](https://caniuse.com/mdn-javascript_operators_import_meta) وابسته است:

* Chrome >=64
* Firefox >=67
* Safari >=11.1
* Edge >=79

توجه داشته باشید که به‌صورت پیش‌فرض، Vite تنها وظیفه‌ی تبدیل سینتکس (syntax transforms) را بر عهده دارد و **شامل پلی‌فیل‌ها (polyfills) نمی‌شود**. می‌توانید از وب‌سایت <https://cdnjs.cloudflare.com/polyfill/> استفاده کنید که بر اساس رشته‌ی UserAgent مرورگر کاربر، به‌صورت خودکار بسته‌ی مناسب پلی‌فیل را تولید می‌کند.

مرورگرهای قدیمی‌تر می‌توانند از طریق پلاگین [vitejs/plugin-legacy@](https://github.com/vitejs/vite/tree/main/packages/plugin-legacy) پشتیبانی شوند، که به طور خودکار چانک‌های قدیمی و پلی‌فیل‌های مربوط به ویژگی‌های زبان ES را تولید می‌کند. چانک‌های قدیمی تنها در مرورگرهایی که از ESM بومی پشتیبانی نمی‌کنند، به صورت شرطی بارگذاری می‌شوند.

## مسیر پایه عمومی {#public-base-path}

* مرتبط: [مدیریت asset ها](./assets)

اگر پروژه خود را در یک مسیر عمومی تودرتو مستقر می‌کنید، کافی است [گزینه تنظیمات `base`](/config/shared-options.md#base) را مشخص کنید تا همه مسیرهای asset ها به طور متناسب بازنویسی شوند. این گزینه همچنین می‌تواند به عنوان پرچم خط فرمان مشخص شود، مثلاً `/vite build --base=/my/public/path` .

آدرس asset های ایمپورت‌شده در جاوااسکریپت، ارجاعات `()url` در CSS و ارجاعات asset در فایل‌های `html.` به طور خودکار برای رعایت این گزینه در طول ساخت تنظیم می‌شوند.

استثنا زمانی است که نیاز دارید آدرس‌ها را به صورت پویا در لحظه ترکیب کنید. در این مورد، می‌توانید از متغیر سراسری تزریق‌شده `import.meta.env.BASE_URL` استفاده کنید که همان مسیر پایه عمومی خواهد بود. توجه داشته باشید که این متغیر در طول ساخت به صورت استاتیک جایگزین می‌شود، بنابراین باید دقیقاً به همان شکل استفاده شود (یعنی `import.meta.env['BASE_URL']` کار نخواهد کرد).

برای کنترل پیشرفته مسیر پایه، [گزینه‌های پیشرفته پایه](#advanced-base-options) را بررسی کنید.

### مسیر پایه نسبی

اگر مسیر پایه را از قبل نمی‌دانید، می‌توانید یک مسیر پایه نسبی با `‎"base": "./"‎` یا `‎"base": ""‎` تنظیم کنید. این کار باعث می‌شود همه آدرس‌های تولیدشده نسبت به هر فایل نسبی باشند.

:::warning پشتیبانی از مرورگرهای قدیمی‌تر هنگام استفاده از مسیرهای پایه نسبی

پشتیبانی از `import.meta` برای مسیرهای پایه نسبی مورد نیاز است. اگر نیاز به پشتیبانی از [مرورگرهایی دارید که از `import.meta` پشتیبانی نمی‌کنند](https://caniuse.com/mdn-javascript_operators_import_meta)، می‌توانید از [پلاگین `legacy`](https://github.com/vitejs/vite/tree/main/packages/plugin-legacy) استفاده کنید.

:::

## سفارشی‌سازی ساخت

ساخت را می‌توان از طریق [گزینه‌های تنظیمات ساخت](/config/build-options.md) سفارشی کرد. به طور خاص، می‌توانید [گزینه‌های Rollup](https://rollupjs.org/configuration-options/) را مستقیماً از طریق `build.rollupOptions` تنظیم کنید:

```js [vite.config.js]
export default defineConfig({
  build: {
    rollupOptions: {
      // https://rollupjs.org/configuration-options/
    },
  },
})
```

برای مثال، می‌توانید چند نسخه خروجی مختلف برای Rollup مشخص کنید و از پلاگین‌هایی استفاده نمایید که فقط هنگام ساخت (build) پروژه اعمال می‌شوند.

## استراتژی تقسیم چانک‌ها

می‌توانید نحوه تقسیم چانک‌ها را با استفاده از `build.rollupOptions.output.manualChunks` (به [مستندات Rollup](https://rollupjs.org/configuration-options/#output-manualchunks) مراجعه کنید) پیکربندی کنید. اگر از یک فریم‌ورک استفاده می‌کنید، به مستندات آن‌ها برای تنظیم نحوه تقسیم چانک‌ها مراجعه کنید.

## مدیریت خطای بارگذاری

Vite در صورت شکست بارگذاری ایمپورت‌های پویا، رویداد `vite:preloadError` را منتشر می‌کند. `event.payload` شامل خطای ایمپورت اصلی است. اگر `event.preventDefault()‎` را فراخوانی کنید، خطا صادر نخواهد شد.

```js twoslash
window.addEventListener('vite:preloadError', (event) => {
  window.location.reload() // برای مثال، تازه‌سازی صفحه
})
```

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

## بازسازی هنگام تغییر فایل‌ها

می‌توانید ناظر Rollup را با `vite build --watch` فعال کنید. یا می‌توانید [گزینه‌های ناظر](https://rollupjs.org/configuration-options/#watch) را مستقیماً از طریق `build.watch` تنظیم کنید:

```js [vite.config.js]
export default defineConfig({
  build: {
    watch: {
      // https://rollupjs.org/configuration-options/#watch
    },
  },
})
```

با فعال بودن پرچم `‎--watch`، تغییرات در `vite.config.js` و همچنین هر فایل دیگری که باید بسته‌بندی شود، باعث بازسازی می‌شود.

## اپلیکیشن چندصفحه‌ای

فرض کنید ساختار کد منبع شما به صورت زیر است:

```
├── package.json
├── vite.config.js
├── index.html
├── main.js
└── nested
    ├── index.html
    └── nested.js
```

در طول توسعه، کافی است به `/nested/` بروید یا به آن لینک دهید - همان‌طور که انتظار می‌رود، مانند یک سرور فایل استاتیک معمولی کار می‌کند.

در طول ساخت، تنها کاری که باید انجام دهید این است که چندین فایل `html.` را به عنوان نقاط ورود مشخص کنید:

```js twoslash [vite.config.js]
import { dirname, resolve } from 'node:path'
import { fileURLToPath } from 'node:url'
import { defineConfig } from 'vite'

const __dirname = dirname(fileURLToPath(import.meta.url))

export default defineConfig({
  build: {
    rollupOptions: {
      input: {
        main: resolve(__dirname, 'index.html'),
        nested: resolve(__dirname, 'nested/index.html'),
      },
    },
  },
})
```

اگر ریشه متفاوتی مشخص کنید، به یاد داشته باشید که `dirname__` همچنان پوشه فایل `vite.config.js` شما خواهد بود هنگام رفع مسیرهای ورودی. بنابراین، باید ورودی `root` خود را به آرگومان‌های `resolve` اضافه کنید.

توجه داشته باشید که برای فایل‌های HTML، نام داده‌شده به ورودی در آبجکت `rollupOptions.input` نادیده گرفته می‌شود و در عوض، شناسه رفع‌شده فایل را هنگام تولید asset HTML در پوشه dist رعایت می‌کند. این امر ساختار ثابتی با نحوه عملکرد سرور توسعه تضمین می‌کند.

## حالت کتابخانه

هنگامی که یک کتابخانه متمرکز بر مرورگر توسعه می‌دهید، احتمالاً بیشتر زمان خود را صرف یک صفحه آزمایشی/دمو می‌کنید که کتابخانه واقعی شما را ایمپورت می‌کند. با Vite، می‌توانید از `index.html` خود برای این منظور استفاده کنید تا تجربه توسعه روان داشته باشید.

هنگامی که زمان بسته‌بندی کتابخانه برای توزیع فرا می‌رسد، از [گزینه تنظیمات `build.lib`](/config/build-options.md#build-lib) استفاده کنید. مطمئن شوید که هر وابستگی‌ای که نمی‌خواهید در کتابخانه شما بسته‌بندی شود، مانند `vue` یا `react`، خارجی‌سازی کنید:

::: code-group

```js twoslash [vite.config.js (ورودی تک)]
import { dirname, resolve } from 'node:path'
import { fileURLToPath } from 'node:url'
import { defineConfig } from 'vite'

const __dirname = dirname(fileURLToPath(import.meta.url))

export default defineConfig({
  build: {
    lib: {
      entry: resolve(__dirname, 'lib/main.js'),
      name: 'MyLib',
      // پسوندهای مناسب اضافه خواهند شد
      fileName: 'my-lib',
    },
    rollupOptions: {
      // اطمینان حاصل کنید وابستگی‌هایی که نباید در کتابخانه بسته‌بندی شوند، خارجی‌سازی شوند

      external: ['vue'],
      output: {
        //  برای وابستگی‌های خارجی‌شده فراهم کنید UMD متغیرهای سراسری برای استفاده در ساخت

        globals: {
          vue: 'Vue',
        },
      },
    },
  },
})
```

```js twoslash [vite.config.js (ورودی‌های چندگانه)]
import { dirname, resolve } from 'node:path'
import { fileURLToPath } from 'node:url'
import { defineConfig } from 'vite'

const __dirname = dirname(fileURLToPath(import.meta.url))

export default defineConfig({
  build: {
    lib: {
      entry: {
        'my-lib': resolve(__dirname, 'lib/main.js'),
        secondary: resolve(__dirname, 'lib/secondary.js'),
      },
      name: 'MyLib',
    },
    rollupOptions: {
      // اطمینان حاصل کنید وابستگی‌هایی که نباید در کتابخانه بسته‌بندی شوند، خارجی‌سازی شوند

      external: ['vue'],
      output: {
        // برای وابستگی‌های خارجی‌شده فراهم کنید UMD متغیرهای سراسری برای استفاده در ساخت

        globals: {
          vue: 'Vue',
        },
      },
    },
  },
})
```

:::

فایل ورودی شامل اکسپورت‌هایی خواهد بود که کاربران بسته شما می‌توانند ایمپورت کنند:

```js [lib/main.js]
import Foo from './Foo.vue'
import Bar from './Bar.vue'
export { Foo, Bar }
```

اجرای `vite build` با این پیکربندی از یک پیش‌تنظیم Rollup استفاده می‌کند که برای انتشار کتابخانه‌ها مناسب است و دو فرمت بسته تولید می‌کند:

* `es` و `umd` (برای ورودی تک)
* `es` و `cjs` (برای ورودی‌های چندگانه)

فرمت‌ها را می‌توان با [گزینه `build.lib.formats`](/config/build-options.md#build-lib) پیکربندی کرد.

```
$ vite build
...ساخت برای پروداکشن
dist/my-lib.js      0.08 kB / gzip: 0.07 kB
dist/my-lib.umd.cjs 0.30 kB / gzip: 0.16 kB
```

`package.json` پیشنهادی برای کتابخانه شما:

::: code-group

```json [package.json (ورودی تک)]
{
  "name": "my-lib",
  "type": "module",
  "files": ["dist"],
  "main": "./dist/my-lib.umd.cjs",
  "module": "./dist/my-lib.js",
  "exports": {
    ".": {
      "import": "./dist/my-lib.js",
      "require": "./dist/my-lib.umd.cjs"
    }
  }
}
```

```json [package.json (ورودی‌های چندگانه)]
{
  "name": "my-lib",
  "type": "module",
  "files": ["dist"],
  "main": "./dist/my-lib.cjs",
  "module": "./dist/my-lib.js",
  "exports": {
    ".": {
      "import": "./dist/my-lib.js",
      "require": "./dist/my-lib.cjs"
    },
    "./secondary": {
      "import": "./dist/secondary.js",
      "require": "./dist/secondary.cjs"
    }
  }
}
```

:::

### پشتیبانی از CSS

اگر کتابخانه شما CSS ایمپورت کند، این CSS به عنوان یک فایل CSS واحد در کنار فایل‌های JS ساخته‌شده بسته‌بندی می‌شود، مثلاً `dist/my-lib.css`. نام به طور پیش‌فرض به `build.lib.fileName` وابسته است، اما می‌توان آن را با [گزینه `build.lib.cssFileName`](/config/build-options.md#build-lib) تغییر داد.

می‌توانید فایل CSS را در `package.json` خود اکسپورت کنید تا کاربران بتوانند آن را وارد کنند:

```json {12}
{
  "name": "my-lib",
  "type": "module",
  "files": ["dist"],
  "main": "./dist/my-lib.umd.cjs",
  "module": "./dist/my-lib.js",
  "exports": {
    ".": {
      "import": "./dist/my-lib.js",
      "require": "./dist/my-lib.umd.cjs"
    },
    "./style.css": "./dist/my-lib.css"
  }
}
```

::: tip پسوندهای فایل
اگر `package.json` شامل `"type": "module"` نباشد، Vite برای سازگاری با Node.js پسوندهای متفاوتی تولید می‌کند. `js.` به `mjs.` و `cjs.` به `js.` تبدیل می‌شود.
:::

::: tip متغیرهای محیطی
در حالت کتابخانه، تمام استفاده‌های [`*.import.meta.env`](./env-and-mode.md) در زمان ساخت برای تولید به صورت استاتیک جایگزین می‌شوند. با این حال، استفاده‌های `*.process.env` جایگزین نمی‌شوند تا مصرف‌کنندگان کتابخانه شما بتوانند آن‌ها را به صورت پویا تغییر دهند. اگر این رفتار مطلوب نیست، می‌توانید به عنوان مثال از `define: { 'process.env.NODE_ENV': '"production"' }‎` برای جایگزینی استاتیک آن‌ها استفاده کنید یا از [`esm-env`](https://github.com/benmccann/esm-env) برای سازگاری بهتر با باندلرها و ران‌تایم‌ها استفاده کنید.
:::

::: warning استفاده پیشرفته
حالت کتابخانه شامل پیکربندی ساده و نظرشده‌ای برای کتابخانه‌های متمرکز بر مرورگر و فریم‌ورک‌های جاوااسکریپت است. اگر کتابخانه‌های غیرمرورگری می‌سازید یا به جریان‌های ساخت پیشرفته نیاز دارید، می‌توانید مستقیماً از [Rollup](https://rollupjs.org) یا [esbuild](https://esbuild.github.io) استفاده کنید.
:::

## گزینه‌های پیشرفته پایه {#advanced-base-options}

::: warning هشدار
این ویژگی آزمایشی است. [بازخورد دهید](https://github.com/vitejs/vite/discussions/13834).
:::

برای موارد استفاده پیشرفته، asset های مستقرشده و فایل‌های عمومی ممکن است در مسیرهای مختلفی قرار گیرند، برای مثال برای استفاده از استراتژی‌های کش متفاوت.
کاربر ممکن است بخواهد در سه مسیر مختلف مستقر کند:

* فایل‌های HTML ورودی تولیدشده (که ممکن است در طول SSR پردازش شوند)
* asset های هش‌شده تولیدشده (JS ، CSS و انواع فایل‌های دیگر مانند تصاویر)
* فایل‌های [عمومی](assets.md#the-public-directory) کپی‌شده

یک [پایه](#public-base-path) استاتیک واحد در این سناریوها کافی نیست. Vite پشتیبانی آزمایشی برای گزینه‌های پیشرفته پایه در طول ساخت ارائه می‌دهد، با استفاده از `experimental.renderBuiltUrl`.

```ts twoslash
import type { UserConfig } from 'vite'
// prettier-ignore
const config: UserConfig = {
// ---cut-before---
experimental: {
  renderBuiltUrl(filename, { hostType }) {
    if (hostType === 'js') {
      return { runtime: `window.__toCdnUrl(${JSON.stringify(filename)})` }
    } else {
      return { relative: true }
    }
  },
},
// ---cut-after---
}
```

اگر asset های هش‌شده و فایل‌های عمومی با هم مستقر نشوند، گزینه‌ها برای هر گروه می‌توانند به طور مستقل با استفاده از `type` asset که در پارامتر دوم `context` به تابع داده شده است، تعریف شوند.

```ts twoslash
import type { UserConfig } from 'vite'
import path from 'node:path'
// prettier-ignore
const config: UserConfig = {
// ---cut-before---
experimental: {
  renderBuiltUrl(filename, { hostId, hostType, type }) {
    if (type === 'public') {
      return 'https://www.domain.com/' + filename
    } else if (path.extname(hostId) === '.js') {
      return {
        runtime: `window.__assetsPath(${JSON.stringify(filename)})`
      }
    } else {
      return 'https://cdn.domain.com/assets/' + filename
    }
  },
},
// ---cut-after---
}
```

توجه داشته باشید که `filename` ارسالی یک URL رمزگشایی‌شده است، و اگر تابع یک رشته URL بازگرداند، باید آن هم رمزگشایی‌شده باشد. Vite هنگام رندر کردن URLها به طور خودکار رمزگذاری را مدیریت می‌کند. اگر یک آبجکت با `runtime` بازگردانده شود، رمزگذاری باید در صورت نیاز توسط خودتان مدیریت شود، زیرا کد ران‌تایم همان‌طور که هست رندر خواهد شد.

---

---
url: /guide.md
---
# شروع

## مرور کلی

Vite (یک کلمه فرانسوی به معنای "سریع"، که `/vit/` تلفظ می‌شود، مانند "ویت") یک ابزار بیلد است که هدف آن ارائه تجربه توسعه سریع‌تر و سبک‌تر برای پروژه‌های وب مدرن است. این ابزار از دو بخش اصلی تشکیل شده است:

یک سرور توسعه که [ویژگی‌های پیشرفته‌تری](./features) را برای [ماژول‌های ES بومی](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) فراهم می‌کند. از جمله این ویژگی‌ها، [جایگزینی سریع ماژول (HMR)](./features#hot-module-replacement) با عملکردی بسیار بهینه است.

* یک کامَند بیلد که کد شما را با [Rollup](https://rollupjs.org) باندل می‌کند، که آماده شده تا فایل‌های استاتیک بسیار بهینه‌شده برای پروداکشن بسازد.

Vite با یک نگرش خاص طراحی شده و تنظیمات پیش‌فرض معقولی را ارائه می‌دهد. برای آشنایی با امکانات بیشتر، می‌توانید به [راهنمای ویژگی‌ها](./features) مراجعه کنید. همچنین، امکان پشتیبانی از فریم‌ورک‌ها و ادغام با سایر ابزارها از طریق [پلاگین‌ها](./using-plugins) وجود دارد. در [بخش تنظیمات](../config/) نیز توضیح داده‌ایم که چگونه Vite را متناسب با نیازهای پروژه خود سفارشی کنید.

Vite همچنین از طریق [API پلاگین](./api-plugin) و [API جاوااسکریپت](./api-javascript) با پشتیبانی کامل از تایپ‌ها، به شدت قابل توسعه است.

می‌توانید برای آشنایی بیشتر با دلایل پشت پروژه به بخش [چرا Vite](./why) مراجعه کنید.

## پشتیبانی مرورگر

در طول فرآیند توسعه، Vite فرض می‌کند که از یک مرورگر مدرن استفاده می‌شود. یعنی مرورگری که از بیشتر قابلیت‌های جدید JavaScript و CSS پشتیبانی می‌کند. به همین دلیل، Vite هدف تبدیل کد را روی [`esnext`](https://esbuild.github.io/api/#target) تنظیم می‌کند. این کار باعث می‌شود کدها به شکل اصلی خود باقی بمانند و نیازی به تبدیل به نسخه‌های قدیمی‌تر نداشته باشند. در نتیجه، Vite ماژول‌ها را تا حد ممکن نزدیک به سورس اصلی ارائه می‌دهد. Vite برای راه‌اندازی سرور توسعه، مقداری کد رانتایم به پروژه اضافه می‌کند. این کدها از ویژگی‌هایی استفاده می‌کنند که در [Baseline](https://web-platform-dx.github.io/web-features/) در زمان هر نسخه اصلی جدید (مثلاً برای این نسخه در تاریخ ۱ مه ۲۰۲۵) در دسترس بوده‌اند.

برای ساخت نسخه پروداکشن، Vite به‌طور پیش‌فرض مرورگرهایی را هدف قرار می‌دهد که در دسته [Baseline Widely Available](https://web-platform-dx.github.io/web-features/) قرار دارند، یعنی مرورگرهایی که حداقل ۲.۵ سال پیش منتشر شده‌اند. این هدف را می‌توان از طریق کانفیگ کاهش داد. علاوه‌براین، پشتیبانی از مرورگرهای قدیمی‌تر نیز از طریق افزونه رسمی [‎@vitejs/plugin-legacy](https://github.com/vitejs/vite/tree/main/packages/plugin-legacy) امکان‌پذیر است. برای جزئیات بیشتر به بخش [ساخت برای محیط پروداکشن](./build) مراجعه کنید.

## امتحان Vite به صورت آنلاین

می‌توانید Vite را به صورت آنلاین در [StackBlitz](https://vite.new/) امتحان کنید. این ابزار، تنظیمات بیلد مبتنی بر Vite را مستقیماً در مرورگر شما اجرا می‌کند، بنابراین تقریباً با تنظیمات لوکال (local) مشابه است اما نیازی به نصب هیچ چیزی بر روی دستگاه شما ندارد. می‌توانید به `vite.new/{template}` بروید تا فریم‌ورک مورد نظر خود را انتخاب کنید.

قالب‌های پشتیبانی شده عبارتند از:

|             JavaScript              |                TypeScript                 |
| :---------------------------------: | :---------------------------------------: |
| [vanilla](https://vite.new/vanilla) | [vanilla-ts](https://vite.new/vanilla-ts) |
|     [vue](https://vite.new/vue)     |     [vue-ts](https://vite.new/vue-ts)     |
|   [react](https://vite.new/react)   |   [react-ts](https://vite.new/react-ts)   |
|  [preact](https://vite.new/preact)  |  [preact-ts](https://vite.new/preact-ts)  |
|     [lit](https://vite.new/lit)     |     [lit-ts](https://vite.new/lit-ts)     |
|  [svelte](https://vite.new/svelte)  |  [svelte-ts](https://vite.new/svelte-ts)  |
|   [solid](https://vite.new/solid)   |   [solid-ts](https://vite.new/solid-ts)   |
|    [qwik](https://vite.new/qwik)    |    [qwik-ts](https://vite.new/qwik-ts)    |

## ساخت اولین پروژه Vite شما

::: tip نکته سازگاری
Vite به نسخه ۲۰.۱۹ یا بالاتر و همچنین ۲۲.۱۲ یا بالاتر از [Node.js](https://nodejs.org/en/) نیاز دارد. با این حال، برخی قالب‌ها برای کار نیاز به نسخه بالاتری از Node.js دارند. لطفاً اگر پکیج منیحر شما هشدار می‌دهد، Node.js را به‌روزرسانی کنید.
:::

::: code-group

```bash [npm]
$ npm create vite@latest
```

```bash [Yarn]
$ yarn create vite
```

```bash [pnpm]
$ pnpm create vite
```

```bash [Bun]
$ bun create vite
```

```bash [Deno]
$ deno init --npm vite
```

:::

سپس مراحل را دنبال کنید!

همچنین می‌توانید با استفاده از آپشن‌های اضافی خط فرمان، نام پروژه و قالب مورد نظر خود را مستقیماً مشخص کنید. به عنوان مثال، برای ایجاد یک پروژه Vite با Vue این دستور را اجرا کنید:

::: code-group

```bash [npm]
# npm 7+ , دو خط تیره اضافی مورد نیاز است:
$ npm create vite@latest my-vue-app -- --template vue
```

```bash [Yarn]
$ yarn create vite my-vue-app --template vue
```

```bash [pnpm]
$ pnpm create vite my-vue-app --template vue
```

```bash [Bun]
$ bun create vite my-vue-app --template vue
```

```bash [Deno]
$ deno init --npm vite my-vue-app --template vue
```

:::

برای جزئیات بیشتر درباره قالب‌های پشتیبانی شده به [create-vite](https://github.com/vitejs/vite/tree/main/packages/create-vite) مراجعه کنید: `vanilla` ، `vanilla-ts` ، `vue` ، `vue-ts` ، `react` ، `react-ts` ، `react-swc` ، `react-swc-ts` ، `preact` ، `preact-ts` ، `lit` ، `lit-ts` ، `svelte` ، `svelte-ts` ، `solid` ، `solid-ts` ، `qwik`، `qwik-ts`.

می‌توانید از `.` برای نام پروژه استفاده کنید تا در دایرکتوری فعلی، ساختار پروژه ایجاد شود.

## قالب‌های ارائه شده توسط جامعه

create-vite ابزاری است برای شروع سریع یک پروژه از یک قالب پایه برای فریم‌ورک‌های محبوب. می‌توانید Awesome Vite را برای [قالب‌های نگهداری شده توسط جامعه](https://github.com/vitejs/awesome-vite#templates) که شامل ابزارهای دیگر یا فریم‌ورک‌های مختلف هستند، بررسی کنید.

برای استفاده قالبی که در `https://github.com/user/project` منتشر شده، می‌توانید آن را به صورت آنلاین با استفاده از `https://github.stackblitz.com/user/project` امتحان کنید (با اضافه کردن `‎.stackblitz` بعد از `github` به URL پروژه).

همچنین می‌توانید از ابزاری مانند [degit](https://github.com/Rich-Harris/degit) برای ساخت پروژه خود با یکی از قالب‌ها استفاده کنید. با فرض اینکه پروژه در GitHub است و از `main` به عنوان برنچ پیش‌فرض استفاده می‌کند، می‌توان یک کپی محلی با این دستور ایجاد کرد:

```bash
npx degit user/project#main my-project
cd my-project

npm install
npm run dev
```

## نصب دستی

در پروژه خود، می‌توانید ابزار خط فرمان `vite` را با استفاده از دستور زیر نصب کنید:

::: code-group

```bash [npm]
$ npm install -D vite
```

```bash [Yarn]
$ yarn add -D vite
```

```bash [pnpm]
$ pnpm add -D vite
```

```bash [Bun]
$ bun add -D vite
```

```bash [Deno]
$ deno add -D npm:vite
```

:::

و یک فایل `index.html` به شکل زیر ایجاد کنید:

```html
<p>Hello Vite!</p>
```

سپس دستور CLI مناسب را در ترمینال خود اجرا کنید:

::: code-group

```bash [npm]
$ npx vite
```

```bash [Yarn]
$ yarn vite
```

```bash [pnpm]
$ pnpm vite
```

```bash [Bun]
$ bunx vite
```

```bash [Deno]
$ deno run -A npm:vite
```

:::

`index.html` در `http://localhost:5173` سرو می‌شود.

## `index.html` و ریشه (Root) پروژه

یک نکته‌ای که ممکن است متوجه شده باشید این است که در یک پروژه Vite، فایل `index.html` در مرکز توجه قرار دارد به جای اینکه در داخل `public` پنهان شده باشد. این عمدی است: در طول توسعه، Vite یک سرور است و `index.html` نقطه ورود به برنامه شما است.

Vite فایل `index.html` را به‌عنوان بخشی از گراف ماژول‌ها و یکی از منابع اصلی کد در نظر می‌گیرد. این ابزار تگ اسکریپت `‎<script type="module" src="...">‎` را پردازش کرده و به کد جاوااسکریپت شما اعمال می‌کند. حتی تگ‌های `‎<script type="module">‎` داخلی و فایل‌های CSS که از طریق `<link href="...">` ارجاع داده شده‌اند نیز از قابلیت‌های ویژه‌ی Vite بهره‌مند می‌شوند. علاوه بر این، URLهای درون `index.html` به‌صورت خودکار تنظیم می‌شوند، بنابراین نیازی به استفاده از نگهدارنده‌هایی مانند `%PUBLIC_URL%` نخواهید داشت.

مشابه سرورهای HTTP استاتیک، Vite مفهومی با نام "دایرکتوری ریشه" را دارد که فایل‌های شما از آنجا سرو می‌شوند. شما آن را به عنوان `<root>` در بقیه مستندات مشاهده خواهید کرد. URLهای مطلق در سورس کد شما با استفاده از ریشه پروژه به عنوان پایه پردازش می‌شوند، بنابراین می‌توانید کدی بنویسید که انگار با یک سرور فایل استاتیک عادی کار می‌کنید (جز اینکه بسیار قدرتمندتر!). Vite همچنین قادر به مدیریت وابستگی‌هایی است که در مکان‌های خارج از سیستم فایل ریشه پردازش می‌شوند، که استفاده از آن را حتی در تنظیمات مبتنی بر مونوریپو امکان‌پذیر می‌سازد.

Vite همچنین از [برنامه‌های چند صفحه‌ای](./build#multi-page-app) با چندین نقطه ورود `‎.html` پشتیبانی می‌کند.

#### تعیین ریشه (Root) جایگزین

`vite` سرور توسعه را با استفاده از دایرکتوری کاری فعلی به عنوان ریشه راه‌اندازی می‌کند. شما می‌توانید ریشه جایگزینی را با استفاده از `vite serve some/sub/dir` مشخص کنید.
توجه داشته باشید که Vite همچنین [فایل پیکربندی خود (یعنی `vite.config.js`)](/config/#configuring-vite) را در داخل ریشه پروژه حل و فصل می‌کند، بنابراین اگر ریشه تغییر کند باید آن را جابجا کنید.

## رابط خط فرمان (CLI)

در پروژه‌ای که Vite نصب شده است، می‌توانید از باینری `vite` در اسکریپت‌های npm خود استفاده کنید، یا مستقیماً آن را با `npx vite` اجرا کنید. در اینجا اسکریپت‌های پیش‌فرض npm در یک پروژه ساخته‌شده شده با Vite آورده شده است:

```json [package.json]
{
  "scripts": {
    "dev": "vite", // `vite dev` ، `vite serve` :شروع سرور توسعه، نام‌های جایگزین
    "build": "vite build", // بیلد برای پروداکشن
    "preview": "vite preview" // پیش‌نمایش بیلد پروداکشن به صورت محلی
  }
}
```

می‌توانید گزینه‌های CLI اضافی مانند `‎--port` یا `‎--open` را مشخص کنید. برای مشاهده لیست کامل گزینه‌های CLI، دستور `npx vite --help` را در پروژه خود اجرا کنید.

بیشتر در مورد [رابط خط فرمان (CLI)](./cli.md) یاد بگیرید

## استفاده از کامیت‌های منتشر نشده

اگر برای امتحان ویژگی‌های جدید نمی‌توانید منتظر نسخه جدید باشید، می‌توانید یک کامیت مشخص از vite را با استفاده از https://pkg.pr.new نصب کنید:

::: code-group

```bash [npm]
$ npm install -D https://pkg.pr.new/vite@SHA
```

```bash [Yarn]
$ yarn add -D https://pkg.pr.new/vite@SHA
```

```bash [pnpm]
$ pnpm add -D https://pkg.pr.new/vite@SHA
```

```bash [Bun]
$ bun add -D https://pkg.pr.new/vite@SHA
```

:::

`SHA` را با هر یک از [commit SHA های Vite](https://github.com/vitejs/vite/commits/main/) جایگزین کنید. توجه داشته باشید که فقط commit‌های مربوط به ماه گذشته کار می‌کنند، زیرا نسخه‌های قدیمی‌تر پاک می‌شوند.

به طور جایگزین، می‌توانید مخزن [vite](https://github.com/vitejs/vite) را در ماشین محلی خود کلون کرده و سپس آن را خودتان بسازید و لینک کنید ([pnpm](https://pnpm.io/) مورد نیاز است):

```bash
git clone https://github.com/vitejs/vite.git
cd vite
pnpm install
cd packages/vite
pnpm run build
pnpm link --global # از پکیج منیجر دلخواه خود برای این مرحله استفاده کنید
```

سپس به پروژه مبتنی بر Vite خود بروید و دستور `pnpm link --global vite` را اجرا کنید (یا مدیریت بسته‌ای که برای لینک کردن `vite` به صورت سراسری استفاده کرده‌اید). حالا سرور توسعه را مجدداً راه‌اندازی کنید تا در کنار آخرین ویژگی‌ها پیشرو باشید!

::: tip وابستگی‌ها با استفاده از Vite
برای جایگزینی نسخه Vite که به طور غیرمستقیم توسط وابستگی‌ها استفاده می‌شود، باید از [npm overrides](https://docs.npmjs.com/cli/v11/configuring-npm/package-json#overrides) یا [pnpm overrides](https://pnpm.io/package_json#pnpmoverrides) استفاده کنید.
:::

## جامعه (Community)

اگر سوالی دارید یا به کمک نیاز دارید، با جامعه در [Discord](https://chat.vite.dev) و [GitHub Discussions](https://github.com/vitejs/vite/discussions) تماس بگیرید.

---

---
url: /guide/performance.md
---
# عملکرد

در حالی که Vite به‌صورت پیش‌فرض سریع است، با گسترش نیازهای پروژه، مشکلات عملکردی (Performance) ممکن است به وجود بیایند. این راهنما به شما کمک می‌کند تا مشکلات رایج عملکردی (Performance) را شناسایی و برطرف کنید، از جمله:

* شروع کند سرور
* بارگذاری کند صفحات
* بیلدهای کند (Slow builds)

## تنظیمات مرورگر خود را بررسی کنید

برخی از اکستنشن‌های مرورگر ممکن است با درخواست‌ها تداخل داشته باشند و زمان شروع و بارگذاری مجدد برنامه‌های بزرگ را کند کنند، به‌ویژه زمانی که از ابزارهای توسعه‌دهنده مرورگر استفاده می‌کنید. پیشنهاد می‌کنیم در این موارد، یک پروفایل مخصوص توسعه (dev-only) بدون اکستنشن‌ها ایجاد کنید یا به حالت ناشناس (Incognito mode) بروید، در حالی که از سرور توسعه Vite استفاده می‌کنید. حالت ناشناس (Incognito mode) همچنین باید سریع‌تر از پروفایل معمولی بدون اکستنشن‌ها باشد.

سرور توسعه‌ی Vite از کش سخت‌افزاری (hard caching) برای وابستگی‌های از پیش بسته‌بندی‌شده (pre-bundled) استفاده می‌کند و پاسخ‌های سریع 304 برای کد سورس پیاده‌سازی می‌کند. غیرفعال‌کردن کش در حالی که ابزارهای توسعه‌ی مرورگر (Dev Tools) باز هستند، می‌تواند تأثیر زیادی روی زمان راه‌اندازی و بارگذاری مجدد کامل صفحه داشته باشد. لطفاً بررسی کنید که گزینه‌ی "غیرفعال‌کردن کش" (Disable Cache) در هنگام کار با سرور Vite فعال نباشد.

## بررسی پلاگین‌های تنظیم‌شده‌ی Vite

پلاگین‌های داخلی و رسمی Vite به‌گونه‌ای بهینه‌سازی شده‌اند که کمترین میزان کار ممکن را انجام دهند و در عین حال سازگاری با اکوسیستم گسترده‌تر را فراهم کنند. به عنوان مثال، تبدیل‌های کد (code transformations) در محیط توسعه (dev) از regex استفاده می‌کنند، اما در مرحله‌ی ساخت (build)، یک تجزیه‌ی کامل (complete parse) انجام می‌شود تا صحت کد تضمین شود.

با این حال، عملکرد پلاگین‌های جامعه (community plugins) خارج از کنترل Vite است و این ممکن است بر تجربه‌ی توسعه‌دهنده تأثیر بگذارد. در اینجا چند نکته وجود دارد که می‌توانید هنگام استفاده از پلاگین‌های اضافی Vite به آن‌ها توجه کنید:

1. وابستگی‌های بزرگ که فقط در موارد خاص استفاده می‌شوند، باید به صورتdynamic ایمپورت شوند تا زمان راه‌اندازی Node.js کاهش یابد. مثال‌هایی از بازنویسی کد (refactors): [vite-plugin-react#212](https://github.com/vitejs/vite-plugin-react/pull/212) و [vite-plugin-pwa#224](https://github.com/vite-pwa/vite-plugin-pwa/pull/244).

2. هوک‌های `buildStart`، `config` و `configResolved` نباید عملیات‌های طولانی و گسترده اجرا کنند. این هوک‌ها در زمان راه‌اندازی dev server منتظر می‌مانند، که این موضوع دسترسی به سایت در مرورگر را به تأخیر می‌اندازد.

3. هوک‌های `resolveId`، `load` و `transform` ممکن است باعث شوند برخی فایل‌ها کندتر از بقیه بارگذاری شوند. اگرچه گاهی اوقات این موضوع اجتناب‌ناپذیر است، اما همچنان ارزش دارد که بخش‌های ممکن برای بهینه‌سازی بررسی شوند. به عنوان مثال، بررسی اینکه آیا `code` شامل یک کلمه‌کلیدی خاص است یا `id` با یک پسوند خاص مطابقت دارد، قبل از انجام تبدیل کامل (full transformation).

   هرچه تبدیل یک فایل (transform) زمان بیشتری طول بکشد، آبشاری از درخواست‌ها (request waterfall) هنگام بارگذاری سایت در مرورگر قابل‌توجه‌تر خواهد بود.

   شما می‌توانید مدت زمان تبدیل یک فایل (transform) را با استفاده از دستور `vite --debug plugin-transform` یا [vite-plugin-inspect](https://github.com/antfu/vite-plugin-inspect) بررسی کنید. توجه داشته باشید که از آنجایی که عملیات ناهمزمان (asynchronous operations) تمایل به ارائه زمان‌بندی‌های نادرست دارند، باید اعداد را به عنوان یک تخمین تقریبی در نظر بگیرید، اما همچنان عملیات‌های پرهزینه‌تر را نشان می‌دهد.

::: tip Profiling
شما می‌توانید دستور `vite --profile` را اجرا کنید، از سایت بازدید کنید و در ترمینال خود `p + enter` را فشار دهید تا یک فایل `‎.cpuprofile` ثبت شود. سپس می‌توانید از ابزاری مانند [speedscope](https://www.speedscope.app) برای بررسی پروفایل و شناسایی bottlenecks استفاده کنید. همچنین می‌توانید [پروفایل ها را به اشتراک بگذارید](https://chat.vite.dev) و به تیم Vite کمک کنید تا مسائل مربوط به عملکرد (performance issues) را شناسایی کنند.
:::

## کاهش عملیات حل و فصل (resolve)

حل و فصل مسیرهای ایمپورت می‌تواند یک عملیات پرهزینه باشد، به‌ویژه زمانی که اغلب به بدترین حالت خود برخورد می‌کند. به عنوان مثال، Vite از "حدس زدن" مسیرهای ایمپورت با استفاده از گزینه‌ی [`resolve.extensions`](/config/shared-options.md#resolve-extensions) پشتیبانی می‌کند که به طور پیش‌فرض برابر با `['‎.mjs', '‎.js', '‎.mts', '‎.ts', '‎.jsx', '‎.tsx', '‎.json'] `است.

وقتی که سعی می‌کنید `‎./Component.jsx`را با `import './Component'` ایمپورت کنید، Vite مراحل زیر را برای حل و فصل آن اجرا می‌کند:

1. بررسی کند که آیا `‎./Component` وجود دارد؟ خیر.
2. بررسی کند که آیا `‎./Component.mjs` وجود دارد؟ خیر.
3. بررسی کند که آیا `‎./Component.js` وجود دارد؟ خیر.
4. بررسی کند که آیا `‎./Component.mts` وجود دارد؟ خیر.
5. بررسی کند که آیا `‎./Component.ts` وجود دارد؟ خیر.
6. بررسی کند که آیا `‎./Component.jsx` وجود دارد؟ بله!

همان‌طور که مشاهده می‌شود، برای حل و فصل یک مسیر ایمپورت، در مجموع ۶ بررسی فایل سیستم لازم است. هرچه تعداد ایمپورت‌های ضمنی (implicit imports) بیشتر باشد، زمان بیشتری برای حل و فصل مسیرها صرف خواهد شد.

بنابراین، معمولاً بهتر است که مسیرهای ایمپورت را به‌صورت صریح مشخص کنید، مانند عبارت `import './Component.jsx'`. همچنین می‌توانید لیست `resolve.extensions` را محدود کنید تا تعداد بررسی‌های فایل سیستم کاهش یابد، اما باید مطمئن شوید که این تغییر برای فایل‌های موجود در `node_modules` نیز به درستی کار می‌کند.

اگر یک نویسنده‌ی پلاگین هستید، اطمینان حاصل کنید که فقط در مواقع ضروری [`this.resolve`](https://rollupjs.org/plugin-development/#this-resolve) را فراخوانی کنید تا تعداد بررسی‌های ذکرشده در بالا کاهش یابد.

::: tip TypeScript
اگر از TypeScript استفاده می‌کنید، مقدار `"moduleResolution": "bundler"` و `‎"allowImportingTsExtensions": true` را در بخش `compilerOptions` فایل `tsconfig.json` فعال کنید تا بتوانید مستقیماً از پسوندهای `‎.ts` و `‎.tsx` در کد خود استفاده کنید.
:::

## از استفاده از فایل‌های Barrel خودداری کنید

فایل‌های Barrel فایل‌هایی هستند که APIهای سایر فایل‌های موجود در همان دایرکتوری را re-export می‌کنند. به عنوان مثال:

```js [src/utils/index.js]
export * from './color.js'
export * from './dom.js'
export * from './slash.js'
```

وقتی که تنها یک API خاص را ایمپورت می‌کنید، مانند `import { slash } from './utils'`، تمامی فایل‌های موجود در آن فایل Barrel باید واکشی (fetched) و تبدیل (transformed) شوند، زیرا ممکن است API `slash` را در خود داشته باشند و همچنین ممکن است دارای side-effects باشند که در زمان بارگذاری اولیه اجرا می‌شوند. این بدین معناست که فایل‌های بیشتری نسبت به آنچه که نیاز است، در هنگام بارگذاری صفحه‌ی اولیه بارگذاری می‌شوند و این باعث کندتر شدن زمان بارگذاری صفحه می‌شود.

در صورت امکان باید از فایل‌های Barrel خودداری کرده و APIهای فردی را به‌طور مستقیم ایمپورت کنید، مانند `import { slash } from './utils/slash.js'‎`. برای اطلاعات بیشتر، می‌توانید [issue #8237](https://github.com/vitejs/vite/issues/8237) را مطالعه کنید.

## فایل‌های پر استفاده را پیش‌بارگذاری کنید

سرور توسعه‌ی Vite فقط فایل‌هایی را تبدیل (transform) می‌کند که توسط مرورگر درخواست شده‌اند. این امکان باعث می‌شود تا سرور به سرعت راه‌اندازی شود و تنها تبدیل (transform)ها را روی فایل‌های استفاده‌شده اعمال کند. همچنین می‌تواند فایل‌هایی را پیش‌تبدیل (pre-transform) کند اگر پیش‌بینی کند که برخی فایل‌ها به زودی درخواست خواهند شد. با این حال، آبشاری از درخواست‌ها (request waterfalls) ممکن است اتفاق بیفتد اگر برخی فایل‌ها زمان بیشتری برای تبدیل (transform) نسبت به بقیه نیاز داشته باشند.

با توجه به یک گراف ایمپورت که در فایل سمت چپ، فایل سمت راست را ایمپورت می‌کند:

```
main.js -> BigComponent.vue -> big-utils.js -> large-data.json
```

رابطه‌ی ایمپورت (import relationship) فقط پس از تبدیل فایل قابل تشخیص است. اگر `BigComponent.vue` زمان‌بر باشد، `big-utils.js` باید منتظر نوبت خود بماند و به همین ترتیب ادامه می‌یابد. این موضوع حتی با وجود قابلیت پیش‌تبدیل (pre-transformation) داخلی، باعث ایجاد یک آبشار درونی (internal waterfall) می‌شود.

Vite به شما امکان می‌دهد فایل‌هایی را که می‌دانید به طور مکرر استفاده می‌شوند، مانند `big-utils.js`، با استفاده از گزینه [`server.warmup`](/config/server-options.md#server-warmup) از قبل بارگذاری کنید. به این ترتیب، `big-utils.js` آماده و در حافظه پنهان (کش) ذخیره می‌شود تا بلافاصله در هنگام درخواست، ارائه شود.

می‌توانید فایل‌هایی که به طور مکرر استفاده می‌شوند را با اجرای دستور `vite --debug transform` پیدا کرده و لاگ‌ها را بررسی کنید.

```bash
vite:transform 28.72ms /@vite/client +1ms
vite:transform 62.95ms /src/components/BigComponent.vue +1ms
vite:transform 102.54ms /src/utils/big-utils.js +1ms
```

```js [vite.config.js]
export default defineConfig({
  server: {
    warmup: {
      clientFiles: [
        './src/components/BigComponent.vue',
        './src/utils/big-utils.js'
      ]
    }
  }
})
```

توجه داشته باشید که فقط باید فایل‌هایی را از قبل بارگذاری کنید که به طور مکرر استفاده می‌شوند تا سرور توسعه Vite در هنگام راه‌اندازی بیش‌ازحد بارگیری نشود. برای اطلاعات بیشتر، گزینه [`server.warmup`](/config/server-options.md#server-warmup) را بررسی کنید.

استفاده از [`‎--open` یا `server.open`](/config/server-options.html#server-open) نیز باعث بهبود عملکرد می‌شود، زیرا Vite به‌طور خودکار entry point برنامه شما یا URL ارائه‌شده برای باز کردن را از قبل بارگذاری می‌کند.

## از ابزارهای ساده‌تر یا بومی استفاده کنید.

برای حفظ سرعت Vite در یک پایگاه کد در حال رشد، باید حجم کاری فایل‌های منبع (مانند JS/TS/CSS) را کاهش دهید.

نمونه‌هایی از کاهش کارها:

* در صورت امکان از CSS به جای Sass/Less/Stylus استفاده کنید (قابلیت‌هایی مانند تودرتو بودن (nesting) می‌تواند توسط PostCSS مدیریت شود).
* SVGها را به کامپوننت‌های فریمورک‌های UI (مثل React، Vue و غیره) transform نکنید. در عوض، آن‌ها را به‌صورت رشته یا URL ایمپورت کنید.
* هنگام استفاده از `‎@vitejs/plugin-react`، از پیکربندی گزینه‌های Babel خودداری کنید تا در طول build از transform شدن صرف‌نظر شود (تنها esbuild استفاده خواهد شد).

نمونه‌هایی از استفاده از ابزارهای بومی:

استفاده از ابزارهای بومی اغلب باعث افزایش حجم نصب می‌شود و به همین دلیل به‌طور پیش‌فرض هنگام شروع یک پروژه جدید با Vite فعال نیست. اما ممکن است برای برنامه‌های بزرگتر، این هزینه ارزش داشته باشد.

* از [Rolldown به‌جای Rollup و esbuild](./rolldown) استفاده کنید تا بیلد سریع‌تر باشد و بین توسعه و بیلد تجربه‌ای هماهنگ‌تر داشته باشید.
* پشتیبانی آزمایشی از [LightningCSS](https://github.com/vitejs/vite/discussions/13835) را امتحان کنید.
* به‌جای `‎@vitejs/plugin-react` از [`‎@vitejs/plugin-react-swc`](https://github.com/vitejs/vite-plugin-react-swc) استفاده کنید.

---

---
url: /guide/troubleshooting.md
---
# عیب‌یابی

برای اطلاعات بیشتر می‌توانید به [راهنمای عیب‌یابی Rollup](https://rollupjs.org/troubleshooting/) نیز مراجعه کنید.

اگر پیشنهادات ارائه‌شده در این صفحه کار نمی‌کنند، لطفاً سؤالات خود را در [GitHub Discussions](https://github.com/vitejs/vite/discussions) یا در کانال ‎`#help` در [Vite Land Discord](https://chat.vite.dev) ارسال کنید.

## CLI

### `Error: Cannot find module 'C:\foo\bar&baz\vite\bin\vite.js'‎`

مسیر پوشه پروژه شما ممکن است شامل `&` باشد، که با `npm` در ویندوز کار نمی‌کند ([npm/cmd-shim#45](https://github.com/npm/cmd-shim/issues/45)).

شما نیاز خواهید داشت به:

* تغییر به یک پکیج منیجر دیگر (مانند `pnpm`, `yarn`)
* حذف `&` از مسیر پروژه شما

## پیکربندی

### این پکیج ESM Only است

هنگام ایمپورت کردن یک پکیج ESM Only با `require`، خطای زیر رخ می‌دهد.

در Node.js نسخه‌های 22 و پایین‌تر، به‌طور پیش‌فرض فایل‌های ESM نمی‌توانند با استفاده از [`require`](https://nodejs.org/docs/latest-v22.x/api/esm.html#require) بارگذاری شوند.

اگرچه ممکن است با استفاده از گزینه [`‎--experimental-require-module`](https://nodejs.org/docs/latest-v22.x/api/modules.html#loading-ecmascript-modules-using-require)، یا در نسخه‌های بالای 22 در Node.js یا در رانتایم‌های دیگر این کار امکان‌پذیر باشد، اما همچنان توصیه می‌کنیم که پیکربندی خود را به ESM تبدیل کنید به یکی از روش‌های زیر:

* اضافه‌کردن `"type": "module"` به `package.json`
* تغییر نام `vite.config.js`/`vite.config.ts` به `vite.config.mjs`/`vite.config.mts`

## سرور توسعه

### Requests are stalled forever

اگر از لینوکس استفاده می‌کنید، ممکن است محدودیت‌های توصیف‌گر فایل (file descriptor) و محدودیت‌های inotify باعث این مشکل شوند. ازآنجاکه Vite بیشتر فایل‌ها را باندل نمی‌کند، مرورگرها ممکن است درخواست‌های زیادی ارسال کنند که نیاز به توصیف‌گر فایل زیادی دارند، و این باعث افزایش محدودیت می‌شود.

برای حل این مشکل:

* افزایش محدودیت دیسکریپتر فایل با `ulimit`

  ```shell
  # بررسی محدودیت فعلی
  $ ulimit -Sn
  # تغییر محدودیت (موقتی)
  $ ulimit -Sn 10000 # ممکن است نیاز به تغییر محدودیت سخت نیز داشته باشید
  # راه‌اندازی مجدد مرورگر خود
  ```

* افزایش محدودیت‌های مرتبط با inotify با `sysctl`

  ```shell
  # بررسی محدودیت‌های فعلی
  $ sysctl fs.inotify
  # تغییر محدودیت‌ها (موقتی)
  $ sudo sysctl fs.inotify.max_queued_events=16384
  $ sudo sysctl fs.inotify.max_user_instances=8192
  $ sudo sysctl fs.inotify.max_user_watches=524288
  ```

اگر مراحل بالا کار نکرد، می‌توانید `DefaultLimitNOFILE=65536` را به‌عنوان یک پیکربندی غیرکامنت به فایل‌های زیر اضافه کنید:

* ‎/etc/systemd/system.conf
* ‎/etc/systemd/user.conf

برای لینوکس Ubuntu، ممکن است نیاز به اضافه‌کردن خط `‎* - nofile 65536` به فایل `‎/etc/security/limits.conf` به‌جای به‌روزرسانی فایل‌های پیکربندی systemd داشته باشید.

توجه داشته باشید که این تنظیمات پایدار هستند اما **نیاز به راه‌اندازی مجدد دارند**.

به‌طور جایگزین، اگر سرور داخل یک devcontainer در VS Code در حال اجرا است، ممکن است به‌نظر برسد که درخواست‌ها متوقف شده‌اند.
برای رفع این مشکل، به بخش [Dev Containers / VS Code Port Forwarding](#dev-containers--انتقال-پورت-vs-code) مراجعه کنید.

### Network requests stop loading

هنگام استفاده از یک گواهی SSL خودامضا، Chrome تمام دستورات کش را نادیده می‌گیرد و محتوا را دوباره بارگذاری می‌کند. Vite به این دستورات کش متکی است.

برای حل این مشکل از یک گواهی SSL معتبر استفاده کنید.

یا میتوانید به این لینک ها مراجعه کنید: [مشکلات کش](https://helpx.adobe.com/mt/experience-manager/kb/cache-problems-on-chrome-with-SSL-certificate-errors.html)، [مشکل Chrome](https://bugs.chromium.org/p/chromium/issues/detail?id=110649#c8)

#### macOS

می‌توانید یک گواهی معتبر را از طریق CLI با این فرمان نصب کنید:

```
security add-trusted-cert -d -r trustRoot -k ~/Library/Keychains/login.keychain-db your-cert.cer
```

یا با واردکردن آن به اپلیکیشن Keychain Access و به‌روزرسانی اعتماد گواهی خود به "Always Trust"

### 431 Request Header Fields Too Large

هنگامی که سرور / سرور WebSocket یک هدر HTTP بزرگ دریافت می‌کند، درخواست رد شده و هشدار زیر نمایش داده می‌شود.

این به این دلیل است که Node.js اندازه هدر درخواست را برای کاهش [CVE-2018-12121](https://www.cve.org/CVERecord?id=CVE-2018-12121) محدود می‌کند.

برای اجتناب از این مشکل، سعی کنید اندازه هدر درخواست خود را کاهش دهید. به عنوان مثال، اگر کوکی طولانی است، آن را حذف کنید. یا می‌توانید از [`‎--max-http-header-size`](https://nodejs.org/api/cli.html#--max-http-header-sizesize) برای تغییر حداکثر اندازه هدر استفاده کنید.

### Dev Containers / انتقال پورت VS Code

اگر از Dev Container یا قابلیت انتقال پورت در VS Code استفاده می‌کنید، ممکن است نیاز به تنظیم گزینه [`server.host`](/config/server-options.md#server-host) به `127.0.0.1` در تنظیمات داشته باشید تا کار کند.

این به این دلیل است که [قابلیت انتقال پورت در VS Code از IPv6 پشتیبانی نمی‌کند](https://github.com/microsoft/vscode-remote-release/issues/7029).

برای جزئیات بیشتر، به [‎#16522](https://github.com/vitejs/vite/issues/16522) مراجعه کنید.

## HMR

### Vite تغییر فایل را تشخیص می‌دهد اما HMR کار نمی‌کند

ممکن است فایلی را با یک حالت متفاوت ایمپورت کنید. به عنوان مثال، `src/foo.js` وجود دارد و `src/bar.js` شامل:

```js
import './Foo.js' // باشد './foo.js' باید
```

لینک ارور: [‎#964](https://github.com/vitejs/vite/issues/964)

### Vite تغییر فایل را تشخیص نمی‌دهد

اگر از Vite در محیط WSL2 استفاده می‌کنید، در برخی شرایط Vite قادر به نظارت بر تغییرات فایل‌ها نخواهد بود. برای اطلاعات بیشتر به گزینه [`server.watch`](/config/server-options.md#server-watch) مراجعه کنید.

### به‌جای HMR، بارگذاری کامل انجام می‌شود

اگر HMR توسط Vite یا پلاگینی مدیریت نشود، بارگذاری کامل انجام خواهد شد زیرا این تنها راه برای تازه‌سازی برنامه است.

اگر HMR مدیریت شود، اما در داخل یک وابستگی حلقه‌ای قرار داشته باشد، یک بارگذاری کامل نیز برای بازیابی ترتیب اجرای برنامه رخ خواهد داد. برای حل این مشکل، سعی کنید حلقه وابستگی را بشکنید. اگر تغییر فایلی باعث این مشکل شده است، می‌توانید دستور `vite --debug hmr` را اجرا کنید تا مسیر وابستگی حلقه‌ای ثبت شود.

## بیلد

### فایل بیلد شده به دلیل خطای CORS کار نمی‌کند

اگر فایل HTML خروجی با پروتکل `file` باز شود، اسکریپت‌ها با خطای زیر مواجه شده و اجرا نخواهند شد.

برای اطلاعات بیشتر در مورد اینکه چرا این اتفاق می‌افتد، به [Reason: CORS request not HTTP - HTTP | MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS/Errors/CORSRequestNotHttp) مراجعه کنید.

شما باید به فایل با پروتکل `http` دسترسی پیدا کنید. آسان‌ترین راه برای انجام این کار اجرای `npx vite preview` است.

## وابستگی‌های بهینه‌سازی‌شده

### لینک شدن پکیج های قدیمی به پکیج های لوکال

کلید هش استفاده‌شده برای باطل کردن وابستگی‌های بهینه‌شده بستگی به محتوای package lock، وصله‌های اعمال‌شده به وابستگی‌ها و گزینه‌های موجود در فایل پیکربندی Vite که بر روی باندل ماژول‌های نود تأثیر می‌گذارد، دارد. این به این معنی است که Vite وقتی یک وابستگی با استفاده از ویژگی‌ای مانند [overrides npm](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#overrides) بازنویسی می‌شود، آن را شناسایی خواهد کرد و وابستگی‌های شما را در شروع بعدی سرور دوباره باندل می‌کند. Vite وقتی که از ویژگی‌ای مانند [npm link](https://docs.npmjs.com/cli/v9/commands/npm-link) استفاده می‌کنید، وابستگی‌ها را باطل نمی‌کند. در صورت لینک یا unlink یک وابستگی، باید بهینه‌سازی مجدد را در شروع بعدی سرور با استفاده از `vite --force` انجام دهید. ما توصیه می‌کنیم از overrides استفاده کنید که اکنون توسط همه پکیج منیجرها پشتیبانی می‌شود (همچنین به [pnpm overrides](https://pnpm.io/package_json#pnpmoverrides) و [yarn resolutions](https://yarnpkg.com/configuration/manifest/#resolutions) مراجعه کنید).

## گلوگاه‌های عملکرد

اگر به‌دلیل گلوگاه‌های عملکرد اپلیکیشن با زمان بارگذاری کند مواجه شدید، می‌توانید با سرور توسعه Vite یا هنگام ساخت اپلیکیشن، بازرسی کننده Node.js را فعال کنید تا پروفایل CPU ایجاد کنید:

::: code-group

```bash [سرور توسعه]
vite --profile --open
```

```bash [ساخت]
vite build --profile
```

:::

::: tip سرور توسعه Vite
پس از باز شدن اپلیکیشن در مرورگر، فقط صبر کنید تا بارگذاری کامل شود و سپس به ترمینال برگردید و کلید `p` را فشار دهید (بازرسی کننده Node.js را متوقف می‌کند) سپس کلید `q` را فشار دهید تا سرور توسعه متوقف شود.
:::

بازرسی کننده Node.js فایل `vite-profile-0.cpuprofile` را در پوشه اصلی ایجاد می‌کند، به <https://www.speedscope.app> بروید و پروفایل CPU را با استفاده از دکمه `BROWSE` بارگذاری کنید تا نتیجه را بررسی کنید.

می‌توانید [vite-plugin-inspect](https://github.com/antfu/vite-plugin-inspect) را نصب کنید که به شما اجازه می‌دهد وضعیت میانی پلاگین‌های Vite را بازرسی کنید و همچنین به شما کمک می‌کند تا مشخص کنید کدام پلاگین‌ها یا میان‌افزارها در اپلیکیشن‌های شما گلوگاه هستند. این پلاگین می‌تواند در حالت‌های توسعه و ساخت استفاده شود. فایل readme را برای جزئیات بیشتر بررسی کنید.

## سایر موارد

### ماژول خارجی برای سازگاری با مرورگر

هنگامی که از یک ماژول Node.js در مرورگر استفاده می‌کنید، Vite هشدار زیر را خروجی می‌دهد.

این به این دلیل است که Vite به‌صورت خودکار ماژول‌های Node.js را پلی‌فیل نمی‌کند.

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

### خطای سینتکس / Type Error رخ می‌دهد

Vite نمی‌تواند کدی را که فقط در non-strict mode اجرا می‌شود (حالت غیر-سخت‌گیر) را مدیریت کند و از آن پشتیبانی نمی‌کند. این به این دلیل است که Vite از ESM استفاده می‌کند و همیشه [Strict Mode](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Strict_mode) درون ESM فعال است.

برای مثال، ممکن است این خطاها را ببینید.

اگر این کدها درون وابستگی‌ها استفاده می‌شوند، می‌توانید از [`patch-package`](https://github.com/ds300/patch-package) (یا [`yarn patch`](https://yarnpkg.com/cli/patch) یا [`pnpm patch`](https://pnpm.io/cli/patch)) برای یک راه‌فرار استفاده کنید.

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

برخی از افزونه‌های مرورگر (مانند مسدودکننده‌های تبلیغات) ممکن است از ارسال درخواست‌ها از کلاینت Vite به سرور توسعه Vite جلوگیری کنند. در این صورت، ممکن است صفحه سفید بدون خطاهای ثبت‌شده مشاهده کنید. اگر با این مشکل روبه‌رو هستید، امتحان کنید که افزونه‌ها را غیرفعال کنید.

### لینک‌های cross drive در ویندوز

اگر در پروژه شما لینک‌های cross drive وجود داشته باشد، Vite ممکن است کار نکند.

یک مثال از لینک‌های cross drive:

* یک درایو مجازی که با دستور `subst` به یک پوشه لینک شده است
* یک symlink/junction به یک درایو متفاوت با دستور `mklink` (مثال: کش global Yarn)

لینک ارور: [‎#10802](https://github.com/vitejs/vite/issues/10802)

---

---
url: /guide/philosophy.md
---
# فلسفه‌ی پروژه Vite

## هسته‌ی کم‌حجم و قابل توسعه

Vite قصد ندارد تمام سناریوهای ممکن را برای همه‌ی کاربران پوشش دهد. هدف Vite این است که الگوهای رایج برای ساخت اپلیکیشن‌های وب را به‌صورت پیش‌فرض ارائه کند، اما [هسته‌ی Vite](https://github.com/vitejs/vite) باید کم‌حجم باقی بماند و API کوچکی داشته باشد تا نگهداری آن در طولانی‌مدت ساده باشد. این هدف به لطف [سیستم پلاگین مبتنی بر Rollup در Vite](./api-plugin.md) محقق می‌شود. قابلیت‌هایی که می‌توانند به‌عنوان پلاگین‌های خارجی پیاده‌سازی شوند، معمولاً به هسته‌ی Vite اضافه نخواهند شد. برای مثال، [vite-plugin-pwa](https://vite-pwa-org.netlify.app/) نمونه‌ای عالی از قابلیت‌هایی است که خارج از هسته‌ی Vite توسعه یافته‌اند. همچنین، مجموعه‌ای از [پلاگین‌های خوب و پشتیبانی‌شده](https://github.com/vitejs/awesome-vite#plugins) برای پوشش نیازهای کاربران وجود دارد. Vite همکاری نزدیکی با پروژه Rollup دارد تا اطمینان حاصل شود که پلاگین‌ها تا حد ممکن هم در پروژه‌های Rollup و هم در Vite قابل استفاده باشند و در صورت نیاز، تغییرات موردنیاز به API پلاگین‌های Rollup اضافه شوند.

## پیشبرد توسعه‌ی وب مدرن

Vite ویژگی‌هایی را ارائه می‌کند که توسعه‌ی کد مدرن را تشویق می‌کند. برای مثال:

* کد منبع باید فقط در قالب ESM نوشته شود، و وابستگی‌های غیر-ESM باید ابتدا [به‌صورت ESM پیش‌باندل](./dep-pre-bundling) شوند تا کار کنند.
* پیشنهاد می‌شود که Web Workers با استفاده از [سینتکس `new Worker`](./features#web-workers) نوشته شوند تا از استانداردهای مدرن پیروی کنند.
* ماژول‌های Node.js را نمی‌توان در مرورگر استفاده کرد.

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

## رویکرد عمل‌گرایانه نسبت به عملکرد

Vite از [ابتدای توسعه‌ی خود](./why.md) بر عملکرد متمرکز بوده است. معماری سرور توسعه‌ی آن به HMR اجازه می‌دهد که حتی با بزرگ‌تر شدن پروژه‌ها، سریع بماند. Vite از ابزارهای بومی مانند [esbuild](https://esbuild.github.io/) و [SWC](https://github.com/vitejs/vite-plugin-react-swc) برای انجام وظایف سنگین استفاده می‌کند، اما بقیه‌ی کد را در JS نگه می‌دارد تا تعادل بین سرعت و انعطاف‌پذیری حفظ شود. در صورت نیاز، پلاگین‌های فریمورک می‌توانند از [Babel](https://babeljs.io/) برای کامپایل کد کاربر استفاده کنند. همچنین، در زمان ساخت، Vite از [Rollup](https://rollupjs.org/) بهره می‌برد، جایی که اندازه‌ی باندل و دسترسی به اکوسیستم گسترده‌ی پلاگین‌ها اهمیت بیشتری نسبت به سرعت خام دارد. Vite به‌صورت مداوم تکامل می‌یابد و در صورت ظهور کتابخانه‌های جدید برای بهبود تجربه‌ی توسعه‌دهنده (DX)، آن‌ها را در معماری داخلی خود ادغام خواهد کرد، در حالی که API آن پایدار باقی می‌ماند.

## ایجاد فریمورک‌ها بر پایه‌ی Vite

هرچند Vite به‌صورت مستقیم توسط کاربران قابل استفاده است، اما قدرت اصلی آن در ایجاد فریمورک‌ها نمایان می‌شود. هسته‌ی Vite وابسته به فریمورک خاصی نیست، اما پلاگین‌های بهینه‌شده‌ای برای هر فریمورک UI وجود دارد. [API جاوااسکریپت Vite](./api-javascript.md) به توسعه‌دهندگان فریمورک‌ها این امکان را می‌دهد که قابلیت‌های Vite را برای ایجاد تجربه‌های اختصاصی برای کاربران خود به کار ببرند. Vite همچنین از [SSRs](./ssr.md) پشتیبانی می‌کند که معمولاً در ابزارهای سطح بالاتر وجود دارند، اما برای ساخت فریمورک‌های وب مدرن ضروری هستند. پلاگین‌های Vite نیز امکان اشتراک‌گذاری بین فریمورک‌های مختلف را فراهم می‌کنند. علاوه بر این، Vite گزینه‌ی مناسبی برای ادغام با [فریمورک‌های بک‌اند](./backend-integration.md) مانند [Ruby](https://vite-ruby.netlify.app/) و [Laravel](https://laravel.com/docs/10.x/vite) است.

## یک اکوسیستم فعال

توسعه‌ی Vite نتیجه‌ی همکاری بین توسعه‌دهندگان فریمورک‌ها، نگه‌داران پلاگین‌ها، کاربران و تیم اصلی Vite است. ما مشارکت فعال در توسعه‌ی هسته‌ی Vite را تشویق می‌کنیم، به‌ویژه زمانی که پروژه‌ای از آن استفاده می‌کند. تیم Vite با پروژه‌های اصلی در اکوسیستم همکاری می‌کند تا از بروز مشکلات در هر نسخه‌ی جدید جلوگیری کند. ابزارهایی مانند [vite-ecosystem-ci](https://github.com/vitejs/vite-ecosystem-ci) به ما کمک می‌کنند تا تست‌های CI را برای پروژه‌های مهم که از Vite استفاده می‌کنند روی PRهای منتخب اجرا کنیم و بررسی کنیم که اکوسیستم چگونه به نسخه‌های جدید واکنش نشان خواهد داد. هدف ما این است که مشکلات قبل از رسیدن به کاربران حل شوند و پروژه‌ها بتوانند بلافاصله پس از انتشار نسخه‌های جدید، به‌روز شوند. اگر شما هم با Vite کار می‌کنید، از شما دعوت می‌کنیم که به [Discord رسمی Vite](https://chat.vite.dev) بپیوندید و در توسعه‌ی این پروژه مشارکت داشته باشید.

---

---
url: /config/dep-optimization-options.md
---
# گزینه‌های بهینه‌سازی وابستگی‌ها

* **مرتبط:** [پیش‌باندل کردن وابستگی‌ها](/guide/dep-pre-bundling)

مگر اینکه ذکر شده باشه، گزینه‌های این بخش فقط به بهینه‌ساز وابستگی‌ها اعمال می‌شن که فقط در حالت توسعه استفاده می‌شه.

## optimizeDeps.entries

* **تایپ:** `[]string | string`

به‌طور پیش‌فرض، Vite همه فایل‌های `‎.html` شما رو بررسی می‌کنه تا وابستگی‌هایی که باید پیش‌باندل بشن رو پیدا کنه (با نادیده گرفتن `node_modules` ، `build.outDir` ، `__tests__‎` و `coverage`). اگه `build.rollupOptions.input` مشخص شده باشه، Vite به جای اون، اون نقاط ورود رو بررسی می‌کنه.

اگه هیچ‌کدوم از این‌ها نیاز شما رو برآورده نکنه، می‌تونید با این گزینه نقاط ورود سفارشی رو مشخص کنید - مقدار باید یه الگوی [`tinyglobby`](https://github.com/SuperchupuDev/tinyglobby) یا آرایه‌ای از الگوها باشه که نسبت به ریشه پروژه Vite هستن. این کار حدس نقاط ورود پیش‌فرض رو بازنویسی می‌کنه. وقتی `optimizeDeps.entries` به‌صراحت تعریف بشه، فقط پوشه‌های `node_modules` و `build.outDir` به‌طور پیش‌فرض نادیده گرفته می‌شن. اگه نیاز باشه پوشه‌های دیگه هم نادیده گرفته بشن، می‌تونید از الگوی نادیده‌گرفتن با علامت `!` در ابتدای لیست نقاط ورود استفاده کنید. توجه داشته باشید: اگر الگویی به‌طور صریح شامل رشته `node_modules` باشد، آن پوشه نادیده گرفته نخواهد شد.

## optimizeDeps.exclude

* **تایپ:** `[]string`

وابستگی‌هایی که باید از پیش‌باندل کردن مستثنا بشن.

::: warning CommonJS
وابستگی‌های CommonJS نباید از بهینه‌سازی مستثنا بشن. اگه یه وابستگی ESM از بهینه‌سازی مستثنا بشه، اما یه وابستگی CommonJS تودرتو داشته باشه، اون وابستگی CommonJS باید به `optimizeDeps.include` اضافه بشه. مثال:

```js twoslash
import { defineConfig } from 'vite'
// ---cut---
export default defineConfig({
  optimizeDeps: {
    include: ['esm-dep > cjs-dep'],
  },
})
```

:::

## optimizeDeps.include

* **تایپ:** `[]string`

به‌طور پیش‌فرض، پکیج‌های لینک‌شده‌ای که داخل `node_modules` نیستن پیش‌باندل نمی‌شن. از این گزینه استفاده کنید تا یه پکیج لینک‌شده رو مجبور به پیش‌باندل شدن کنید.

**آزمایشی:** اگه از کتابخونه‌ای با ایمپورت‌های عمیق زیاد استفاده می‌کنید، می‌تونید یه الگوی گلوب انتهایی هم مشخص کنید تا همه ایمپورت‌های عمیق رو یه‌جا پیش‌باندل کنه. این کار از پیش‌باندل مداوم هر بار که یه ایمپورت عمیق جدید استفاده می‌شه جلوگیری می‌کنه. [بازخورد بدید](https://github.com/vitejs/vite/discussions/15833). مثلاً:

```js twoslash
import { defineConfig } from 'vite'
// ---cut---
export default defineConfig({
  optimizeDeps: {
    include: ['my-lib/components/**/*.vue'],
  },
})
```

## optimizeDeps.esbuildOptions

* **تایپ:** [`Omit`](https://www.typescriptlang.org/docs/handbook/utility-types.html#omittype-keys)`<`[`EsbuildBuildOptions`](https://esbuild.github.io/api/#general-options)`,
  | 'bundle'
  | 'entryPoints'
  | 'external'
  | 'write'
  | 'watch'
  | 'outdir'
  | 'outfile'
  | 'outbase'
  | 'outExtension'
  | 'metafile'>‎`

گزینه‌هایی که موقع اسکن و بهینه‌سازی وابستگی‌ها به esbuild منتقل می‌شن.

بعضی گزینه‌ها حذف شدن، چون تغییرشون با بهینه‌سازی وابستگی‌های Vite سازگار نیست.

* `external` هم حذف شده، به جاش از گزینه `optimizeDeps.exclude` در Vite استفاده کنید.
* `plugins` با پلاگین وابستگی Vite ادغام می‌شن.

## optimizeDeps.force

* **تایپ:** `boolean`

اگه روی `true` تنظیم بشه، پیش‌باندل کردن وابستگی‌ها رو اجباری می‌کنه و وابستگی‌های بهینه‌شده کش‌شده قبلی رو نادیده می‌گیره.

## optimizeDeps.noDiscovery

* **تایپ:** `boolean`
* **پیش‌فرض:** `false`

وقتی مقدار این گزینه روی `true` تنظیم شود، شناسایی خودکار وابستگی‌ها غیرفعال می‌شود و فقط وابستگی‌هایی که در `optimizeDeps.include` ذکر شده‌اند، بهینه‌سازی خواهند شد. وابستگی‌هایی که فقط به‌صورت CommonJS (CJS-only) هستند، باید حتماً در طول توسعه در `optimizeDeps.include` قرار داشته باشند.

## optimizeDeps.holdUntilCrawlEnd

* **آزمایشی:** [بازخورد بدید](https://github.com/vitejs/vite/discussions/15834)
* **تایپ:** `boolean`
* **پیش‌فرض:** `true`

وقتی فعال باشه، نتایج اولیه بهینه‌سازی وابستگی‌ها رو تا وقتی که همه ایمپورت‌های استاتیک موقع cold start بررسی بشن نگه می‌داره. این کار از نیاز به بارگذاری مجدد کل صفحه وقتی وابستگی‌های جدید پیدا می‌شن و تکه‌های مشترک جدیدی تولید می‌کنن جلوگیری می‌کنه. اگه همه وابستگی‌ها توسط اسکنر به علاوه اونایی که توی `include` صراحتاً تعریف شدن پیدا بشن، بهتره این گزینه رو غیرفعال کنید تا مرورگر درخواست‌های بیشتری رو به‌صورت موازی پردازش کنه.

## optimizeDeps.disabled

* **منسوخ‌شده**
* **آزمایشی:** [بازخورد بدید](https://github.com/vitejs/vite/discussions/13839)
* **تایپ:** `boolean | 'build' | 'dev'‎`
* **پیش‌فرض:** `'build'`

این گزینه منسوخ شده. از Vite 5.1، پیش‌باندل کردن وابستگی‌ها موقع ساخت حذف شده. تنظیم `optimizeDeps.disabled` روی `true` یا `'dev'` بهینه‌ساز رو غیرفعال می‌کنه، و تنظیمش روی `false` یا `'build'` بهینه‌ساز رو توی توسعه فعال نگه می‌داره.

برای غیرفعال کردن کامل بهینه‌ساز، از `optimizeDeps.noDiscovery: true` استفاده کنید تا کشف خودکار وابستگی‌ها رو غیرمجاز کنید و `optimizeDeps.include` رو تعریف‌نشده یا خالی بذارید.

::: warning هشدار
بهینه‌سازی وابستگی‌ها موقع ساخت یه ویژگی **آزمایشی** بود. پروژه‌هایی که این استراتژی رو امتحان کردن، `rollup/plugin-commonjs@` رو با استفاده از `build.commonjsOptions: { include: [] }` حذف کرده بودن. اگه این کار رو کردید، یه هشدار شما رو راهنمایی می‌کنه که دوباره فعالش کنید تا از پکیج‌های فقط CJS موقع باندل کردن پشتیبانی بشه.
:::

## optimizeDeps.needsInterop

* **آزمایشی**
* **تایپ:** `[]string`

وقتی این وابستگی‌ها ایمپورت می‌شن، ESM interop رو اجباری می‌کنه. Vite معمولاً می‌تونه درست تشخیص بده که کی یه وابستگی به interop نیاز داره، پس این گزینه عموماً لازم نیست. اما ترکیب‌های مختلف وابستگی‌ها ممکنه باعث بشه بعضی‌هاشون متفاوت پیش‌باندل بشن. اضافه کردن این پکیج‌ها به `needsInterop` می‌تونه شروع سرد رو با جلوگیری از بارگذاری مجدد کل صفحه سریع‌تر کنه. اگه این مورد برای یکی از وابستگی‌هاتون پیش بیاد، یه هشدار می‌گیرید که پیشنهاد می‌ده اسم پکیج رو به این آرایه توی پیکربندی‌تون اضافه کنید.

---

---
url: /config/build-options.md
---
# گزینه‌های بیلد

مگر اینکه ذکر شده باشه، گزینه‌های این بخش فقط موقع بیلد اعمال می‌شن.

## build.target

* **تایپ:** `[]string | string`
* **پیش‌فرض:** `'baseline-widely-available'`
* **مرتبط:** [سازگاری با مرورگر](/guide/build#browser-compatibility)

هدف سازگاری مرورگر برای باندل نهایی. مقدار پیش‌فرض یک مقدار خاص در Vite به نام `'baseline-widely-available'` است که مرورگرهایی را هدف می‌گیرد که در [Baseline – Widely Available](https://web-platform-dx.github.io/web-features/) در تاریخ ۱ مه ۲۰۲۵ گنجانده شده‌اند. به طور مشخص، این مقدار شامل مرورگرهای ‎`['chrome107', 'edge107', 'firefox104', 'safari16']`‎ است.

یه مقدار خاص دیگه `'esnext'` هست که فرض می‌کنه پشتیبانی از ایمپورت داینامیک بومی وجود داره و فقط حداقل ترنسپایل رو انجام می‌ده.

ترنسفورم با esbuild انجام می‌شه و مقدار باید یه [گزینه هدف esbuild](https://esbuild.github.io/api/#target) معتبر باشه. هدف‌های سفارشی می‌تونن یه نسخه ES (مثل `es2015`)، یه مرورگر با نسخه (مثل `chrome58`) یا آرایه‌ای از چند رشته هدف باشن.

اگه کد شامل ویژگی‌هایی باشه که esbuild نتونه به‌خوبی ترنسپایلشون کنه، بیلد خطا می‌ده. برای جزئیات بیشتر به [مستندات esbuild](https://esbuild.github.io/content-types/#javascript) نگاه کنین.

## build.modulePreload

* **تایپ:** `boolean | { polyfill?: boolean, resolveDependencies?: ResolveModulePreloadDependenciesFn }`
* **پیش‌فرض:** `{ polyfill: true }`

به‌صورت پیش‌فرض، یه [پلی‌فیل module preload](https://guybedford.com/es-module-preloading-integrity#modulepreload-polyfill) به‌صورت خودکار تزریق می‌شه. این پلی‌فیل توی ماژول پراکسی هر ورودی `index.html` تزریق می‌شه. اگه بیلد برای استفاده از یه ورودی سفارشی غیر HTML با `build.rollupOptions.input` تنظیم شده باشه، باید پلی‌فیل رو دستی تو ورودی سفارشی ایمپورت کنین:

```js
import 'vite/modulepreload-polyfill'
```

توجه: این پلی‌فیل تو [حالت کتابخانه](/guide/build#library-mode) اعمال نمی‌شه. اگه نیاز دارین مرورگرهایی رو پشتیبانی کنین که ایمپورت داینامیک بومی ندارن، بهتره ازش تو کتابخونتون استفاده نکنین.

با `{ polyfill: false }` می‌تونین پلی‌فیل رو غیرفعال کنین.

لیست چانک‌هایی که باید برای هر ایمپورت داینامیک پیش‌بارگذاری بشن توسط Vite محاسبه می‌شه. به‌صورت پیش‌فرض، یه مسیر مطلق شامل `base` برای بارگذاری این وابستگی‌ها استفاده می‌شه. اگه `base` نسبی باشه (`''` یا `'./‎'`)، از `import.meta.url` تو زمان اجرا استفاده می‌شه تا از مسیرهای مطلقی که به `base` نهایی وابسته‌ان جلوگیری بشه.

پشتیبانی آزمایشی برای کنترل دقیق‌تر لیست وابستگی‌ها و مسیرهاشون با تابع `resolveDependencies` وجود داره. [نظرتون رو بدین](https://github.com/vitejs/vite/discussions/13841). این تابع باید از نوع `ResolveModulePreloadDependenciesFn` باشه:

```ts
type ResolveModulePreloadDependenciesFn = (
  url: string,
  deps: string[],
  context: {
    hostId: string
    hostType: 'html' | 'js'
  },
) => string[]
```

تابع `resolveDependencies` برای هر ایمپورت داینامیک با لیست چانک‌هایی که بهش وابسته‌ان فراخوانی می‌شه و همین‌طور برای هر چانک ایمپورت‌شده تو فایل‌های HTML ورودی. می‌تونین یه آرایه وابستگی جدید برگردونین که فیلتر شده یا وابستگی‌های بیشتری تزریق شده و مسیرهاشون تغییر کرده باشه. مسیرهای `deps` نسبت به `build.outDir` هستن. مقدار برگشتی باید یه مسیر نسبی به `build.outDir` باشه.

```js twoslash
/** @type {import('vite').UserConfig} */
const config = {
  // prettier-ignore
  build: {
// ---cut-before---
modulePreload: {
  resolveDependencies: (filename, deps, { hostId, hostType }) => {
    return deps.filter(condition)
  },
},
// ---cut-after---
  },
}
```

مسیرهای وابستگی رفع‌شده رو می‌تونین با [`experimental.renderBuiltUrl`](../guide/build.md#advanced-base-options) بیشتر تغییر بدین.

## build.polyfillModulePreload

* **تایپ:** `boolean`
* **پیش‌فرض:** `true`
* **منسوخ‌شده:** به جاش از `build.modulePreload.polyfill` استفاده کنین

آیا یه [پلی‌فیل module preload](https://guybedford.com/es-module-preloading-integrity#modulepreload-polyfill) به‌صورت خودکار تزریق بشه یا نه.

## build.outDir

* **تایپ:** `string`
* **پیش‌فرض:** `dist`

دایرکتوری خروجی رو مشخص می‌کنه (نسبت به [ریشه پروژه](/guide/#index-html-و-ریشه-root-پروژه)).

## build.assetsDir

* **تایپ:** `string`
* **پیش‌فرض:** `assets`

دایرکتوری‌ای که asset های تولیدشده توش قرار می‌گیرن رو مشخص می‌کنه (نسبت به `build.outDir`). تو [حالت کتابخانه](/guide/build#library-mode) استفاده نمی‌شه.

## build.assetsInlineLimit

* **تایپ:** `number | ((filePath: string, content: Buffer) => boolean | undefined)`
* **پیش‌فرض:** `4096` (4 کیلوبایت)

asset های ایمپورت‌شده یا ارجاع‌شده که از این حد کوچیک‌تر باشن، به‌صورت URLهای base64 اینلاین می‌شن تا درخواست‌های HTTP اضافی کم بشه. با `0` می‌تونین اینلاین کردن رو کامل غیرفعال کنین.

اگه یه callback بفرستین، می‌تونین یه مقدار بولین برگردونین تا اینلاین بشه یا نه. اگه چیزی برنگردونین، منطق پیش‌فرض اعمال می‌شه.

فایل‌های placeholder Git LFS به‌صورت خودکار از اینلاین شدن مستثنی هستن چون محتوای فایلی که نمایندگی می‌کنن رو ندارن.

::: tip نکته
اگه `build.lib` رو مشخص کنین، `build.assetsInlineLimit` نادیده گرفته می‌شه و دارایی‌ها همیشه اینلاین می‌شن، بدون توجه به اندازه فایل یا placeholder بودن Git LFS.
:::

## build.cssCodeSplit

* **تایپ:** `boolean`
* **پیش‌فرض:** `true`

تقسیم‌بندی کد CSS رو فعال یا غیرفعال می‌کنه. وقتی فعال باشه، CSS ایمپورت‌شده تو چانک‌های JS ناهمگام به‌صورت چانک نگه داشته می‌شه و وقتی چانک بارگذاری می‌شه، همراهش فچ می‌شه.

اگه غیرفعال باشه، همه CSS پروژه تو یه فایل CSS واحد استخراج می‌شه.

::: tip نکته
اگه `build.lib` رو مشخص کنین، `build.cssCodeSplit` به‌صورت پیش‌فرض `false` می‌شه.
:::

## build.cssTarget

* **تایپ:** `[]string | string`
* **پیش‌فرض:** همون [`build.target`](#build-target)

این گزینه به کاربرها اجازه می‌ده هدف مرورگر متفاوتی برای مینیفای CSS نسبت به ترنسپایل JS تنظیم کنن.

فقط وقتی باید استفاده بشه که یه مرورگر غیرمعمول رو هدف گرفتین. یه مثالش Android WeChat WebView هست که بیشتر ویژگی‌های مدرن JS رو پشتیبانی می‌کنه
ولی از [نوتاسیون رنگ هگزادسیمال #RGBA در CSS](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#rgb_colors) نه.
تو این مورد، باید `build.cssTarget` رو به `chrome61` تنظیم کنین تا Vite رنگ‌های `rgba()‎` رو به نوتاسیون هگزادسیمال #RGBA تبدیل نکنه.

## build.cssMinify

* **تایپ:** `boolean | 'esbuild' | 'lightningcss'`
* **پیش‌فرض:** برای کلاینت همون [`build.minify`](#build-minify)، برای SSR `'esbuild'‎`

این گزینه به کاربرها اجازه می‌ده مینیفای CSS رو جدا از `build.minify` تنظیم کنن، تا بتونین مینیفای JS و CSS رو جداگانه پیکربندی کنین. Vite به‌صورت پیش‌فرض از `esbuild` برای مینیفای CSS استفاده می‌کنه. با تنظیمش به `'lightningcss'` می‌تونین از [Lightning CSS](https://lightningcss.dev/minification.html) استفاده کنین. اگه انتخابش کنین، با [`css.lightningcss`](./shared-options.md#css-lightningcss) قابل پیکربندی هست.

## build.sourcemap

* **تایپ:** `boolean | 'inline' | 'hidden'‎`
* **پیش‌فرض:** `false`

نقشه‌های منبع (sourcemap) رو برای تولید بسازین. اگه `true` باشه، یه فایل sourcemap جدا ساخته می‌شه. اگه `'inline'` باشه، sourcemap به‌عنوان یه data URI به فایل خروجی اضافه می‌شه. `'hidden'` مثل `true` کار می‌کنه ولی کامنت‌های sourcemap تو فایل‌های باندل‌شده حذف می‌شن.

## build.rollupOptions

* **تایپ:** [`RollupOptions`](https://rollupjs.org/configuration-options/)

باندل Rollup زیرساختی رو مستقیم سفارشی کنین. این همون گزینه‌هایی هست که می‌تونین از یه فایل کانفیگ Rollup اکسپورت کنین و با گزینه‌های داخلی Rollup توی Vite ادغام می‌شه. برای جزئیات بیشتر به [مستندات گزینه‌های Rollup](https://rollupjs.org/configuration-options/) نگاه کنین.

## build.commonjsOptions

* **تایپ:** [`RollupCommonJSOptions`](https://github.com/rollup/plugins/tree/master/packages/commonjs#options)

گزینه‌هایی که به [‎@rollup/plugin-commonjs](https://github.com/rollup/plugins/tree/master/packages/commonjs) ارسال می‌شن.

## build.dynamicImportVarsOptions

* **تایپ:** [`RollupDynamicImportVarsOptions`](https://github.com/rollup/plugins/tree/master/packages/dynamic-import-vars#options)
* **مرتبط:** [ایمپورت داینامیک](/guide/features#dynamic-import)

گزینه‌هایی که به [@rollup/plugin-dynamic-import-vars](https://github.com/rollup/plugins/tree/master/packages/dynamic-import-vars) ارسال می‌شن.

## build.lib

* **تایپ:** `‎{ entry: string | string[] | { [entryAlias: string]: string }, name?: string, formats?: ('es' | 'cjs' | 'umd' | 'iife')[], fileName?: string | ((format: ModuleFormat, entryName: string) => string), cssFileName?: string }`
* **مرتبط:** [حالت کتابخانه](/guide/build#library-mode)

به‌عنوان یه کتابخانه بیلد کنین. `entry` لازمه چون کتابخانه نمی‌تونه از HTML به‌عنوان ورودی استفاده کنه. `name` متغیر جهانی‌ای هست که افشا می‌شه و وقتی `formats` شامل `'umd'` یا `'iife'` باشه لازمه. فرمت‌های پیش‌فرض `['es', 'umd']` هستن، یا اگه چند ورودی استفاده بشه، `['es', 'cjs']`.

`fileName` اسم فایل خروجی بسته هست که به‌صورت پیش‌فرض از `"name"` توی `package.json` میاد. می‌تونه یه تابع باشه که `format` و `entryName` رو می‌گیره و اسم فایل رو برمی‌گردونه.

اگه بسته‌تون CSS ایمپورت می‌کنه، با `cssFileName` می‌تونین اسم فایل CSS خروجی رو مشخص کنین. اگه `fileName` یه رشته باشه، به همون مقدار پیش‌فرض می‌شه، وگرنه به `"name"` توی `package.json` برمی‌گرده.

```js twoslash [vite.config.js]
import { defineConfig } from 'vite'

export default defineConfig({
  build: {
    lib: {
      entry: ['src/main.js'],
      fileName: (format, entryName) => `my-lib-${entryName}.${format}.js`,
      cssFileName: 'my-lib-style',
    },
  },
})
```

## build.manifest

* **تایپ:** `boolean | string`
* **پیش‌فرض:** `false`
* **مرتبط:** [یکپارچه‌سازی بک‌اند](/guide/backend-integration)

آیا یه فایل manifest ساخته بشه که نگاشت اسم فایل‌های دارایی بدون هش به نسخه‌های هش‌شده‌شون رو داشته باشه، که بعدش یه فریم‌ورک سرور می‌تونه ازش برای رندر کردن لینک‌های درست دارایی‌ها استفاده کنه.

اگه مقدارش یه رشته باشه، به‌عنوان مسیر فایل manifest نسبت به `build.outDir` استفاده می‌شه. اگه `true` باشه، مسیرش `‎.vite/manifest.json` می‌شه.

## build.ssrManifest

* **تایپ:** `boolean | string`
* **پیش‌فرض:** `false`
* **مرتبط:** [رندر سمت سرور](/guide/ssr)

آیا یه فایل manifest برای SSR ساخته بشه که برای مشخص کردن لینک‌های استایل و دایرکتیوهای پیش‌بارگذاری دارایی تو تولید استفاده می‌شه.

اگه مقدارش یه رشته باشه، به‌عنوان مسیر فایل manifest نسبت به `build.outDir` استفاده می‌شه. اگه `true` باشه، مسیرش `‎.vite/ssr-manifest.json` می‌شه.

## build.ssr

* **تایپ:** `boolean | string`
* **پیش‌فرض:** `false`
* **مرتبط:** [رندر سمت سرور](/guide/ssr)

بیلد متمرکز بر SSR تولید کنه. مقدار می‌تونه یه رشته باشه که مستقیم ورودی SSR رو مشخص کنه، یا `true` باشه که نیاز داره ورودی SSR از طریق `rollupOptions.input` مشخص بشه.

## build.emitAssets

* **تایپ:** `boolean`
* **پیش‌فرض:** `false`

تو بیلدهای غیر کلاینت، asset های استاتیک منتشر نمی‌شن چون فرض می‌شه که به‌عنوان بخشی از بیلد کلاینت منتشر می‌شن. این گزینه به فریم‌ورک‌ها اجازه می‌ده تو بیلد محیط‌های دیگه انتشارشون رو اجباری کنن. وظیفه فریم‌ورکه که دارایی‌ها رو با یه مرحله بعد از بیلد ادغام کنه.

## build.ssrEmitAssets

* **تایپ:** `boolean`
* **پیش‌فرض:** `false`

تو بیلد SSR، asset های استاتیک منتشر نمی‌شن چون فرض می‌شه که به‌عنوان بخشی از بیلد کلاینت منتشر می‌شن. این گزینه به فریم‌ورک‌ها اجازه می‌ده تو هر دو بیلد کلاینت و SSR انتشارشون رو اجباری کنن. وظیفه فریم‌ورکه که دارایی‌ها رو با یه مرحله بعد از بیلد ادغام کنه. این گزینه وقتی API محیط پایدار بشه با `build.emitAssets` جایگزین می‌شه.

## build.minify

* **تایپ:** `boolean | 'terser' | 'esbuild'‎`
* **پیش‌فرض:** `'esbuild'` برای بیلد کلاینت، `false` برای بیلد SSR

با `false` مینیفای کردن رو غیرفعال کنین، یا مینیفایری که می‌خواین استفاده بشه رو مشخص کنین. پیش‌فرض [esbuild](https://github.com/evanw/esbuild) هست که 20 تا 40 برابر سریع‌تر از terser هست و فشرده‌سازیش فقط 1 تا 2 درصد ضعیف‌تره. [مقایسه‌ها](https://github.com/privatenumber/minification-benchmarks)

توجه کنین که گزینه `build.minify` تو حالت کتابخانه با فرمت `'es'` فضای خالی رو مینیفای نمی‌کنه، چون حاشیه‌نویسی‌های خالص رو حذف می‌کنه و tree-shaking رو خراب می‌کنه.

اگه روی `'terser'` تنظیم بشه، باید terser نصب بشه:

```sh
npm add -D terser
```

## build.terserOptions

* **تایپ:** `TerserOptions`

گزینه‌های اضافی [مینیفای](https://terser.org/docs/api-reference#minify-options) که به terser ارسال می‌شن.

می‌تونین یه گزینه `maxWorkers: number` هم بفرستین تا حداکثر تعداد کارگرهایی که ساخته می‌شن رو مشخص کنین. پیش‌فرضش تعداد CPUها منهای 1 هست.

## build.write

* **تایپ:** `boolean`
* **پیش‌فرض:** `true`

با `false` نوشتن باندل روی دیسک رو غیرفعال کنین. بیشتر تو فراخوانی‌های برنامه‌ریزی‌شده [`build()‎`](/guide/api-javascript#build) استفاده می‌شه که نیاز به پردازش بیشتر باندل قبل از نوشتن روی دیسک دارن.

## build.emptyOutDir

* **تایپ:** `boolean`
* **پیش‌فرض:** `true` اگه `outDir` داخل `root` باشه

به‌صورت پیش‌فرض، اگه `outDir` داخل ریشه پروژه باشه، Vite موقع بیلد اون رو خالی می‌کنه. اگه `outDir` بیرون ریشه باشه، یه هشدار می‌ده تا از حذف تصادفی فایل‌های مهم جلوگیری کنه. می‌تونین این گزینه رو صریح تنظیم کنین تا هشدار رو غیرفعال کنین. از خط فرمان هم با `‎--emptyOutDir` در دسترسه.

## build.copyPublicDir

* **تایپ:** `boolean`
* **پیش‌فرض:** `true`

به‌صورت پیش‌فرض، Vite موقع بیلد فایل‌ها رو از `publicDir` به `outDir` کپی می‌کنه. با `false` این کار رو غیرفعال کنین.

## build.reportCompressedSize

* **تایپ:** `boolean`
* **پیش‌فرض:** `true`

گزارش اندازه فشرده‌شده با gzip رو فعال یا غیرفعال کنین. فشرده‌سازی فایل‌های خروجی بزرگ می‌تونه کند باشه، پس غیرفعال کردنش ممکنه عملکرد بیلد رو برای پروژه‌های بزرگ بهتر کنه.

## build.chunkSizeWarningLimit

* **تایپ:** `number`
* **پیش‌فرض:** `500`

حد هشدار برای اندازه چانک (به کیلوبایت). با اندازه چانک فشرده‌نشده مقایسه می‌شه چون [اندازه JS خودش به زمان اجرا ربط داره](https://v8.dev/blog/cost-of-javascript-2019).

## build.watch

* **تایپ:** [`WatcherOptions`](https://rollupjs.org/configuration-options/#watch)`| null`
* **پیش‌فرض:** `null`

با `{}` ناظر rollup رو فعال کنین. بیشتر تو مواردی استفاده می‌شه که پلاگین‌ها یا فرآیندهای یکپارچه‌سازی فقط برای بیلد هستن.

::: warning استفاده از Vite تو WSL2

بعضی وقت‌ها پایش سیستم فایل تو WSL2 کار نمی‌کنه.
برای جزئیات بیشتر به [`server.watch`](./server-options.md#server-watch) نگاه کنین.

:::

---

---
url: /config/preview-options.md
---
# گزینه‌های پیش‌نمایش

مگر اینکه ذکر شده باشه، گزینه‌های این بخش فقط برای پیش‌نمایش اعمال می‌شن.

## preview.host

* **تایپ:** `string | boolean`
* **پیش‌فرض:** [`server.host`](./server-options#server-host)

مشخص می‌کنه سرور باید روی کدوم آدرس‌های IP گوش کنه. با تنظیم این روی `0.0.0.0` یا `true`، سرور روی همه آدرس‌ها، از جمله شبکه محلی (LAN) و آدرس‌های عمومی، گوش می‌ده.

این می‌تونه از طریق CLI با `host 0.0.0.0--` یا `host--` تنظیم بشه.

::: tip نکته
بعضی وقت‌ها ممکنه سرورهای دیگه به جای Vite پاسخ بدن. برای جزئیات بیشتر به [`server.host`](./server-options#server-host) نگاه کنید.
:::

## preview.allowedHosts

* **تایپ:** `string | true`
* **پیش‌فرض:** [`server.allowedHosts`](./server-options#server-allowedhosts)

نام‌های میزبانی که Vite اجازه داره بهشون پاسخ بده.

برای جزئیات بیشتر به [`server.allowedHosts`](./server-options#server-allowedhosts) مراجعه کنید.

## preview.port

* **تایپ:** `number`
* **پیش‌فرض:** `4173`

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

**مثال:**

```js
export default defineConfig({
  server: {
    port: 3030,
  },
  preview: {
    port: 8080,
  },
})
```

## preview.strictPort

* **تایپ:** `boolean`
* **پیش‌فرض:** [`server.strictPort`](./server-options#server-strictport)

اگه روی `true` تنظیم بشه، در صورتی که پورت در حال استفاده باشه، برنامه خارج می‌شه و به جای امتحان خودکار پورت بعدی، خطا می‌ده.

## preview.https

* **تایپ:** `https.ServerOptions`
* **پیش‌فرض:** [`server.https`](./server-options#server-https)

TLS و HTTP/2 رو فعال می‌کنه.

برای جزئیات بیشتر به [`server.https`](./server-options#server-https) نگاه کنید.

## preview.open

* **تایپ:** `boolean | string`
* **پیش‌فرض:** [`server.open`](./server-options#server-open)

با شروع سرور، برنامه رو به‌طور خودکار توی مرورگر باز می‌کنه. اگه مقدار یه رشته باشه، به عنوان مسیر URL استفاده می‌شه. اگه می‌خواید سرور توی مرورگر خاصی که دوست دارید باز بشه، می‌تونید متغیر محیطی `process.env.BROWSER` رو تنظیم کنید (مثلاً `firefox`). همچنین می‌تونید با `process.env.BROWSER_ARGS` آرگومان‌های اضافی بفرستید (مثلاً `incognito--`).

`BROWSER` و `BROWSER_ARGS` متغیرهای محیطی خاصی هستن که می‌تونید توی فایل `env.` تنظیم‌شون کنید. برای جزئیات بیشتر به [پکیج `open`](https://github.com/sindresorhus/open#app) مراجعه کنید.

## preview.proxy

* **تایپ:** `<Record<string, string | ProxyOptions`
* **پیش‌فرض:** [`server.proxy`](./server-options#server-proxy)

قوانین پراکسی سفارشی رو برای سرور پیش‌نمایش پیکربندی می‌کنه. یه آبجکت از جفت‌های `‎{ key: options }` انتظار داره. اگه کلید با `^` شروع بشه، به عنوان `RegExp` تفسیر می‌شه. گزینه `configure` می‌تونه برای دسترسی به نمونه پراکسی استفاده بشه.

از [`http-proxy`](https://github.com/http-party/node-http-proxy) استفاده می‌کنه. گزینه‌های کامل رو [اینجا](https://github.com/http-party/node-http-proxy#options) ببینید.

## preview.cors

* **تایپ:** `boolean | CorsOptions`
* **پیش‌فرض:** [`server.cors`](./server-options#server-cors)

CORS رو برای سرور پیش‌نمایش پیکربندی می‌کنه.

برای جزئیات بیشتر به [`server.cors`](./server-options#server-cors) نگاه کنید.

## preview.headers

* **تایپ:** `OutgoingHttpHeaders`

هدرهای پاسخ سرور رو مشخص می‌کنه.

---

---
url: /config/server-options.md
---
# گزینه‌های سرور

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

## server.host

* **تایپ:** `string | boolean`
* **پیش‌فرض:** `'localhost'`

مشخص می‌کنه سرور باید روی کدوم آدرس‌های IP گوش کنه. برای گوش دادن به همه آدرس‌ها،
از جمله LAN و آدرس‌های عمومی، این رو به `0.0.0.0` یا `true` تنظیم کنین.

می‌تونین این رو از طریق خط فرمان با `host 0.0.0.0--` یا `host--` تنظیم کنین.

::: tip نکته

بعضی وقت‌ها ممکنه سرورهای دیگه به جای Vite جواب بدن.

مورد اول وقتیه که از `localhost` استفاده می‌شه. Node.js تو نسخه‌های زیر 17 به‌صورت پیش‌فرض ترتیب آدرس‌های رفع‌شده DNS رو تغییر می‌ده. وقتی به `localhost` دسترسی پیدا می‌کنین، مرورگرها از DNS برای رفع آدرس استفاده می‌کنن و ممکنه این آدرس با چیزی که Vite بهش گوش می‌ده فرق داشته باشه. Vite اگه تفاوت داشته باشه، آدرس رفع‌شده رو چاپ می‌کنه.

می‌تونین با [`dns.setDefaultResultOrder('verbatim')`](https://nodejs.org/api/dns.html#dns_dns_setdefaultresultorder_order) این رفتار رو غیرفعال کنین. اون موقع Vite آدرس رو به‌صورت `localhost` چاپ می‌کنه.

```js twoslash [vite.config.js]
import { defineConfig } from 'vite'
import dns from 'node:dns'

dns.setDefaultResultOrder('verbatim')

export default defineConfig({
  // حذف شده
})
```

مورد دوم وقتیه که از میزبان‌های wildcard (مثل `0.0.0.0`) استفاده می‌شه. چون سرورهایی که روی میزبان‌های غیر wildcard گوش می‌دن، نسبت به اونایی که روی wildcard هستن اولویت دارن.

:::

::: tip دسترسی به سرور تو WSL2 از LAN

وقتی Vite رو تو WSL2 اجرا می‌کنین، تنظیم `host: true` برای دسترسی به سرور از LAN کافی نیست.
برای جزئیات بیشتر به [مستندات WSL](https://learn.microsoft.com/en-us/windows/wsl/networking#accessing-a-wsl-2-distribution-from-your-local-area-network-lan) نگاه کنین.

:::

## server.allowedHosts

* **تایپ:** `string[] | true`
* **پیش‌فرض:** `[]`

hostname هایی که Vite اجازه داره بهشون جواب بده.
به‌صورت پیش‌فرض، `localhost`، دامنه‌های زیر `‎.localhost` و همه آدرس‌های IP مجازن.
وقتی از HTTPS استفاده می‌کنین، این بررسی انجام نمی‌شه.

اگه یه رشته با `.` شروع بشه، اون نام میزبان بدون `.` و همه زیر دامنه‌هاش مجاز می‌شن. مثلاً `‎.example.com` شامل `example.com`، `foo.example.com` و `foo.bar.example.com` می‌شه. اگه روی `true` تنظیم بشه، سرور می‌تونه به درخواست‌های هر میزبانی جواب بده.

::: details چه میزبان‌هایی برای اضافه کردن امنن؟

میزبان‌هایی که شما کنترل آدرس‌های IPشون رو دارین، برای اضافه کردن به لیست میزبان‌های مجاز امنن.

مثلاً اگه دامنه `vite.dev` مال شماست، می‌تونین `vite.dev` و `‎.vite.dev` رو به لیست اضافه کنین. اگه مالک دامنه نیستین و به مالکش اعتماد ندارین، نباید اضافه‌ش کنین.

به‌خصوص، هیچ‌وقت دامنه‌های سطح بالا مثل `‎.com` رو به لیست اضافه نکنین. چون هر کسی می‌تونه دامنه‌ای مثل `example.com` بخره و آدرس IPش رو کنترل کنه.

:::

::: danger خطر!!

تنظیم `server.allowedHosts` به `true` به هر وب‌سایتی اجازه می‌ده با حملات DNS rebinding به سرور توسعه‌تون درخواست بفرسته و کد منبع و محتواتون رو دانلود کنه. پیشنهاد می‌کنیم همیشه از یه لیست مشخص از میزبان‌های مجاز استفاده کنین. برای جزئیات بیشتر به [GHSA-vg6x-rcgg-rjx6](https://github.com/vitejs/vite/security/advisories/GHSA-vg6x-rcgg-rjx6) نگاه کنین.

:::

::: details پیکربندی با متغیر محیطی
می‌تونین متغیر محیطی `‎__VITE_ADDITIONAL_SERVER_ALLOWED_HOSTS` رو تنظیم کنین تا یه میزبان مجاز دیگه اضافه کنین.
:::

## server.port

* **تایپ:** `number`
* **پیش‌فرض:** `5173`

پورت سرور رو مشخص می‌کنه. اگه پورت قبلاً در حال استفاده باشه، Vite خودکار پورت بعدی در دسترس رو امتحان می‌کنه، پس ممکنه پورت واقعی که سرور بهش گوش می‌ده با این فرق داشته باشه.

## server.strictPort

* **تایپ:** `boolean`

اگه روی `true` تنظیم بشه، اگه پورت در حال استفاده باشه، خارج می‌شه و پورت بعدی رو خودکار امتحان نمی‌کنه.

## server.https

* **تایپ:** `https.ServerOptions`

TLS + HTTP/2 رو فعال می‌کنه. مقدارش یه [آبجکت از گزینه‌ها](https://nodejs.org/api/https.html#https_https_createserver_options_requestlistener) هست که به `https.createServer()‎` ارسال می‌شه.

اگه گزینه [`server.proxy`](#server-proxy) هم استفاده بشه، فقط به TLS کاهش پیدا می‌کنه.

یه گواهینامه معتبر لازمه. برای تنظیم ساده، می‌تونین [‎@vitejs/plugin-basic-ssl](https://github.com/vitejs/vite-plugin-basic-ssl) رو به پلاگین‌های پروژه اضافه کنین که یه گواهینامه خود-امضا رو خودکار می‌سازه و کش می‌کنه. ولی پیشنهاد می‌کنیم گواهینامه‌های خودتون رو بسازین.

## server.open

* **تایپ:** `boolean | string`

وقتی سرور شروع می‌شه، اپلیکیشن رو خودکار تو مرورگر باز می‌کنه. اگه مقدارش یه رشته باشه، به‌عنوان مسیر URL استفاده می‌شه. اگه می‌خواین سرور تو یه مرورگر خاص باز بشه، می‌تونین متغیر محیطی `process.env.BROWSER` رو تنظیم کنین (مثلاً `firefox`). با `process.env.BROWSER_ARGS` هم می‌تونین آرگومان‌های اضافی بفرستین (مثلاً `incognito--`).

`BROWSER` و `BROWSER_ARGS` متغیرهای محیطی خاصی هستن که می‌تونین تو فایل `‎.env` تنظیم‌شون کنین. برای جزئیات بیشتر به [پکیج `open`](https://github.com/sindresorhus/open#app) نگاه کنین.

**مثال:**

```js
export default defineConfig({
  server: {
    open: '/docs/index.html',
  },
})
```

## server.proxy

* **تایپ:** `<Record<string, string | ProxyOptions`

قوانین پراکسی سفارشی رو برای سرور توسعه تنظیم می‌کنه. یه آبجکت از جفت‌های `{ key: options }` می‌خواد. هر درخواستی که مسیرش با اون کلید شروع بشه، به هدف مشخص‌شده پراکسی می‌شه. اگه کلید با `^` شروع بشه، به‌عنوان `RegExp` تفسیر می‌شه. با گزینه `configure` می‌تونین به نمونه پراکسی دسترسی پیدا کنین. اگه یه درخواست با یکی از قوانین پراکسی مطابقت کنه، توسط Vite تبدیل نمی‌شه.

اگه از [`base`](/config/shared-options.md#base) غیر نسبی استفاده می‌کنین، باید هر کلید رو با اون `base` پیشوند کنین.

بر اساس [`http-proxy`](https://github.com/http-party/node-http-proxy#options) گسترش پیدا کرده. گزینه‌های اضافی [اینجا](https://github.com/vitejs/vite/blob/main/packages/vite/src/node/server/middlewares/proxy.ts#L13) هستن.

بعضی وقت‌ها ممکنه بخواین سرور توسعه زیرین رو هم تنظیم کنین (مثلاً برای اضافه کردن میدلورهای سفارشی به اپلیکیشن داخلی [connect](https://github.com/senchalabs/connect)). برای این کار، باید یه [پلاگین](/guide/using-plugins.html) خودتون بنویسین و از تابع [configureServer](/guide/api-plugin.html#configureserver) استفاده کنین.

**مثال:**

```js
export default defineConfig({
  server: {
    proxy: {
      // :کوتاه‌نویسی رشته
      // http://localhost:5173/foo
      //   -> http://localhost:4567/foo
      '/foo': 'http://localhost:4567',
      // :با گزینه‌ها
      // http://localhost:5173/api/bar
      //   -> http://jsonplaceholder.typicode.com/bar
      '/api': {
        target: 'http://jsonplaceholder.typicode.com',
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/api/, ''),
      },
      // :RegExp با
      // http://localhost:5173/fallback/
      //   -> http://jsonplaceholder.typicode.com/
      '^/fallback/.*': {
        target: 'http://jsonplaceholder.typicode.com',
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/fallback/, ''),
      },
      // استفاده از نمونه پراکسی
      '/api': {
        target: 'http://jsonplaceholder.typicode.com',
        changeOrigin: true,
        configure: (proxy, options) => {
          // خواهد بود 'http-proxy' یک نمونه از  proxy کلید
        },
      },

      // :socket.io یا websockets پراکسی کردن
      // ws://localhost:5173/socket.io
      //   -> ws://localhost:5174/socket.io
      // .آسیب ‌پذیر شود CSRF احتیاط کنید زیرا ممکن است در برابر حملات `rewriteWsOrigin` هنگام استفاده از
      '/socket.io': {
        target: 'ws://localhost:5174',
        ws: true,
        rewriteWsOrigin: true,
      },
    },
  },
})
```

## server.cors

* **تایپ:** `boolean | CorsOptions`
* **پیش‌فرض:**  `‎{ origin: /^https?:\/\/(?:(?:[^:]+\.)?localhost|127\.0\.0\.1|\[::1\])(?::\d+)?$/ }‎` (اجازه‌ی دسترسی به localhost و `127.0.0.1**‎`و `::1`)

CORS رو برای سرور توسعه تنظیم می‌کنه. یه [آبجکت از گزینه‌ها](https://github.com/expressjs/cors#configuration-options) بفرستین تا رفتارش رو دقیق تنظیم کنین یا با `true` به هر مبدأ اجازه بدین.

::: danger خطر!!

تنظیم `server.cors` به `true` به هر وب‌سایتی اجازه می‌ده به سرور توسعه‌تون درخواست بفرسته و کد منبع و محتواتون رو دانلود کنه. پیشنهاد می‌کنیم همیشه از یه لیست مشخص از مبدأهای مجاز استفاده کنین.

:::

## server.headers

* **تایپ:** `OutgoingHttpHeaders`

هدرهای پاسخ سرور رو مشخص می‌کنه.

## server.hmr

* **تایپ:**  `boolean | { protocol?: string, host?: string, port?: number, path?: string, timeout?: number, overlay?: boolean, clientPort?: number, server?: Server }`

اتصال HMR رو غیرفعال یا تنظیم می‌کنه (برای وقتی که وب‌سوکت HMR باید آدرس متفاوتی از سرور HTTP استفاده کنه).

با تنظیم `server.hmr.overlay` به `false` می‌تونین پوشش خطای سرور رو غیرفعال کنین.

`protocol` پروتکل وب‌سوکت رو برای اتصال HMR مشخص می‌کنه: `ws` (وب‌سوکت) یا `wss` (وب‌سوکت امن).

`clientPort` یه گزینه پیشرفته‌ست که فقط پورت سمت کلاینت رو بازنویسی می‌کنه و بهتون اجازه می‌ده وب‌سوکت رو روی پورتی متفاوت از چیزی که کد کلاینت دنبالش می‌گرده ارائه بدین.

اگه `server.hmr.server` تعریف بشه، Vite درخواست‌های اتصال HMR رو از طریق سرور داده‌شده پردازش می‌کنه. اگه تو حالت میدلور نباشه، Vite سعی می‌کنه درخواست‌ها رو از طریق سرور موجود پردازش کنه. این می‌تونه برای استفاده از گواهینامه‌های خود-امضا یا ارائه Vite روی شبکه با یه پورت واحد مفید باشه.

برای مثال‌ها به [`vite-setup-catalogue`](https://github.com/sapphi-red/vite-setup-catalogue) نگاه کنین.

::: tip نکته

تو تنظیمات پیش‌فرض، انتظار می‌ره پراکسی‌های معکوس جلوی Vite از پراکسی وب‌سوکت پشتیبانی کنن. اگه کلاینت HMR Vite نتونه به وب‌سوکت وصل بشه، کلاینت به اتصال مستقیم وب‌سوکت به سرور HMR Vite برمی‌گرده و پراکسی‌های معکوس رو دور می‌زنه:

```
Direct websocket connection fallback. Check out https://vite.dev/config/server-options.html#server-hmr to remove the previous connection error.
```

خطایی که تو مرورگر موقع این بازگشت نشون داده می‌شه رو می‌تونین نادیده بگیرین. برای جلوگیری از خطا با دور زدن مستقیم پراکسی‌ها، می‌تونین:

* پراکسی معکوس رو طوری تنظیم کنین که وب‌سوکت رو هم پراکسی کنه
* [`server.strictPort = true`](#server-strictport) رو فعال کنین و `server.hmr.clientPort` رو با `server.port` یکی کنین
* `server.hmr.port` رو یه مقدار متفاوت از [`server.port`](#server-port) تنظیم کنین

:::

## server.warmup

* **تایپ:** `{ []clientFiles?: string[], ssrFiles?: string }`
* **مرتبط:** [فایل‌های پر استفاده را پیش‌بارگذاری کنید](/guide/performance.html#فایل‌های-پر-استفاده-را-پیش‌بارگذاری-کنید)

فایل‌ها را از قبل پردازش و در کش ذخیره می‌کند تا بارگذاری اولیه صفحه هنگام راه‌اندازی سرور سریع‌تر شود و از پردازش‌های پیاپی جلوگیری کند.

`clientFiles` فایل‌هایی هستن که فقط تو کلاینت استفاده می‌شن و `ssrFiles` فایل‌هایی که فقط تو SSR استفاده می‌شن. اینا یه آرایه از مسیرهای فایل یا الگوهای [`tinyglobby`](https://github.com/SuperchupuDev/tinyglobby) نسبت به `root` قبول می‌کنن.

فقط فایل‌هایی رو اضافه کنین که زیاد استفاده می‌شن تا سرور توسعه Vite موقع شروع بیش از حد بارگذاری نشه.

```js
export default defineConfig({
  server: {
    warmup: {
      clientFiles: ['./src/components/*.vue', './src/utils/big-utils.js'],
      ssrFiles: ['./src/server/modules/*.js'],
    },
  },
})
```

## server.watch

* **تایپ:** `object | null`

گزینه‌های ناظر سیستم فایل که به [chokidar](https://github.com/paulmillr/chokidar/tree/3.6.0#api) ارسال می‌شن.

ناظر سرور `root` رو تماشا می‌کنه و به‌صورت پیش‌فرض دایرکتوری‌های `test-results/`‎ ، `node_modules` ، `git` و دایرکتوری‌های `cacheDir` و `build.outDir` Vite رو نادیده می‌گیره. وقتی یه فایل تماشا‌ شده تغییر می‌کنه، Vite HMR رو اعمال می‌کنه و صفحه رو فقط اگه نیاز باشه به‌روز می‌کنه.

اگه روی `null` تنظیم بشه، هیچ فایلی تماشا نمی‌شه. `server.watcher` یه منتشرکننده رویداد سازگار می‌ده، ولی فراخوانی `add` یا `unwatch` اثری نداره.

::: warning تماشای فایل‌ها تو `node_modules`

الان نمی‌شه فایل‌ها و بسته‌ها تو `node_modules` رو تماشا کرد. برای پیشرفت بیشتر و راه‌حل‌ها، می‌تونین [موضوع #8619](https://github.com/vitejs/vite/issues/8619) رو دنبال کنین.

:::

::: warning استفاده از Vite تو WSL2

وقتی Vite رو تو WSL2 اجرا می‌کنین، اگه فایل با برنامه‌های ویندوز (فرایند غیر WSL2) ویرایش بشه، تماشای سیستم فایل کار نمی‌کنه. این به خاطر [یه محدودیت WSL2](https://github.com/microsoft/WSL/issues/4739) هست. این برای اجرا تو Docker با بک‌اند WSL2 هم صدق می‌کنه.

برای درست کردنش، می‌تونین:

* **توصیه‌شده:** از برنامه‌های WSL2 برای ویرایش فایل‌هاتون استفاده کنین.
  * بهتره پوشه پروژه رو بیرون از سیستم فایل ویندوز بذارین. دسترسی به سیستم فایل ویندوز از WSL2 کنده و حذف این سربار عملکرد رو بهتر می‌کنه.
* `{ usePolling: true }` رو تنظیم کنین.
  * توجه کنین که [`usePolling` مصرف CPU رو بالا می‌بره](https://github.com/paulmillr/chokidar/tree/3.6.0#performance).

:::

## server.middlewareMode

* **تایپ:** `boolean`
* **پیش‌فرض:** `false`

سرور Vite رو تو حالت میدلور می‌سازه.

* **مرتبط:** [appType](./shared-options#apptype) ، [SSR - تنظیم سرور توسعه](/guide/ssr#setting-up-the-dev-server)

* **مثال:**

```js twoslash
import express from 'express'
import { createServer as createViteServer } from 'vite'

async function createServer() {
  const app = express()

  // middleware در حالت Vite ایجاد سرور
  const vite = await createViteServer({
    server: { middlewareMode: true },
    // را حذف کن HTML Vite میان‌افزارهای پیش‌فرض
    appType: 'custom',
  })
  // Vite استفاده از میان‌افزارهای
  app.use(vite.middlewares)

  app.use('*', async (req, res) => {
    // .است، پاسخ باید اینجا ارسال شود 'custom' برابر appType چون
    // ،باشد 'mpa' یا 'spa' برابر appType توجه: اگر
    // ،و خطای ۴۰۴ اضافه می‌کند HTML میان‌افزارهایی برای Vite
    // .قرار بگیرند Vite بنابراین میان‌افزارهای کاربر باید قبل از میان‌افزارهای
  })
}

createServer()
```

## server.fs.strict

* **تایپ:** `boolean`
* **پیش‌فرض:** `true` (از Vite 2.7 به‌صورت پیش‌فرض فعاله)

جلوگیری از دسترسی و ارائه فایل‌هایی که خارج از پوشه اصلی پروژه (workspace root) قرار دارند.

## server.fs.allow

* **تایپ:** `[]string`

فایل‌هایی که می‌تونن از طریق `/@fs/` ارائه بشن رو محدود می‌کنه. وقتی `server.fs.strict` روی `true` باشه، دسترسی به فایل‌های بیرون این لیست که از یه فایل مجاز ایمپورت نشدن، خطای 403 می‌ده.

هم دایرکتوری‌ها و هم فایل‌ها رو می‌تونین بدین.

Vite ریشه فضای کاری احتمالی رو پیدا می‌کنه و به‌عنوان پیش‌فرض استفاده می‌کنه. یه فضای کاری معتبر باید این شرایط رو داشته باشه، وگرنه به [ریشه پروژه](/guide/#index-html-و-ریشه-root-پروژه) برمی‌گرده:

* تو `package.json` فیلد `workspaces` داشته باشه
* یکی از این فایل‌ها رو داشته باشه:
  * `lerna.json`
  * `pnpm-workspace.yaml`

یه مسیر رو برای مشخص کردن ریشه فضای کاری سفارشی قبول می‌کنه. می‌تونه مسیر مطلق یا نسبی به [ریشه پروژه](/guide/#index-html-و-ریشه-root-پروژه) باشه. مثلاً:

```js
export default defineConfig({
  server: {
    fs: {
      // اجازه ارائه فایل‌ها از یه سطح بالاتر از ریشه پروژه
      allow: ['..'],
    },
  },
})
```

وقتی `server.fs.allow` مشخص بشه، تشخیص خودکار ریشه فضای کاری غیرفعال می‌شه. برای گسترش رفتار اصلی، یه ابزار `searchForWorkspaceRoot` ارائه شده:

```js
import { defineConfig, searchForWorkspaceRoot } from 'vite'

export default defineConfig({
  server: {
    fs: {
      allow: [
        // جستجو برای ریشه فضای کاری
        searchForWorkspaceRoot(process.cwd()),
        // قوانین سفارشی‌تون
        '/path/to/custom/allow_directory',
        '/path/to/custom/allow_file.demo',
      ],
    },
  },
})
```

## server.fs.deny

* **تایپ:** `[]string`
* **پیش‌فرض:** `['‎.env', '‎.env.*', '*.{crt,pem}', '**/.git/**‎']`

لیست سیاه برای فایل‌های حساسی که سرور توسعه Vite نمی‌تونه ارائه‌شون کنه. این نسبت به [`server.fs.allow`](#server-fs-allow) اولویت بالاتری داره. الگوهای [picomatch](https://github.com/micromatch/picomatch#globbing-features) پشتیبانی می‌شن.

::: tip نکته

فهرست مسدودسازی برای [دایرکتوری عمومی (public)](/guide/assets.md#the-public-directory) اعمال نمی‌شود. تمام فایل‌های موجود در دایرکتوری عمومی بدون هیچ‌گونه فیلترسازی ارائه می‌شوند، چرا که در هنگام ساخت (build) به‌صورت مستقیم در دایرکتوری خروجی کپی می‌شوند.

:::

## server.origin

* **تایپ:** `string`

مبدأ URLهای asset های تولیدشده رو تو زمان توسعه مشخص می‌کنه.

```js
export default defineConfig({
  server: {
    origin: 'http://127.0.0.1:8080',
  },
})
```

## server.sourcemapIgnoreList

* **تایپ:** `false | (sourcePath: string, sourcemapPath: string) => boolean`
* **پیش‌فرض:** `‎(sourcePath) => sourcePath.includes('node_modules')`

اینکه فایل‌های منبع تو sourcemap سرور نادیده گرفته بشن یا نه، برای پر کردن افزونه [`x_google_ignoreList` sourcemap](https://developer.chrome.com/articles/x-google-ignore-list/) استفاده می‌شه.

`server.sourcemapIgnoreList` معادل [`build.rollupOptions.output.sourcemapIgnoreList`](https://rollupjs.org/configuration-options/#output-sourcemapignorelist) برای سرور توسعه‌ست. تفاوت این دو گزینه اینه که تابع rollup با یه مسیر نسبی برای `sourcePath` فراخوانی می‌شه، ولی `server.sourcemapIgnoreList` با یه مسیر مطلق. تو توسعه، بیشتر ماژول‌ها نقشه و منبع رو تو یه پوشه دارن، پس مسیر نسبی برای `sourcePath` خود اسم فایله. تو این موارد، مسیرهای مطلق راحت‌ترن.

به‌صورت پیش‌فرض، همه مسیرهای شامل `node_modules` رو مستثنی می‌کنه. می‌تونین با `false` این رفتار رو غیرفعال کنین، یا برای کنترل کامل، یه تابع بدین که مسیر منبع و مسیر sourcemap رو می‌گیره و مشخص می‌کنه که مسیر منبع نادیده گرفته بشه یا نه.

```js
export default defineConfig({
  server: {
    // دارند node_modules این مقدار پیش‌فرض است و تمام فایل‌هایی که در مسیرشان
    // را به لیست نادیده‌گیری اضافه می‌کند
    sourcemapIgnoreList(sourcePath, sourcemapPath) {
      return sourcePath.includes('node_modules')
    },
  },
})
```

::: tip نکته
[`server.sourcemapIgnoreList`](#server-sourcemapignorelist) و [`build.rollupOptions.output.sourcemapIgnoreList`](https://rollupjs.org/configuration-options/#output-sourcemapignorelist) باید جداگانه تنظیم بشن. `server.sourcemapIgnoreList` فقط برای سروره و مقدار پیش‌فرضش از گزینه‌های rollup تعریف‌شده نمیاد.
:::

---

---
url: /config/shared-options.md
---
# گزینه‌های مشترک

مگر اینکه ذکر شده باشد، گزینه‌های این بخش برای همه حالت‌های توسعه (dev)، ساخت (build) و پیش‌نمایش (preview) اعمال می‌شوند.

## root

* **تایپ:** `string`
* **پیش‌فرض:** `()process.cwd`

پوشه ریشه پروژه (محلی که فایل `index.html` در آن قرار دارد). می‌تواند یک مسیر مطلق یا یک مسیر نسبت به پوشه کاری فعلی باشد.

برای اطلاعات بیشتر، به [ریشه پروژه](/guide/#index-html-و-ریشه-root-پروژه) مراجعه کنید.

## base

* **تایپ:** `string`
* **پیش‌فرض:** `/`
* **مرتبط:** [`server.origin`](/config/server-options.md#server-origin)

مسیر عمومی پایه هنگام ارائه در توسعه یا تولید. مقادیر معتبر شامل موارد زیر هستند:

* مسیر URL مطلق، مثل `/foo/`
* URL کامل، مثل `/https://bar.com/foo` (بخش origin در توسعه استفاده نمی‌شود، بنابراین مقدار همان `/foo/` است)
* رشته خالی یا `/.` (برای استقرار جاسازی‌شده)

برای اطلاعات بیشتر، به [مسیر پایه عمومی](/guide/build#public-base-path) مراجعه کنید.

## mode

* **تایپ:** `string`
* **پیش‌فرض:** `'development'` برای توسعه، `'production'` برای ساخت

مشخص کردن این در تنظیمات، حالت پیش‌فرض را برای **هر دو توسعه و ساخت** بازنویسی می‌کند. این مقدار همچنین می‌تواند از طریق گزینه `mode--` در خط فرمان بازنویسی شود.

برای اطلاعات بیشتر، به [متغیرهای محیطی و حالت‌ها](/guide/env-and-mode) مراجعه کنید.

## define

* **تایپ:** `<Record<string, any`

تعریف جایگزین‌های ثابت سراسری. موارد تعریف‌شده در طول توسعه به صورت سراسری تعریف می‌شوند و در زمان ساخت به صورت ایستا جایگزین می‌شوند.

Vite از [تعاریف esbuild](https://esbuild.github.io/api/#define) برای انجام جایگزینی‌ها استفاده می‌کند، بنابراین عبارات مقدار باید یک رشته شامل مقدار قابل سریال‌سازی JSON (null، بولین، عدد، رشته، آرایه یا آبجکت) یا یک شناسه واحد باشند. برای مقادیر غیررشته‌ای، Vite به صورت خودکار آن را با `JSON.stringify` به رشته تبدیل می‌کند.

**مثال:**

```js
export default defineConfig({
  define: {
    __APP_VERSION__: JSON.stringify('v1.0.0'),
    __API_URL__: 'window.__backend_api_url',
  },
})
```

::: tip نکته
برای کاربران TypeScript، مطمئن شوید که اعلان‌های تایپ را در فایل `vite-env.d.ts` اضافه کرده‌اید تا بررسی تایپ و Intellisense داشته باشید.

مثال:

```ts
// vite-env.d.ts
declare const __APP_VERSION__: string
```

:::

## plugins

* **تایپ:** `[](<[]Plugin | Plugin[] | Promise<Plugin | Plugin)`

آرایه‌ای از پلاگین‌ها برای استفاده. پلاگین‌های falsy نادیده گرفته می‌شوند و آرایه‌های پلاگین‌ها به یک آرایه‌ی ساده تبدیل می‌شوند. اگر یک Promise برگردانده شود، قبل از اجرا رفع می‌شود. برای اطلاعات بیشتر در مورد پلاگین‌های Vite، به [API پلاگین](/guide/api-plugin) مراجعه کنید.

## publicDir

* **تایپ:** `string | false`
* **پیش‌فرض:** `"public"`

پوشه‌ای برای ارائه به عنوان دارایی‌های استاتیک ساده. فایل‌های این پوشه در طول توسعه در `/` ارائه می‌شوند و در زمان ساخت به ریشه `outDir` کپی می‌شوند و همیشه بدون تغییر ارائه یا کپی می‌شوند. مقدار می‌تواند یک مسیر مطلق در سیستم فایل یا یک مسیر نسبت به ریشه پروژه باشد.

تنظیم `publicDir` به `false` این قابلیت را غیرفعال می‌کند.

برای اطلاعات بیشتر، به [پوشه `public`](/guide/assets.html#دایرکتوری-public) مراجعه کنید.

## cacheDir

* **تایپ:** `string`
* **پیش‌فرض:** `"node_modules/.vite"`

پوشه‌ای برای ذخیره فایل‌های کش. فایل‌های این پوشه شامل وابستگی‌های پیش‌باندل‌شده یا سایر فایل‌های کش تولیدشده توسط Vite هستند که می‌توانند عملکرد را بهبود ببخشند. می‌توانید از پرچم `force--` استفاده کنید یا پوشه را به صورت دستی حذف کنید تا فایل‌های کش دوباره تولید شوند. مقدار می‌تواند یک مسیر مطلق در سیستم فایل یا یک مسیر نسبت به ریشه پروژه باشد. اگر فایل `package.json` تشخیص داده نشود، به صورت پیش‌فرض `vite.` خواهد بود.

## resolve.alias

* **تایپ:**&#x20;
  `Record<string, string> | Array<{ find: string | RegExp, replacement: string, customResolver?: ResolverFunction | ResolverObject }>`

به `rollup/plugin-alias@` به عنوان [گزینه entries](https://github.com/rollup/plugins/tree/master/packages/alias#entries) منتقل می‌شود. می‌تواند یک آبجکت یا آرایه‌ای از جفت‌های `{ find, replacement, customResolver }` باشد.

هنگام استفاده از alias برای مسیرهای سیستم فایل، همیشه از مسیرهای مطلق استفاده کنید. مقادیر alias نسبی به همان شکل استفاده می‌شوند و به مسیرهای سیستم فایل تبدیل نمی‌شوند.

برای انجام پردازش‌های پیشرفته‌تر هنگام حل مسیرها (resolution)، می‌توان از [پلاگین‌ها](/guide/api-plugin) استفاده کرد.

::: warning استفاده با SSR
اگر alias‌هایی را برای [وابستگی‌های خارجی SSR](/guide/ssr.md#ssr-externals) تنظیم کرده‌اید، ممکن است بخواهید پکیج‌های واقعی `node_modules` را alias کنید. هر دو [Yarn](https://classic.yarnpkg.com/en/docs/cli/add/#toc-yarn-add-alias) و [pnpm](https://pnpm.io/aliases/) از alias کردن از طریق پیشوند `:npm` پشتیبانی می‌کنند.
:::

## resolve.dedupe

* **تایپ:** `[]string`

اگر در پروژه‌ی خود چندین نسخه‌ی تکراری از یک کتابخانه یا وابستگی دارید (مثلاً به دلیل مدیریت وابستگی‌ها با hoisting یا بسته‌های لینک‌شده در یک monorepo)، می‌توانید از این گزینه استفاده کنید تا Vite همیشه فقط یک نسخه‌ی مشخص از آن کتابخانه را استفاده کند. این کار از بروز مشکلات ناسازگاری و افزایش حجم نهایی جلوگیری می‌کند، زیرا همه‌ی بخش‌های پروژه از یک نسخه‌ی مشترک استفاده خواهند کرد.

::: warning SSR + ESM
برای ساخت‌های SSR، حذف تکرار در خروجی‌های ساخت ESM که از `build.rollupOptions.output` تنظیم شده‌اند کار نمی‌کند. راه‌حل موقت استفاده از خروجی‌های ساخت CJS است تا زمانی که ESM پشتیبانی بهتری برای بارگذاری ماژول از پلاگین‌ها داشته باشد.
:::

## resolve.conditions

* **تایپ:** `[]string`
* **پیش‌فرض:**`['module', 'browser', 'development|production']` (`defaultClientConditions`)

شرایط اضافی که هنگام تعیین مسیر خروجی‌های شرطی ([Conditional Exports](https://nodejs.org/api/packages.html#packages_conditional_exports)) از یک پکیج مجاز هستند.

یک پکیج با اکسپورت‌های شرطی ممکن است فیلد `exports` زیر را در `package.json` خود داشته باشد:

```json
{
  "exports": {
    ".": {
      "import": "./index.mjs",
      "require": "./index.js"
    }
  }
}
```

در اینجا، `import` و `require` "شرایط" هستند. شرایط می‌توانند تودرتو باشند و باید از خاص‌ترین به عمومی‌ترین مشخص شوند.

`development|production` یک مقدار خاص است که بسته به مقدار `process.env.NODE_ENV` با `production` یا `development` جایگزین می‌شود. وقتی `'process.env.NODE_ENV === 'production` باشد، به `production` و در غیر این صورت به `development` تبدیل می‌شود.

توجه کنید که شرایط `import`، `require` و `default` همیشه در صورت برآورده شدن الزامات اعمال می‌شوند.

## resolve.mainFields

* **تایپ:** `[]string`
* **پیش‌فرض:** (`defaultClientMainFields`) `['browser', 'module', 'jsnext:main', 'jsnext']`

فهرست فیلدهایی در `package.json` که هنگام رزولوشن نقطه ورود یک پکیج امتحان می‌شوند. توجه داشته باشید که این اولویت کمتری نسبت به اکسپورت شرطی رزولوش‌شده از فیلد `exports` دارد: اگر نقطه ورودی با موفقیت از `exports` رزولوش شود، فیلد main نادیده گرفته می‌شود.

## resolve.extensions

* **تایپ:** `[]string`
* **پیش‌فرض:** `['mjs', '.js', '.mts', '.ts', '.jsx', '.tsx', '.json.']`

فهرست پسوندهای فایل برای امتحان کردن در ایمپورت‌هایی که پسوند را حذف کرده‌اند. توجه داشته باشید که توصیه نمی‌شود پسوندها را برای تایپ‌های ایمپورت سفارشی (مثل `vue.`) حذف کنید، زیرا می‌تواند با پشتیبانی IDE و تایپ تداخل داشته باشد.

## resolve.preserveSymlinks

* **تایپ:** `boolean`
* **پیش‌فرض:** `false`

فعال کردن این تنظیم باعث می‌شود Vite هویت فایل را بر اساس مسیر اصلی فایل (یعنی مسیر بدون دنبال کردن symlink‌ها) به جای مسیر واقعی فایل (یعنی مسیر پس از دنبال کردن symlink‌ها) تعیین کند.

* **مرتبط:** [esbuild#preserve-symlinks](https://esbuild.github.io/api/#preserve-symlinks)،
  [webpack#resolve.symlinks](https://webpack.js.org/configuration/resolve/#resolvesymlinks)

## html.cspNonce

* **تایپ:** `string`
* **مرتبط:** [سیاست امنیتی محتوا (CSP)](/guide/features#content-security-policy-csp)

یک نگهدارنده مقدار nonce که هنگام تولید تگ‌های اسکریپت/استایل استفاده می‌شود. تنظیم این مقدار همچنین یک تگ meta با مقدار nonce تولید می‌کند.

## css.modules

* **تایپ:**
  ```ts
  interface CSSModulesOptions {
    getJSON?: (
      cssFileName: string,
      json: Record<string, string>,
      outputFileName: string,
    ) => void
    scopeBehaviour?: 'global' | 'local'
    globalModulePaths?: RegExp[]
    exportGlobals?: boolean
    generateScopedName?:
      | string
      | ((name: string, filename: string, css: string) => string)
    hashPrefix?: string
    /**
     * undefined :پیش‌فرض
     */
    localsConvention?:
      | 'camelCase'
      | 'camelCaseOnly'
      | 'dashes'
      | 'dashesOnly'
      | ((
          originalClassName: string,
          generatedClassName: string,
          inputFile: string,
        ) => string)
  }
  ```

رفتار ماژول‌های CSS را پیکربندی می‌کند. گزینه‌ها به [postcss-modules](https://github.com/css-modules/postcss-modules) منتقل می‌شوند.

این گزینه هنگام استفاده از [Lightning CSS](../guide/features.md#lightning-css) تأثیری ندارد. در صورت فعال بودن، باید از [`css.lightningcss.cssModules`](https://lightningcss.dev/css-modules.html) استفاده شود.

## css.postcss

* **تایپ:** `string | (postcss.ProcessOptions & { plugins?: postcss.AcceptedPlugin[] })`

پیکربندی درون‌خطی PostCSS یا یک پوشه سفارشی برای جستجوی پیکربندی PostCSS (پیش‌فرض ریشه پروژه است).

برای پیکربندی درون‌خطی PostCSS، فرمت مشابه `postcss.config.js` انتظار می‌رود. اما برای ویژگی `plugins`، فقط [فرمت آرایه](https://github.com/postcss/postcss-load-config/blob/main/README.md#array) قابل استفاده است.

جستجو با استفاده از [postcss-load-config](https://github.com/postcss/postcss-load-config) انجام می‌شود و فقط نام‌های فایل پیکربندی پشتیبانی‌شده بارگذاری می‌شوند. فایل‌های پیکربندی خارج از ریشه workspace (یا [ریشه پروژه](/guide/#index-html-و-ریشه-root-پروژه) اگر workspace یافت نشود) به صورت پیش‌فرض جستجو نمی‌شوند. در صورت نیاز، می‌توانید یک مسیر سفارشی خارج از ریشه را برای بارگذاری فایل پیکربندی خاص مشخص کنید.

توجه داشته باشید اگر پیکربندی درون‌خطی ارائه شود، Vite برای سایر منابع پیکربندی PostCSS جستجو نمی‌کند.

## css.preprocessorOptions

* **تایپ:** `<Record<string, object`

گزینه‌هایی را برای انتقال به پیش‌پردازنده‌های CSS مشخص می‌کند. پسوندهای فایل به عنوان کلید برای گزینه‌ها استفاده می‌شوند. گزینه‌های پشتیبانی‌شده برای هر پیش‌پردازنده را می‌توان در مستندات مربوطه آنها یافت:

* `sass`/`scss`:
  * اگر پکیج `sass-embedded` نصب شده باشد، از آن استفاده می‌کند؛ در غیر این صورت از `sass` معمولی استفاده می‌شود. برای عملکرد بهتر، توصیه می‌شود پکیج `sass-embedded` را نصب کنید.
  * [گزینه‌ها](https://sass-lang.com/documentation/js-api/interfaces/stringoptions/)
* `less`: [گزینه‌ها](https://lesscss.org/usage/#less-options).
* `styl`/`stylus`: فقط [`define`](https://stylus-lang.com/docs/js.html#define-name-node) پشتیبانی می‌شود که می‌تواند به صورت یک آبجکت منتقل شود.

**مثال:**

```js
export default defineConfig({
  css: {
    preprocessorOptions: {
      less: {
        math: 'parens-division',
      },
      styl: {
        define: {
          $specialColor: new stylus.nodes.RGBA(51, 197, 255, 1),
        },
      },
      scss: {
        importers: [
          // ...
        ],
      },
    },
  },
})
```

### css.preprocessorOptions\[extension].additionalData

* **تایپ:** `string | ((source: string, filename: string) => (string | { content: string; map?: SourceMap }))`

این گزینه می‌تواند برای تزریق کد اضافی به هر محتوای استایل استفاده شود. توجه داشته باشید که اگر استایل‌های واقعی و نه فقط متغیرها را شامل شوید، این استایل‌ها در باندل نهایی تکرار خواهند شد.

**مثال:**

```js
export default defineConfig({
  css: {
    preprocessorOptions: {
      scss: {
        additionalData: `$injectedColor: orange;`,
      },
    },
  },
})
```

## css.preprocessorMaxWorkers

* **تایپ:** `number | true`
* **پیش‌فرض:** `true`

تعداد حداکثری رشته‌های پردازشی (threads) که پیش‌پردازنده‌های CSS می‌توانند استفاده کنند را مشخص می‌کند. اگر مقدار `true` باشد، به این معنی است که از حداکثر تعداد هسته‌های CPU منهای یک استفاده خواهد شد. اگر مقدار `0` تنظیم شود، Vite هیچ پردازشگری ایجاد نمی‌کند و پیش‌پردازنده‌ها را در نخ اصلی (main thread) اجرا خواهد کرد.

بسته به تنظیمات پیش‌پردازنده، ممکن است Vite حتی اگر این گزینه روی `0` تنظیم نشده باشد، باز هم پیش‌پردازنده‌ها را در نخ اصلی اجرا کند.

## css.devSourcemap

* **آزمایشی:** [بازخورد دهید](https://github.com/vitejs/vite/discussions/13845)
* **تایپ:** `boolean`
* **پیش‌فرض:** `false`

آیا در طول توسعه sourcemap‌ها فعال شوند یا خیر.

## css.transformer

* **آزمایشی:** [بازخورد دهید](https://github.com/vitejs/vite/discussions/13835)
* **تایپ:** `'postcss' | 'lightningcss'`
* **پیش‌فرض:** `'postcss'`

موتور مورد استفاده برای پردازش CSS را انتخاب می‌کند. برای اطلاعات بیشتر به [Lightning CSS](../guide/features.md#lightning-css) مراجعه کنید.

::: info تکرار `import@`ها
توجه داشته باشید که postcss (postcss-import) رفتار متفاوتی با `import@`های تکراری نسبت به مرورگرها دارد. به [postcss/postcss-import#462](https://github.com/postcss/postcss-import/issues/462) مراجعه کنید.
:::

## css.lightningcss

* **آزمایشی:** [بازخورد دهید](https://github.com/vitejs/vite/discussions/13835)
* **تایپ:**

```js
import type {
  CSSModulesConfig,
  Drafts,
  Features,
  NonStandard,
  PseudoClasses,
  Targets,
} from 'lightningcss'
```

```js
{
  targets?: Targets
  include?: Features
  exclude?: Features
  drafts?: Drafts
  nonStandard?: NonStandard
  pseudoClasses?: PseudoClasses
  unusedSymbols?: string[]
  cssModules?: CSSModulesConfig,
  // ...
}
```

Lightning CSS را پیکربندی می‌کند. گزینه‌های کامل تبدیل را می‌توان در [مخزن Lightning CSS](https://github.com/parcel-bundler/lightningcss/blob/master/node/index.d.ts) یافت.

## json.namedExports

* **تایپ:** `boolean`
* **پیش‌فرض:** `true`

آیا از ایمپورت‌های نام‌گذاری‌شده از فایل‌های `json.` پشتیبانی شود یا خیر.

## json.stringify

* **تایپ:** `boolean | 'auto'`
* **پیش‌فرض:** `'auto'`

اگر روی `true` تنظیم شود، JSON ایمپورت‌شده به `("...")export default JSON.parse` تبدیل می‌شود که به طور قابل‌توجهی عملکرد بهتری نسبت به آبجکت‌های لفظی دارد، به‌ویژه وقتی فایل JSON بزرگ باشد.

اگر روی `'auto'` تنظیم شود، داده‌ها فقط در صورتی به رشته تبدیل می‌شوند که [داده بزرگ‌تر از 10 کیلوبایت باشد](https://v8.dev/blog/cost-of-javascript-2019#json:~:text=A%20good%20rule%20of%20thumb%20is%20to%20apply%20this%20technique%20for%20objects%20of%2010%20kB%20or%20larger).

## esbuild

* **تایپ:** `ESBuildOptions | false`

`ESBuildOptions` گزینه‌های تبدیل خود [esbuild](https://esbuild.github.io/api/#transform) را گسترش می‌دهد. رایج‌ترین مورد استفاده، سفارشی‌سازی JSX است:

```js
export default defineConfig({
  esbuild: {
    jsxFactory: 'h',
    jsxFragment: 'Fragment',
  },
})
```

به صورت پیش‌فرض، esbuild روی فایل‌های `ts`، `jsx` و `tsx` اعمال می‌شود. می‌توانید این را با `esbuild.include` و `esbuild.exclude` که می‌تواند یک regex، یک الگوی [picomatch](https://github.com/micromatch/picomatch#globbing-features)، یا آرایه‌ای از هر کدام باشد، سفارشی کنید.

علاوه بر این، می‌توانید از `esbuild.jsxInject` برای تزریق خودکار ایمپورت‌های کمکی JSX برای هر فایلی که توسط esbuild تبدیل می‌شود استفاده کنید:

```js
export default defineConfig({
  esbuild: {
    jsxInject: `import React from 'react'`,
  },
})
```

وقتی [`build.minify`](./build-options.md#build-minify) روی `true` باشد، همه بهینه‌سازی‌های فشرده‌سازی به صورت پیش‌فرض اعمال می‌شوند. برای غیرفعال کردن [جنبه‌های خاصی](https://esbuild.github.io/api/#minify) از آن، هر یک از گزینه‌های `esbuild.minifyIdentifiers`، `esbuild.minifySyntax` یا `esbuild.minifyWhitespace` را روی `false` تنظیم کنید. توجه داشته باشید که گزینه `esbuild.minify` نمی‌تواند `build.minify` را بازنویسی کند.

برای غیرفعال کردن تبدیل‌های esbuild، روی `false` تنظیم کنید.

## assetsInclude

* **تایپ:** `[]string | RegExp | (string | RegExp)`
* **مرتبط:** [مدیریت دارایی‌های استاتیک](/guide/assets)

الگوهای اضافی [picomatch](https://github.com/micromatch/picomatch#globbing-features) را به عنوان دارایی‌های استاتیک مشخص می‌کند تا:

* هنگام ارجاع از HTML یا درخواست مستقیم از طریق `fetch` یا XHR، از خط لوله تبدیل پلاگین خارج شوند.

* ایمپورت آنها از جاوااسکریپت، رشته URL رزولوش‌شده آنها را برمی‌گرداند (اگر پلاگینی با `'enforce: 'pre` برای مدیریت نوع دارایی به طور متفاوت داشته باشید، این می‌تواند بازنویسی شود).

فهرست نوع دارایی‌های داخلی را می‌توان [اینجا](https://github.com/vitejs/vite/blob/main/packages/vite/src/node/constants.ts) یافت.

**مثال:**

```js
export default defineConfig({
  assetsInclude: ['**/*.gltf'],
})
```

## logLevel

* **تایپ:** `'info' | 'warn' | 'error' | 'silent'`

سطح جزئیات خروجی کنسول را تنظیم می‌کند. پیش‌فرض `'info'` است.

## customLogger

* **تایپ:**
  ```ts
  interface Logger {
    info(msg: string, options?: LogOptions): void
    warn(msg: string, options?: LogOptions): void
    warnOnce(msg: string, options?: LogOptions): void
    error(msg: string, options?: LogErrorOptions): void
    clearScreen(type: LogType): void
    hasErrorLogged(error: Error | RollupError): boolean
    hasWarned: boolean
  }
  ```

از یک logger سفارشی برای ثبت پیام‌ها استفاده کنید. می‌توانید از API `createLogger` در Vite استفاده کنید تا logger پیش‌فرض را بگیرید و آن را سفارشی کنید، مثلاً پیام را تغییر دهید یا هشدارهای خاصی را فیلتر کنید.

```ts twoslash
import { createLogger, defineConfig } from 'vite'

const logger = createLogger()
const loggerWarn = logger.warn

logger.warn = (msg, options) => {
  // خالی را نادیده بگیر CSS هشدار مربوط به فایل‌های
  if (msg.includes('vite:css') && msg.includes(' is empty')) return
  loggerWarn(msg, options)
}

export default defineConfig({
  customLogger: logger,
})
```

## clearScreen

* **تایپ:** `boolean`
* **پیش‌فرض:** `true`

برای جلوگیری از پاک کردن صفحه ترمینال توسط Vite هنگام ثبت برخی پیام‌ها، روی `false` تنظیم کنید. از طریق خط فرمان، از `clearScreen false--` استفاده کنید.

## envDir

* **تایپ:** `string | false`
* **پیش‌فرض:** `root`

پوشه‌ای که فایل‌های `env.` از آن بارگذاری می‌شوند. می‌تواند یک مسیر مطلق یا یک مسیر نسبت به ریشه پروژه باشد. اگر مقدار آن `false` باشد، بارگذاری فایل‌های `‎.env` غیرفعال می‌شود.

برای اطلاعات بیشتر در مورد فایل‌های محیطی، [اینجا](/guide/env-and-mode.html#فایل‌های-%E2%80%8E-env) را ببینید.

## envPrefix

* **تایپ:** `[]string | string`
* **پیش‌فرض:** `VITE_‎`

متغیرهای محیطی که با `envPrefix` شروع می‌شوند از طریق `import.meta.env` به کد منبع سمت کلاینت شما در دسترس خواهند بود.

::: warning نکات امنیتی
`envPrefix` نباید به صورت `''` تنظیم شود، زیرا این کار همه متغیرهای محیطی شما را در معرض دید قرار می‌دهد و ممکن است منجر به نشت غیرمنتظره اطلاعات حساس شود. Vite هنگام تشخیص `''` خطا می‌دهد.

اگر می‌خواهید یک متغیر بدون پیشوند را در معرض دید قرار دهید، می‌توانید از [define](#define) استفاده کنید:

```js
define: {
  'import.meta.env.ENV_VARIABLE': JSON.stringify(process.env.ENV_VARIABLE)
}
```

:::

## appType

* **تایپ:** `'spa' | 'mpa' | 'custom'`
* **پیش‌فرض:** `'spa'`

مشخص می‌کند که برنامه شما یک برنامه تک‌صفحه‌ای (SPA)، یک [برنامه چندصفحه‌ای (MPA)](../guide/build#multi-page-app) یا برنامه سفارشی (SSR و چارچوب‌هایی با مدیریت HTML سفارشی) است:

* `'spa'`: شامل میان‌افزارهای HTML و استفاده از بازگشت SPA. در پیش‌نمایش، [sirv](https://github.com/lukeed/sirv) را با `single: true` پیکربندی می‌کند.
* `'mpa'`: شامل میان‌افزارهای HTML.
* `'custom'`: شامل میان‌افزارهای HTML نمی‌شود.

برای اطلاعات بیشتر در راهنمای [SSR Vite](/guide/ssr#vite-cli) بخوانید. مرتبط: [`server.middlewareMode`](./server-options#server-middlewaremode).

## future

* **تایپ:** `<Record<string, 'warn' | undefined`
* **مرتبط:** [تغییرات ناسازگار](/changes/)

تغییرات ناسازگار آینده را فعال می‌کند تا برای مهاجرت روان به نسخه اصلی بعدی Vite آماده شوید. این فهرست ممکن است در هر زمان با توسعه ویژگی‌های جدید به‌روزرسانی، اضافه یا حذف شود.

برای جزئیات گزینه‌های ممکن، صفحه [تغییرات ناسازگار](/changes/) را ببینید.

---

---
url: /guide/env-and-mode.md
---
# متغیرهای محیطی (Env Variables) و حالت‌ها

Vite برخی ثابت‌ها (constants) را از آبجکت ویژه‌ی `import.meta.env` در دسترس قرار می‌دهد. این ثابت‌ها در زمان توسعه به‌صورت متغیرهای سراسری تعریف می‌شوند و هنگام ساخت (build)، مقدار آن‌ها مستقیماً در کد جایگذاری می‌شود. این کار باعث می‌شود که بخش‌های بلااستفاده‌ی کد به‌طور مؤثرتری توسط فرآیند tree-shaking حذف شوند.

## Built-in Constants

برخی از ثابت‌های داخلی در همه‌ی شرایط در دسترس هستند:

* **`import.meta.env.MODE`**: [حالت](#حالتها-modes) اجرای برنامه. (string)

* **`import.meta.env.BASE_URL`**: آدرس پایه‌ای (base url) که برنامه از آن سرویس‌دهی می‌شود. این مقدار توسط [`base` config option](/config/shared-options.md#base) تعیین می‌شود. (string)

* **`import.meta.env.PROD`**: مشخص می‌کند که آیا برنامه در حالت production در حال اجراست یا خیر. (این حالت زمانی فعال می‌شود که سرور توسعه با `NODE_ENV='production'‎` اجرا شود یا برنامه‌ای که با `NODE_ENV='production'‎` ساخته شده است، در حال اجرا باشد). (boolean)

* **`import.meta.env.DEV`**: مشخص می‌کند که آیا برنامه در حالت توسعه (development) اجرا می‌شود یا خیر (این مقدار همیشه برعکس `import.meta.env.PROD` است). (boolean)

* **`import.meta.env.SSR`**: مشخص می‌کند که آیا برنامه در [server](./ssr.md#conditional-logic) اجرا می‌شود یا خیر. (boolean)

## متغیرهای محیطی (Env Variables)

Vite به‌طور خودکار متغیرهای محیطی را از طریق آبجکت `import.meta.env` به‌صورت رشته‌ای در دسترس قرار می‌دهد.

برای جلوگیری از افشای تصادفی متغیرهای محیطی در سمت کلاینت، تنها متغیرهایی که با پیشوند `VITE_‎` شروع می‌شوند، در کد پردازش‌شده‌ی Vite قابل دسترسی خواهند بود. به‌عنوان مثال، در متغیرهای زیر:

```[.env]
VITE_SOME_KEY=123
DB_PASSWORD=foobar
```

تنها مقدار `VITE_SOME_KEY` در دسترس کد کلاینت قرار می‌گیرد و به‌صورت `import.meta.env.VITE_SOME_KEY` قابل استفاده خواهد بود، اما `DB_PASSWORD` در دسترس نخواهد بود.

```js
console.log(import.meta.env.VITE_SOME_KEY) // "123"
console.log(import.meta.env.DB_PASSWORD) // undefined
```

اگر می‌خواهید پیشوند متغیرهای محیطی را سفارشی کنید، به گزینه‌ی [`envPrefix`](/config/shared-options.html#envprefix) مراجعه کنید.

:::tip نحوه‌ی پردازش متغیرهای محیطی
همان‌طور که در مثال بالا مشاهده می‌شود، مقدار `VITE_SOME_KEY` یک عدد است، اما هنگام دریافت، به‌صورت رشته بازگردانده می‌شود. همین اتفاق برای متغیرهای بولی نیز رخ می‌دهد. بنابراین، هنگام استفاده از این مقادیر، آن‌ها را به تایپ داده موردنظر خود تبدیل کنید.
:::

## فایل‌های `‎.env`

Vite از [dotenv](https://github.com/motdotla/dotenv) برای بارگذاری متغیرهای محیطی (environment variables) اضافی از فایل‌های زیر در دایرکتوری محیط [environment directory](/config/shared-options.md#envdir) استفاده می‌کند:

```
.env                # در همه موارد بارگذاری می‌شود
.env.local          # نادیده گرفته می‌شود git در همه موارد بارگذاری می‌شود، اما توسط
.env.[mode]         # فقط در حالت مشخص‌شده بارگذاری می‌شود
.env.[mode].local   # نادیده گرفته می‌شود git فقط در حالت مشخص‌شده بارگذاری می‌شود و توسط
```

:::tip اولویت‌های بارگذاری فایل‌های Env

یک فایل env مربوط به حالت خاص (مثلاً `‎.env.production`) اولویت بالاتری نسبت به فایل‌های عمومی (مثلاً `‎.env`) خواهد داشت.

Vite همیشه فایل‌های `‎.env` و `‎.env.local` را علاوه بر فایل مخصوص هر حالت (مانند `‎.env.[mode]`) بارگذاری می‌کند. متغیرهایی که در فایل‌های مخصوص هر حالت تعریف شده‌اند، نسبت به متغیرهای موجود در فایل‌های عمومی اولویت دارند. با این حال، متغیرهایی که فقط در `‎.env` یا `‎.env.local` تعریف شده‌اند، همچنان در محیط (environment) در دسترس خواهند بود.

علاوه بر این، متغیرهای محیطی (environment variables) که از قبل در هنگام اجرای Vite وجود دارند، بالاترین اولویت را دارند و توسط فایل‌های `‎.env` بازنویسی نمی‌شوند. به عنوان مثال، هنگام اجرای دستوری مانند `VITE_SOME_KEY=123 vite build`.

فایل‌های `‎.env` در هنگام راه‌اندازی Vite بارگذاری می‌شوند. پس از ایجاد تغییرات، سرور را دوباره راه‌اندازی کنید.

:::

همچنین، Vite از [dotenv-expand](https://github.com/motdotla/dotenv-expand) برای گسترش متغیرهای نوشته‌شده در فایل‌های env به صورت پیش‌فرض استفاده می‌کند. برای یادگیری بیشتر درباره syntax این قابلیت، می‌توانید [مستندات آن‌ها](https://github.com/motdotla/dotenv-expand#what-rules-does-the-expansion-engine-follow) را بررسی کنید.

توجه کنید که اگر قصد دارید از `$` در مقدار متغیر محیطی خود استفاده کنید، باید آن را با `\` (بک‌اسلش) قرار دهید.

```[.env]
KEY=123
NEW_KEY1=test$foo   # test
NEW_KEY2=test\$foo  # test$foo
NEW_KEY3=test$KEY   # test123
```

:::warning نکات امنیتی

* فایل‌های `‎.env.*.local` فقط به صورت محلی (local-only) هستند و می‌توانند شامل متغیرهای حساس باشند. شما باید `‎*.local` را به فایل `‎.gitignore` خود اضافه کنید تا از ثبت آن‌ها در git جلوگیری شود.

* از آنجایی که هر متغیری که در سورس کد Vite شما قرار می‌گیرد، در نهایت به باندل (bundle) سمت کلاینت راه پیدا می‌کند، متغیرهای `VITE_*‎` *نباید* شامل هیچ اطلاعات حساسی باشند.

:::

::: details گسترش متغیرها به‌صورت معکوس

Vite از قابلیت گسترش متغیرها به‌صورت معکوس پشتیبانی می‌کند.
برای مثال، فایل `‎.env` زیر به‌صورت `VITE_FOO=foobar` و `VITE_BAR=bar` ارزیابی می‌شود:

```ini
VITE_FOO=foo${VITE_BAR}
VITE_BAR=bar
```

این ویژگی در اسکریپت‌های شِل و ابزارهایی مانند `docker-compose` کار نمی‌کند.
با این حال، Vite از این قابلیت پشتیبانی می‌کند، زیرا `dotenv-expand` مدت‌هاست که این رفتار را ارائه داده و برخی ابزارهای دیگر در اکوسیستم جاوا اسکریپت هنوز از نسخه‌های قدیمی‌تر پشتیبانی‌کننده‌ی این ویژگی استفاده می‌کنند.

برای جلوگیری از مشکلات ناسازگاری، توصیه می‌شود به این ویژگی وابسته نشوید. Vite ممکن است در آینده برای استفاده از این رفتار، هشدارهایی نمایش دهد.

:::

### IntelliSense برای TypeScript

به‌طور پیش‌فرض، Vite تعریف تایپ (Type Definitions) برای `import.meta.env` را در فایل `vite/client.d.ts` ارائه می‌دهد. در حالی که می‌توانید متغیرهای محیطی (environment variables) سفارشی‌تری را در فایل‌های `‎.env.[mode]` تعریف کنید، ممکن است بخواهید از قابلیت IntelliSense TypeScript برای متغیرهای env تعریف‌شده توسط کاربر که با پیشوند `VITE_‎` شروع می‌شوند، استفاده کنید.

برای این کار، می‌توانید یک فایل `vite-env.d.ts` در پوشه `src` ایجاد کرده و `ImportMetaEnv` را به شکل زیر توسعه دهید:

```typescript [vite-env.d.ts]
/// <reference types="vite/client" />

interface ViteTypeOptions {
  // کنید (strict) رو سخت‌گیرانه ImportMetaEnv با اضافه کردن این خط، می‌تونید تایپ
  // تا از استفاده کلیدهای ناشناس جلوگیری بشه
  // strictImportMetaEnv: unknown
}

interface ImportMetaEnv {
  readonly VITE_APP_TITLE: string
  // env بقیه متغیرهای
}

interface ImportMeta {
  readonly env: ImportMetaEnv
}
```

اگر کد شما به `types` مربوط به محیط‌های مرورگر مانند [DOM](https://github.com/microsoft/TypeScript/blob/main/src/lib/dom.generated.d.ts) و [WebWorker](https://github.com/microsoft/TypeScript/blob/main/src/lib/webworker.generated.d.ts) وابسته است، می‌توانید فیلد [`lib`](https://www.typescriptlang.org/tsconfig#lib) را در `tsconfig.json` به‌روزرسانی کنید.

```json [tsconfig.json]
{
  "lib": ["WebWorker"]
}
```

:::warning ایمپورت‌ها باعث خرابی type augmentation می‌شوند

اگر گسترش (augmentation) `ImportMetaEnv` کار نکرد، مطمئن شوید که هیچ عبارت import در فایل `vite-env.d.ts` ندارید. برای اطلاعات بیشتر، به [مستندات TypeScript](https://www.typescriptlang.org/docs/handbook/2/modules.html#how-javascript-modules-are-defined) مراجعه کنید.

:::

## جایگذاری ثابت‌ها در HTML

Vite همچنین از جایگذاری ثابت‌ها در فایل‌های HTML پشتیبانی می‌کند. هر ویژگی از `import.meta.env` را می‌توان با استفاده از سینتکس ویژه `%CONST_NAME%` در فایل‌های HTML استفاده کرد:

```html
<h1>Vite is running in %MODE%</h1>
<p>Using data from %VITE_API_URL%</p>
```

اگر متغیر محیطی (env) در `import.meta.env` وجود نداشته باشد، مثلاً `%NON_EXISTENT%`، نادیده گرفته می‌شود و جایگزین نمی‌شود. این رفتار برخلاف `import.meta.env.NON_EXISTENT` در جاوااسکریپت است که در آن، مقدار به‌عنوان `undefined` جایگزین می‌شود.

با توجه به اینکه Vite توسط بسیاری از فریم‌ورک‌ها استفاده می‌شود، به‌طور عمدی در مورد جایگزینی‌های پیچیده‌ای مانند شرط‌ها (conditionals) نظر خاصی ندارد. Vite را می‌توان با استفاده از [یک پلاگین موجود از کاربران](https://github.com/vitejs/awesome-vite#transformers) یا یک پلاگین سفارشی که از هوک [`transformIndexHtml`](./api-plugin#transformindexhtml) استفاده می‌کند، گسترش داد.

## حالت‌ها (Modes)

به طور پیش‌فرض، سرور توسعه (`dev` command) در حالت `development` اجرا می‌شود و دستور `build` در حالت `production` اجرا می‌شود.

این بدان معناست که هنگام اجرای `vite build`، متغیرهای env از فایل `‎.env.production` بارگذاری می‌شوند (اگر چنین فایلی وجود داشته باشد):

```[.env.production]
VITE_APP_TITLE=My App
```

در برنامه‌تان می‌توانید title را با استفاده از `import.meta.env.VITE_APP_TITLE` نمایش دهید.

در برخی موارد، ممکن است بخواهید دستور `vite build` را با حالت (mode) متفاوتی اجرا کنید تا title متفاوتی نمایش داده شود. می‌توانید حالت پیش‌فرض مورد استفاده برای یک دستور را با استفاده از فلگ `‎--mode` تغییر دهید. به‌عنوان مثال، اگر می‌خواهید برنامه‌تان را برای حالت استیجینگ (staging) بسازید:

```bash
vite build --mode staging
```

و یک فایل `‎.env.staging` ایجاد کنید:

```[.env.staging]
VITE_APP_TITLE=My App (staging)
```

از آن‌جایی که `vite build` به‌طور پیش‌فرض یک build مربوط به محیط production اجرا می‌کند، می‌توانید این رفتار را تغییر داده و با استفاده از یک mode متفاوت و پیکربندی فایل `.env`، یک build مربوط به محیط development اجرا کنید:

```[.env.testing]
NODE_ENV=development
```

### `NODE_ENV` و Mode ها

مهم است توجه داشته باشید که `NODE_ENV` (`process.env.NODE_ENV`) و mode ها دو مفهوم متفاوت هستند. در اینجا نحوه تأثیر دستورات مختلف بر `NODE_ENV` و mode آورده شده است:

| Command                                              | NODE\_ENV        | Mode            |
| ---------------------------------------------------- | --------------- | --------------- |
| `vite build`                                         | `"production"`  | `"production"`  |
| `vite build --mode development`                      | `"production"`  | `"development"` |
| `NODE_ENV=development vite build`                    | `"development"` | `"production"`  |
| `NODE_ENV=development vite build --mode development` | `"development"` | `"development"` |

مقادیر مختلف `NODE_ENV` و mode همچنین در ویژگی‌های مربوط به `import.meta.env` منعکس می‌شوند:

| Command                | `import.meta.env.PROD` | `import.meta.env.DEV` |
| ---------------------- | ---------------------- | --------------------- |
| `NODE_ENV=production`  | `true`                 | `false`               |
| `NODE_ENV=development` | `false`                | `true`                |
| `NODE_ENV=other`       | `false`                | `true`                |

| Command              | `import.meta.env.MODE` |
| -------------------- | ---------------------- |
| `--mode production`  | `"production"`         |
| `--mode development` | `"development"`        |
| `--mode staging`     | `"staging"`            |

:::tip `NODE_ENV` در فایل‌های `‎.env`

`NODE_ENV=...‎` را می‌توان هم در دستور و هم در فایل `‎.env` تنظیم کرد. اگر `NODE_ENV` در یک فایل `‎.env.[mode]` مشخص شده باشد، می‌توان از mode برای کنترل مقدار آن استفاده کرد. با این حال، هر دو `NODE_ENV` و modes همچنان به‌عنوان دو مفهوم مجزا باقی می‌مانند.

مزیت اصلی استفاده از `NODE_ENV=...‎` در دستور این است که به Vite اجازه می‌دهد مقدار را زودتر تشخیص دهد. همچنین به شما امکان می‌دهد `process.env.NODE_ENV` را در تنظیمات Vite خود بخوانید، زیرا Vite فقط می‌تواند فایل‌های env را پس از ارزیابی تنظیمات بارگیری کند.
:::

---

---
url: /guide/assets.md
---
# مدیریت asset های استاتیک

* مرتبط: [مسیر پایه عمومی (public base path)](./build#public-base-path)
* مرتبط: [`assetsInclude` آپشن کانفیگ](/config/shared-options.md#assetsinclude)

## ایمپورت کردن asset ها به عنوان URL

ایمپورت کردن assetها یک URL عمومی را بعد از سرو شدن برمی‌گرداند:

```js twoslash
import 'vite/client'
// ---cut---
import imgUrl from './img.png'
document.getElementById('hero-img').src = imgUrl
```

برای مثال `imgUrl` هنگام توسعه ‎`/src/img.png` و بعد از بیلد پروداکشن تبدیل به‎`/assets/img.2d8efhg.png` می‌شود.

این رفتار مشابه `file-loader` در وب‌پک است. تفاوت اینجاست که فایل ایمپورت شده می‌تواند از آدرس‌های عمومی مطلق(absolute public paths) (بر اساس روت پروژه در هنگام توسعه) یا آدرس با مسیرهای نسبی (relative paths) باشد.

* رفرنس‌های `url()`‎ در CSS هم به همین روش کار می‌کنند.

* اگر از پلاگین Vue استفاده شود، رفرنس‌های فایل‌ها در تمپلیت‌های کامپوننت‌های تک فایلی ویو (Vue SFC) خودبخود تبدیل به ایمپورت می‌شوند.

* فرمت‌های رایج فایل‌های تصویری، مدیاها و فونت‌ها به صورت خودکار به عنوان asset شناسایی می‌شوند. شما میتوانید این لیست داخلی را با [گزینه `assetsInclude`](/config/shared-options.md#assetsinclude) گسترش دهید.

* asset های رفرنس داده شده به عنوان بخشی از گراف asset های بیلد گنجانده می‌شوند، نام فایل‌های هش شده را می‌گیرند و می‌توانند برای بهینه‌سازی توسط پلاگین‌ها مورد استفاده قرار گیرند.

* asset هایی که اندازه‌شان کمتر از مقدار تعیین شده‌ی [گزینه`assetsInlineLimit`](/config/build-options.md#build-assetsinlinelimit) باشد به شکل URL های دیتای base64 درون‌خطی(inline) خواهند شد.

* placeholder های Git LFS به طور خودکار از درون‌خطی شدن (inlining) مستثنی می‌شوند چرا که دارای محتوای فایلی که نمایش می‌دهند نیستند. برای inline کردن آنها، مطمئن شوید که محتواهای فایل را از Git LFS قبل از بیلد کردن دانلود کرده باشید.

* تایپ‌اسکریپت، به صورت پیشفرض، ایمپورت‌های asset های استاتیک را به عنوان یک ماژول معتبر تشخیص نمی‌دهد. برای برطرف کردن این موضوع، [`vite/client`](./features#client-types) را اضافه کنید.

::: tip Inline کردن SVGها از طریق `url()`‎
زمانی که URL یک فایل SVG را به متد `url()`‎ که به صورت دستی ساخته شده(manually constructed) با JS پاس می‌دهیم، متغیر باید داخل دبل کوت قرار گیرد.

```js twoslash
import 'vite/client'
// ---cut---
import imgUrl from './img.svg'
document.getElementById('hero-img').style.background = `url("${imgUrl}")`
```

:::

### ایمپورت URL های مشخص

asset هایی که در لیست داخلی یا `assetsInclude` قرار ندارند، می‌توانند با پسوند ‎`?url` به صراحت(explicitly) به عنوان URL ایمپورت شوند.این مورد کاربردی است، مثلا برای ایمپورت کردن [Houdini Paint Worklets](https://houdini.how/usage).

```js twoslash
import 'vite/client'
// ---cut---
import workletURL from 'extra-scalloped-border/worklet.js?url'
CSS.paintWorklet.addModule(workletURL)
```

### مدیریت inline مشخص (Explicit Inline)

asset ها می‌توانند به شکل مشخص(explicit) با inline کردن یا بدون آن ایمپورت شوند این کار به ترتیب با پسوند ‎`?inline` یا ‎`?no-inline` انجام می‌شود.

```js twoslash
import 'vite/client'
// ---cut---
import imgUrl1 from './img.svg?no-inline'
import imgUrl2 from './img.png?inline'
```

### ایمپورت‌ کردن asset ها به شکل رشته (string)

asset ها می‌توانند به شکل رشته با استفاده از پسوند ‎`?raw` ایمپورت شوند.

```js twoslash
import 'vite/client'
// ---cut---
import shaderString from './shader.glsl?raw'
```

### ایمپورت کردن Script به عنوان یک Worker

اسکریپت‌ها می‌توانند به عنوان یک web worker با پسوند ‎`?worker` یا ‎`?sharedworker` ایمپورت شوند.

```js twoslash
import 'vite/client'
// ---cut---
// جداگانه در بیلد chunk
import Worker from './shader.js?worker'
const worker = new Worker()
```

```js twoslash
import 'vite/client'
// ---cut---
// ورکر اشتراکی
import SharedWorker from './shader.js?sharedworker'
const sharedWorker = new SharedWorker()
```

```js twoslash
import 'vite/client'
// ---cut---
// inline کردن به شکل رشته‌های ‎base64
import InlineWorker from './shader.js?worker&inline'
```

برای جزییات بیشتر به [بخش Web Worker](./features.md#web-workers) سر بزنید.

## دایرکتوری `public`

اگر asset هایی دارید که:

* هرگز در سورس کد به آنها رفرنس داده نشده است. (مانند `robots.txt`)
* باید نام فایل آنها دست نخورده باقی بماند (بدون هش کردن)
* یا نمی‌خواهید که حتما مجبور باشید برای دریافت URL یک asset، ابتدا آنرا ایمپورت کنید

پس می‌توانید آن asset را در دایرکتوری مخصوص `public` درون فایل روت پروژه قرار دهید. asset های داخل این دایرکتوری در حالت dev در آدرس(path) اصلی `/` سرو می‌شوند و به همان شکلی که هستند در دایرکتوری روت در dist کپی می‌شوند.

دایرکتوری به شکل پیش‌فرض ‎`<root>/public` است، اما از طریق [گزینه `publicDir`](/config/shared-options.md#publicdir) می‌تواند کانفیگ شود.

به یاد داشته باشید که شما همیشه می‌توانید asset های `public` را با آدرس‌دهی مطلق(absolute path) رفرنس دهید، برای مثال فایل `public/icon.png` باید به شکل ‎ `/icon.png` در سورس کد رفرنس داده شود.

## new URL(url, import.meta.url)

[import.meta.url](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import.meta) یک قابلیت نیتیو ESM است که URL ماژول فعلی را به ما می‌دهد. ترکیب آن با [URL constructor](https://developer.mozilla.org/en-US/docs/Web/API/URL) آدرس کامل یک asset ثابت را با استفاده از آدرس‌دهی نسبی از یک ماژول JS می‌دهد:

```js
const imgUrl = new URL('./img.png', import.meta.url).href

document.getElementById('hero-img').src = imgUrl
```

این کد به صورت نیتیو در مرورگرهای مدرن کار می‌کند؛ در واقع اصلا نیازی نیست که Vite پردازشی روی این کد در حالت توسعه انجام دهد!

همچنین این پترن URLهای داینامیک را نیز از طریق template literalها ساپورت می‌کند:

```js
function getImageUrl(name) {
  // توجه داشته باشید که این، ساب‌دایرکتوری‌ها را شامل نمی‌شود
  return new URL(`./dir/${name}.png`, import.meta.url).href
}
```

در زمان بیلد، Vite تغییرات لازم را اعمال خواهد که URLها همچنان حتی بعد از باندل‌کردن و هش‌کردن assetها به مکان درستی اشاره کنند. گرچه ‌رشته‌ی URL باید ثابت باشد تا بتواند آنالیز شود و در غیر این صورت کد به همان شکلی که بود باقی می‌ماند که این موضوع می‌تواند باعث ارورهای runtime شود اگر `build.target` عبارت `import.meta.url` را ساپورت نکند.

```js
// این کد را تغییر نمی‌دهد vite
const imgUrl = new URL(imagePath, import.meta.url).href
```

::: details چگونه کار می‌کند

Vite متد `getImageUrl` را تغییر می‌دهد به:

```js
import __img0png from './dir/img0.png'
import __img1png from './dir/img1.png'

function getImageUrl(name) {
  const modules = {
    './dir/img0.png': __img0png,
    './dir/img1.png': __img1png,
  }
  return new URL(modules[`./dir/${name}.png`], import.meta.url).href
}
```

:::

::: warning با SSR کار نمی‌کند
این پترن اگر که شما Vite را برای رندر سمت سرور(server-side rendering) استفاده می‌کنید کار نمی‌کند چرا که `import.meta.url` معانی متفاوتی در مرورگرها در مقابل Node.js دارد. سرور باندل(server bundle) نیز نمی‌تواند URL میزبان کلاینت(client host URL) را در لحظه تشخیص دهد.
:::

---

---
url: /guide/migration.md
---
# مهاجرت از نسخه ۶

## پشتیبانی Node.js

Vite دیگر از Node.js نسخه ۱۸ پشتیبانی نمی‌کند، چرا که به پایان عمر خود (EOL) رسیده است. از این پس حداقل به Node.js نسخه 20.19+ یا 22.12+ نیاز دارید.

## تغییر Target مرورگر پیش‌فرض

مقدار پیش‌فرض `build.target` برای مرورگرها به نسخه‌های جدیدتر به‌روزرسانی شده است:

* Chrome: از 87 → 107
* Edge: از 88 → 107
* Firefox: از 78 → 104
* Safari: از 14.0 → 16.0

این نسخه‌های مرورگر مطابق با مجموعه قابلیت‌های «به طور گسترده در دسترس» در [Baseline](https://web-platform-dx.github.io/web-features/) هستند (تا تاریخ ۱ مه ۲۰۲۵). به عبارت دیگر، همه این نسخه‌ها پیش از ۱ نوامبر ۲۰۲۲ منتشر شده‌اند.

در Vite نسخه ۵، مقدار پیش‌فرض `'modules'` بود، که اکنون دیگر پشتیبانی نمی‌شود. به جای آن، مقدار جدید `'baseline-widely-available'` به عنوان پیش‌فرض معرفی شده است.

## تغییرات عمومی

### حذف پشتیبانی از API قدیمی Sass

پشتیبانی از API قدیمی Sass طبق برنامه‌ریزی قبلی حذف شده است. Vite اکنون فقط از API مدرن Sass پشتیبانی می‌کند. می‌توانید گزینه‌های `css.preprocessorOptions.sass.api` و `css.preprocessorOptions.scss.api` را از تنظیمات خود حذف کنید.

## حذف ویژگی‌های منقضی‌شده

* `splitVendorChunkPlugin` (از نسخه 5.2.7 منقضی شده بود)
  * این پلاگین برای ساده‌تر کردن مهاجرت به Vite 2.9 معرفی شده بود.
  * اکنون می‌توان از گزینه `build.rollupOptions.output.manualChunks` برای کنترل چانک‌ها استفاده کرد.
* `enforce` / `transform` در سطح هوک برای `transformIndexHtml` (در نسخه 4.0.0 منقضی شده بود)
  * ساختار آن به سبک [هوک‌های آبجکت در Rollup](https://rollupjs.org/plugin-development/#build-hooks:~:text=Instead%20of%20a%20function%2C%20hooks%20can%20also%20be%20objects.) تغییر کرد.
  * اکنون باید به جای `enforce` از `order` و به جای `transform` از `handler` استفاده شود.

## پیشرفته

تغییرات ناسازگار دیگری نیز وجود دارند که فقط تعداد کمی از کاربران را تحت تأثیر قرار می‌دهند:

* [‎\[#19979\] chore: declare version range for peer dependencies](https://github.com/vitejs/vite/pull/19979)
  * محدوده نسخه‌ی وابستگی‌های هم‌سطح (peer dependencies) برای پیش‌پردازنده‌های CSS مشخص شده است.
* [‎\[#20013\] refactor: remove no-op `legacy.proxySsrExternalModules`](https://github.com/vitejs/vite/pull/20013)
  * ویژگی `legacy.proxySsrExternalModules` از نسخه ۶ به بعد در Vite هیچ تأثیری نداشت. اکنون این ویژگی به طور کامل حذف شده است.
* [‎\[#19985\] refactor!: remove deprecated no-op type only properties](https://github.com/vitejs/vite/pull/19985)
  * ویژگی‌های بدون استفاده زیر اکنون حذف شده‌اند: `ModuleRunnerOptions.root`, `ViteDevServer._importGlobMap`, `ResolvePluginOptions.isFromTsImporter`, `ResolvePluginOptions.getDepsOptimizer`, `ResolvePluginOptions.shouldExternalize`, `ResolvePluginOptions.ssrConfig`
* [‎\[#19986\] refactor: remove deprecated env api properties](https://github.com/vitejs/vite/pull/19986)
  * این ویژگی‌ها از ابتدا منقضی (deprecated) شده بودند و اکنون به‌طور کامل حذف شده‌اند.
* [‎\[#19987\] refactor!: remove deprecated `HotBroadcaster` related types](https://github.com/vitejs/vite/pull/19987)
  * این تایپ‌ها به‌عنوان بخشی از API رانتایم که اکنون منقضی شده، معرفی شده بودند. این تایپ‌ها اکنون به‌طور کامل حذف شده‌اند: `HMRBroadcaster`, `HMRBroadcasterClient`, `ServerHMRChannel`, `HMRChannel`
* [‎\[#19996\] fix(ssr)!: don't access `Object` variable in ssr transformed code](https://github.com/vitejs/vite/pull/19996)
  * اکنون مقدار `__vite_ssr_exportName__` برای context رانتایم ماژول الزامی شده است.
* [‎\[#20045\] fix: treat all `optimizeDeps.entries` values as globs](https://github.com/vitejs/vite/pull/20045)
  * `optimizeDeps.entries` اکنون دیگر مسیرهای رشته‌ای (literal string paths) را نمی‌پذیرد. در عوض، همیشه باید به‌صورت glob ارائه شود.
* [‎\[#20222\] feat: apply some middlewares before `configureServer` hook](https://github.com/vitejs/vite/pull/20222), [\[#20224\] feat: apply some middlewares before `configurePreviewServer` hook](https://github.com/vitejs/vite/pull/20224)
  * برخی از میان‌افزارها اکنون پیش از اجرای هوک‌های `configureServer` و `configurePreviewServer` اعمال می‌شوند. توجه داشته باشید: اگر انتظار ندارید که یک مسیر خاص از گزینه‌های [`server.cors`](../config/server-options.md#server-cors) یا [`preview.cors`](../config/preview-options.md#preview-cors) تأثیر بگیرد، حتماً هدرهای مرتبط را به‌صورت دستی از پاسخ حذف کنید.

## مهاجرت از نسخه ۵

ابتدا راهنمای [مهاجرت از نسخه ۵](https://v6.vite.dev/guide/migration.html) را در مستندات Vite نسخه ۶ بخوانید تا برنامه‌تان را به Vite ۶ منتقل کنید، سپس تغییرات گفته‌شده در این صفحه را اعمال نمایید.

---

---
url: /changes/hotupdate-hook.md
---
# هوک پلاگین `hotUpdate` برای HMR

::: tip بازخورد
به ما در [Environment API feedback discussion](https://github.com/vitejs/vite/discussions/16358) بازخورد دهید
:::

ما قصد داریم هوک پلاگین `handleHotUpdate` را به نفع [هوک `hotUpdate`](/guide/api-environment#the-hotupdate-hook) منسوخ کنیم تا با [API محیطی](/guide/api-environment.md) هماهنگ شود و رویدادهای  اضافی نظلرت (watch events) را با create و delete مدیریت کند.

دامنه تاثیر: `نویسندگان پلاگین Vite`

::: warning منسوخ‌شدن در آینده
هوک `hotUpdate` اولین بار در نسخه `v6.0` معرفی شد. منسوخ شدن `handleHotUpdate` برای یکی از نسخه‌های اصلی (major) آینده برنامه‌ریزی شده است. هنوز توصیه نمی‌کنیم که از `handleHotUpdate` استفاده نکنید. اگر می‌خواهید آزمایش کنید و بازخورد بدهید، می‌توانید در تنظیمات Vite خود `future.removePluginHookHandleHotUpdate` را به مقدار `"warn"` تنظیم کنید.
:::

## انگیزه

[هوک `handleHotUpdate`](/guide/api-plugin.md#handlehotupdate) به شما این امکان را می‌دهد که به‌طور سفارشی به‌روزرسانی‌های HMR را مدیریت کنید. یک لیست از ماژول‌هایی که باید به‌روزرسانی شوند در `HmrContext` ارسال می‌شود.

```ts
interface HmrContext {
  file: string
  timestamp: number
  modules: Array<ModuleNode>
  read: () => string | Promise<string>
  server: ViteDevServer
}
```

این هوک یک‌بار برای تمامی محیط‌ها فراخوانی می‌شود و ماژول‌های ارسال‌شده اطلاعات ترکیبی از محیط‌های Client و SSR دارند. زمانی که فریم‌ورک‌ها به محیط‌های سفارشی منتقل شوند، به هوک جدیدی نیاز است که برای هر یک از این محیط‌ها فراخوانی شود.

هوک جدید `hotUpdate` به همان روش `handleHotUpdate` کار می‌کند، اما برای هر محیط به‌طور جداگانه فراخوانی می‌شود و یک نمونه جدید از `HotUpdateOptions` دریافت می‌کند.

```ts
interface HotUpdateOptions {
  type: 'create' | 'update' | 'delete'
  file: string
  timestamp: number
  modules: Array<EnvironmentModuleNode>
  read: () => string | Promise<string>
  server: ViteDevServer
}
```

محیط توسعه کنونی مانند سایر هوک‌های پلاگین با استفاده از `this.environment` قابل دسترسی است. لیست `modules` اکنون تنها شامل گره‌های ماژول از محیط جاری خواهد بود. هر به‌روزرسانی محیط می‌تواند استراتژی‌های به‌روزرسانی مختلفی را تعریف کند.

این هوک اکنون برای رویدادهای اضافی نظارت (watch events) نیز فراخوانی می‌شود و تنها مختص `'update'` نیست. برای تمایز بین آن‌ها از `type` استفاده کنید.

## راهنمای مهاجرت

برای دقت بیشتر در HMR، لیست ماژول‌های تحت تاثیر را فیلتر کرده و محدود کنید.

```js
handleHotUpdate({ modules }) {
  return modules.filter(condition)
}

// مهاجرت کنید به:

hotUpdate({ modules }) {
  return modules.filter(condition)
}
```

یک آرایه خالی برگردانید و بارگذاری کامل را انجام دهید:

```js
handleHotUpdate({ server, modules, timestamp }) {
  // ماژول‌ها را به‌صورت دستی غیرفعال کنید
  const invalidatedModules = new Set()
  for (const mod of modules) {
    server.moduleGraph.invalidateModule(
      mod,
      invalidatedModules,
      timestamp,
      true
    )
  }
  server.ws.send({ type: 'full-reload' })
  return []
}

// مهاجرت کنید به:

hotUpdate({ modules, timestamp }) {
  // ماژول‌ها را به‌صورت دستی غیرفعال کنید
  const invalidatedModules = new Set()
  for (const mod of modules) {
    this.environment.moduleGraph.invalidateModule(
      mod,
      invalidatedModules,
      timestamp,
      true
    )
  }
  this.environment.hot.send({ type: 'full-reload' })
  return []
}
```

یک آرایه خالی برگردانید و مدیریت کامل HMR سفارشی را با ارسال رویدادهای سفارشی به کلاینت انجام دهید:

```js
handleHotUpdate({ server }) {
  server.ws.send({
    type: 'custom',
    event: 'special-update',
    data: {}
  })
  return []
}

// مهاجرت کنید به:

hotUpdate() {
  this.environment.hot.send({
    type: 'custom',
    event: 'special-update',
    data: {}
  })
  return []
}
```

---

---
url: /guide/features.md
---
# ویژگی‌ها

در ابتدایی‌ترین سطح، توسعه با Vite تفاوت زیادی با استفاده از یک سرور فایل استاتیک ندارد. اما Vite امکانات بیشتری فراتر از ایمپورت ESM بومی ارائه می‌دهد تا از ویژگی‌های مختلفی که معمولاً در راه‌اندازی مبتنی بر باندلر دیده می‌شوند، پشتیبانی کند.

## حل وابستگی‌های npm و پیش‌باندل کردن

ایمپورت ES بومی از ایمپورت ماژول‌های بدون مسیر مشخص مانند نمونه زیر پشتیبانی نمی‌کند:

```js
import { someMethod } from 'my-dep'
```

کد بالا در مرورگر خطا ایجاد می‌کند. Vite ایمپورت ماژول‌های بدون مسیر مانند این را در تمامی فایل‌های منبع شناسایی کرده و اقدامات زیر را انجام می‌دهد:

1. **[پیش‌باندل](./dep-pre-bundling):** این فرآیند سرعت بارگذاری صفحه را بهبود می‌بخشد و ماژول‌های CommonJS/UMD را به ESM تبدیل می‌کند. مرحله پیش‌باندل (پیش بسته‌بندی) با استفاده از ابزار [esbuild](http://esbuild.github.io/) انجام می‌شود که زمان  زمان راه‌اندازی اولیه (cold start) ابزار Vite را به طور قابل توجهی سریع‌تر از هر باندلر جاوااسکریپتی دیگر می‌کند.

2. بازنویسی ایمپورت‌ها به آدرس‌های معتبر مانند `‎/node_modules/.vite/deps/my-dep.js?v=f3sf2ebd` تا مرورگر بتواند آنها را به درستی ایمپورت کند.

**وابستگی‌ها به‌شدت در کش ذخیره می‌شوند**

Vite درخواست‌های مربوط به وابستگی‌ها را از طریق هدرهای HTTP کش می‌کند، بنابراین اگر بخواهید یک وابستگی را به‌صورت محلی ویرایش یا دیباگ کنید، مراحل ذکر شده [اینجا](./dep-pre-bundling#browser-cache) را دنبال کنید.

## جایگزینی سریع ماژول (Hot Module Replacement)

Vite یک **[API جایگزینی سریع ماژول (HMR)](./api-hmr)** بر پایه ESM بومی ارائه می‌دهد. فریمورک‌هایی که از قابلیت HMR پشتیبانی می‌کنند، می‌توانند از این API استفاده کنند تا به‌روزرسانی‌های فوری و دقیق را بدون نیاز به بارگذاری مجدد صفحه یا از دست رفتن وضعیت برنامه ارائه دهند. Vite یکپارچه‌سازی‌های HMR اختصاصی برای **[کامپوننت‌های تک‌فایلی Vue](https://github.com/vitejs/vite-plugin-vue/tree/main/packages/plugin-vue)** و **[React Fast Refresh](https://github.com/vitejs/vite-plugin-react/tree/main/packages/plugin-react)** فراهم می‌کند. همچنین یکپارچه‌سازی‌های رسمی برای **Preact** از طریق **[‎@prefresh/vite](https://github.com/JoviDeCroock/prefresh/tree/main/packages/vite)** وجود دارد.

توجه داشته باشید که نیازی به تنظیم دستی این موارد ندارید. زمانی که یک برنامه را از طریق **[`create-vite`](./)** ایجاد می‌کنید، قالب‌های انتخابی این تنظیمات را از پیش برای شما پیکربندی کرده‌اند.

## تایپ‌اسکریپت

Vite به‌طور پیش‌فرض از ایمپورت کردن فایل‌های `‎.ts` پشتیبانی می‌کند.

### فقط تبدیل (Transpile Only)

توجه داشته باشید که Vite تنها عملیات **تبدیل (transpilation)** را روی فایل‌های `‎.ts` انجام می‌دهد و **هیچ‌گونه بررسی تایپ (type checking)** انجام نمی‌دهد. این ابزار فرض می‌کند که بررسی تایپ توسط IDE یا فرآیند ساخت شما مدیریت می‌شود.

دلیل اینکه Vite بررسی تایپ را به‌عنوان بخشی از فرآیند تبدیل انجام نمی‌دهد این است که این دو وظیفه به‌صورت بنیادی متفاوت عمل می‌کنند. تبدیل (Transpilation) می‌تواند به‌صورت مستقل برای هر فایل انجام شود و کاملاً با مدل کامپایل در لحظه Vite هماهنگ است. در مقایسه، بررسی تایپ به اطلاعات کامل از کل گراف ماژول نیاز دارد. گنجاندن بررسی تایپ در مراحل تبدیل Vite به‌ناچار مزایای سرعتی آن را کاهش می‌دهد.

وظیفه Vite این است که ماژول‌های منبع شما را به شکلی درآورد که بتوانند در سریع‌ترین زمان ممکن در مرورگر اجرا شوند. به همین منظور، پیشنهاد می‌شود که بررسی‌های تحلیلی استاتیک (مثل ESLint و موارد مشابه) را از مراحل تبدیل Vite جدا کنید.

* برای بیلد‌های پروداکش، می‌توانید دستور `tsc --noEmit` را علاوه بر دستور بیلد Vite اجرا کنید.

* در طول توسعه، اگر به اطلاعات بیشتری فراتر از پیشنهادات IDE نیاز دارید، پیشنهاد می‌شود که دستور `tsc --noEmit --watch` را در یک فرآیند جداگانه اجرا کنید، یا اگر ترجیح می‌دهید که خطاهای تایپ مستقیماً در مرورگر گزارش شوند، از [vite-plugin-checker](https://github.com/fi3ework/vite-plugin-checker) استفاده کنید.

Vite از [esbuild](https://github.com/evanw/esbuild) برای تبدیل تایپ‌اسکریپت به جاوااسکریپت استفاده می‌کند که حدود ۲۰ تا ۳۰ برابر سریع‌تر از `tsc` معمولی است و به‌روزرسانی‌های HMR می‌توانند در کمتر از ۵۰ میلی‌ثانیه در مرورگر منعکس شوند.

برای جلوگیری از مشکلات احتمالی مانند باندل نادرست ایمپورت فقط تایپ (type-only imports)، از سینتکس [Type-Only Imports and Export](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-8.html#type-only-imports-and-export) استفاده کنید. به‌عنوان مثال:

```ts
import type { T } from 'only/types'
export type { T }
```

### گزینه‌های کامپایلر TypeScript

برخی از فیلدهای پیکربندی در `compilerOptions` در فایل `tsconfig.json` نیاز به توجه ویژه دارند.

#### `isolatedModules`

* [مستندات TypeScript](https://www.typescriptlang.org/tsconfig#isolatedModules)

باید به `true` تنظیم شود.

به این دلیل که `esbuild` ترنسپایل را بدون اطلاع از تایپ‌ها انجام می‌دهد و از ویژگی‌هایی مانند const enum و ایمپورت تایپ ضمنی پشتیبانی نمی‌کند.

باید `‎"isolatedModules": true` را در `tsconfig.json` زیر `compilerOptions` تنظیم کنید تا TypeScript به شما در مورد ویژگی‌هایی که با ترنسپایل ایزوله کار نمی‌کنند، هشدار دهد.

اگر یک وابستگی با `‎"isolatedModules": true` به خوبی کار نمی‌کند، می‌توانید از `‎"skipLibCheck": true` استفاده کنید تا به طور موقت خطاها را تا زمانی که در بالادست رفع شوند، نادیده بگیرید.

#### `useDefineForClassFields`

* [مستندات TypeScript](https://www.typescriptlang.org/tsconfig#useDefineForClassFields)

مقدار پیش‌فرض این گزینه زمانی برابر با `true` خواهد بود که target در تایپ‌اسکریپت روی `ES2022` یا نسخه‌های جدیدتر از جمله `ESNext` تنظیم شده باشد. این رفتار با عملکرد [TypeScript نسخه 4.3.2 به بعد](https://github.com/microsoft/TypeScript/pull/42663) هماهنگ است.
سایر target ها در تایپ‌اسکریپت به طور پیش‌فرض `false` خواهند بود.

`true` مطابق با استاندارد رانتایم ECMAScript است.

اگر از کتابخانه‌ای استفاده می‌کنید که به شدت به فیلدهای کلاس وابسته است، لطفاً مطمئن شوید که کتابخانه با تنظیمات شما سازگار است.
در حالی که بیشتر کتابخانه‌ها انتظار دارند که `‎"useDefineForClassFields": true` باشد، اگر کتابخانه شما از این ویژگی پشتیبانی نمی‌کند، می‌توانید به صراحت `useDefineForClassFields` را به `false` تنظیم کنید.

#### `target`

* [مستندات TypeScript](https://www.typescriptlang.org/tsconfig#target)

Vite مقدار `target` در `tsconfig.json` را نادیده می‌گیرد و از همان تنظیمات `esbuild` پیروی می‌کند.

برای مشخص کردن target در حالت توسعه، می‌توانید از گزینه [`esbuild.target`](/config/shared-options.html#esbuild) استفاده کنید که به طور پیش‌فرض `esnext` برای کمترین ترنسپایل تنظیم شده است. در بیلد، گزینه [`build.target`](/config/build-options.html#build-target) اولویت بالاتری نسبت به `esbuild.target` دارد و در صورت نیاز می‌توانید آن را تنظیم کنید.

::: warning `useDefineForClassFields`

اگر `target` در `tsconfig.json` برابر با `ESNext` یا `ES2022` یا جدیدتر نباشد، یا اگر فایل `tsconfig.json` وجود نداشته باشد، مقدار پیش‌فرض `useDefineForClassFields` برابر با `false` خواهد بود که ممکن است با مقدار پیش‌فرض `esbuild.target` یعنی `esnext` مشکل‌ساز شود. این ممکن است به [static initialization blocks](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes/Static_initialization_blocks#browser_compatibility) ترنسپایل شود که ممکن است مرورگر شما از آن‌ها پشتیبانی نکند.

بنابراین، توصیه می‌شود که `target` را به `ESNext` یا `ES2022` یا جدیدتر تنظیم کنید، یا `useDefineForClassFields` را به صراحت در `tsconfig.json` به `true` تنظیم کنید.
:::

#### سایر گزینه‌های کامپایلر که بر نتیجه بیلد تأثیر می‌گذارند

* [`extends`](https://www.typescriptlang.org/tsconfig#extends)
* [`importsNotUsedAsValues`](https://www.typescriptlang.org/tsconfig#importsNotUsedAsValues)
* [`preserveValueImports`](https://www.typescriptlang.org/tsconfig#preserveValueImports)
* [`verbatimModuleSyntax`](https://www.typescriptlang.org/tsconfig#verbatimModuleSyntax)
* [`jsx`](https://www.typescriptlang.org/tsconfig#jsx)
* [`jsxFactory`](https://www.typescriptlang.org/tsconfig#jsxFactory)
* [`jsxFragmentFactory`](https://www.typescriptlang.org/tsconfig#jsxFragmentFactory)
* [`jsxImportSource`](https://www.typescriptlang.org/tsconfig#jsxImportSource)
* [`experimentalDecorators`](https://www.typescriptlang.org/tsconfig#experimentalDecorators)
* [`alwaysStrict`](https://www.typescriptlang.org/tsconfig#alwaysStrict)

::: tip `skipLibCheck`
قالب‌های شروع Vite به طور پیش‌فرض `"skipLibCheck": "true"` دارند تا از بررسی تایپ وابستگی‌ها جلوگیری کنند، زیرا ممکن است فقط از نسخه‌ها و تنظیمات خاصی از TypeScript پشتیبانی کنند. می‌توانید اطلاعات بیشتری را در [vuejs/vue-cli#5688](https://github.com/vuejs/vue-cli/pull/5688) بیابید.
:::

### تایپ‌های کلاینت

تایپ‌های پیش‌فرض Vite برای API مورد استفاده در Node.js آن هستند. برای شبیه‌سازی محیط کد سمت کلاینت در یک برنامه Vite، یک فایل تعریف `d.ts` اضافه کنید:

```typescript
/// <reference types="vite/client" />
```

::: details استفاده از `compilerOptions.types`

به طور جایگزین، می‌توانید `vite/client` را به `compilerOptions.types` در `tsconfig.json` اضافه کنید:

```json [tsconfig.json]
{
  "compilerOptions": {
    "types": ["vite/client", "some-other-global-lib"]
  }
}
```

توجه داشته باشید که اگر [`compilerOptions.types`](https://www.typescriptlang.org/tsconfig#types) مشخص شده باشد، تنها این پکیج‌ها در محدوده سراسری گنجانده خواهند شد (به جای همه پکیج‌های قابل مشاهده `‎@types`).

:::

`vite/client` کار تایپ‌های زیر را فراهم می‌کند:

* ایمپورت asset ها (مثلاً ایمپورت یک فایل `‎.svg`)
* تایپ‌ها برای [ثابت‌ها](./env-and-mode#env-variables) تزریق شده توسط Vite در `import.meta.env`
* تایپ‌ها برای [HMR API](./api-hmr) در `import.meta.hot`

::: tip نکته
برای بازنویسی تایپ‌های پیش‌فرض، یک فایل تعریف تایپ اضافه کنید که تایپ‌های شما را شامل شود. سپس، مرجع تایپ را قبل از `vite/client` اضافه کنید.

برای مثال، برای تبدیل ایمپورت پیش‌فرض `‎*.svg` به یک کامپوننت React:

* `vite-env-override.d.ts` (فایلی که تایپ‌های شما را شامل می‌شود):
  ```ts
  declare module '*.svg' {
    const content: React.FC<React.SVGProps<SVGElement>>
    export default content
  }
  ```
* فایلی که مرجع به `vite/client` را شامل می‌شود (در حالت نرمال `vite-env.d.ts`):
  ```ts
  /// <reference types="./vite-env-override.d.ts" />
  /// <reference types="vite/client" />
  ```

:::

## HTML

فایل‌های HTML در پروژه Vite به عنوان نقاط ورودی برای برنامه شما عمل می‌کنند و ساخت برنامه‌های تک‌صفحه‌ای و [چندصفحه‌ای](/guide/build.html#multi-page-app) را ساده می‌کنند.

می‌توان به هر فایل HTML که در ریشه پروژه شماست، مستقیماً از طریق مسیر دایرکتوری آن دسترسی پیدا کرد:

* `‎<root>/index.html` -> `http://localhost:5173/‎`
* `‎<root>/about.html` -> `http://localhost:5173/about.html`
* `‎<root>/blog/index.html` -> `http://localhost:5173/blog/index.html`

asset هایی که توسط عناصر HTML مانند `<script type="module" src>` و `<link href>` ارجاع داده می‌شوند، به عنوان بخشی از برنامه پردازش و بسته‌بندی می‌شوند. لیست کامل عناصر پشتیبانی شده به شرح زیر است:

* `<audio src>`
* `<embed src>`
* `<img src>` و `<img srcset>`
* `<image href>` و `<image xlink:href>`
* `<input src>`
* `<link href>` و `<link imagesrcset>`
* `<object data>`
* `<script type="module" src>`
* `<source src>` و `<source srcset>`
* `<track src>`
* `<use href>` و `<use xlink:href>`
* `<video src>` و `<video poster>`
* `<meta content>`
  * فقط اگر ویژگی `name` با `msapplication-tileimage` ، `msapplication-square70x70logo` ، `msapplication-square150x150logo` ، `msapplication-wide310x150logo` ، `msapplication-square310x310logo` ، `msapplication-config` ، `twitter:image` مطابقت داشته باشد.
  * یا فقط اگر ویژگی `property` با `og:image` ، `og:image:url` ، `og:image:secure_url` ، `og:audio` ، `og:audio:secure_url` ، `og:video` ، `og:video:secure_url` مطابقت داشته باشد.

```html {4-5,8-9}
<!doctype html>
<html>
  <head>
    <link rel="icon" href="/favicon.ico" />
    <link rel="stylesheet" href="/src/styles.css" />
  </head>
  <body>
    <img src="/src/images/logo.svg" alt="logo" />
    <script type="module" src="/src/main.js"></script>
  </body>
</html>
```

برای غیرفعال کردن پردازش HTML در برخی المنت‌ها، می‌توانید ویژگی `vite-ignore` را به عنصر اضافه کنید که می‌تواند در هنگام ارجاع به asset های خارجی یا CDN مفید باشد.

## فریمورک‌ها

تمام فریم‌ورک‌های مدرن با Vite یکپارچه‌سازی شده‌اند. بیشتر پلاگین‌های فریم‌ورک توسط تیم‌های هر فریم‌ورک نگهداری می‌شوند، به جز پلاگین‌های رسمی Vue و React Vite که توسط سازمان Vite نگهداری می‌شوند:

* پشتیبانی از Vue از طریق [‎@vitejs/plugin-vue](https://github.com/vitejs/vite-plugin-vue/tree/main/packages/plugin-vue)
* پشتیبانی از Vue JSX از طریق [‎@vitejs/plugin-vue-jsx](https://github.com/vitejs/vite-plugin-vue/tree/main/packages/plugin-vue-jsx)
* پشتیبانی از React از طریق [‎@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/tree/main/packages/plugin-react)
* پشتیبانی از React با استفاده از SWC از طریق [‎@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/tree/main/packages/plugin-react-swc)

برای اطلاعات بیشتر، به [راهنمای پلاگین‌ها](https://vite.dev/plugins) مراجعه کنید.

## JSX

فایل‌های `‎.jsx` و `‎.tsx` نیز به صورت پیش‌فرض پشتیبانی می‌شوند. ترنسپایل JSX نیز از طریق [esbuild](https://esbuild.github.io) انجام می‌شود.

فریم‌ورک انتخابی شما به طور پیش‌فرض JSX را پیکربندی خواهد کرد (برای مثال، کاربران Vue باید از پلاگین رسمی [‎@vitejs/plugin-vue-jsx](https://github.com/vitejs/vite-plugin-vue/tree/main/packages/plugin-vue-jsx) استفاده کنند که ویژگی‌های خاص Vue 3 از جمله HMR، حل و فصل سراسری کامپوننت‌ها، دایرکتیوها و اسلات‌ها را فراهم می‌کند).

اگر از JSX با فریم‌ورک خودتان استفاده می‌کنید، می‌توانید `jsxFactory` و `jsxFragment` سفارشی را با استفاده از گزینه [`esbuild`](/config/shared-options.md#esbuild) تنظیم کنید. به عنوان مثال، پلاگین Preact از این تنظیمات استفاده می‌کند:

```js twoslash [vite.config.js]
import { defineConfig } from 'vite'

export default defineConfig({
  esbuild: {
    jsxFactory: 'h',
    jsxFragment: 'Fragment',
  },
})
```

جزئیات بیشتر در [مستندات esbuild](https://esbuild.github.io/content-types/#jsx).

می‌توانید از `jsxInject` (که یک گزینه مخصوص Vite است) برای تزریق کمک‌کننده‌های JSX استفاده کنید تا از ایمپورت دستی جلوگیری کنید:

```js twoslash [vite.config.js]
import { defineConfig } from 'vite'

export default defineConfig({
  esbuild: {
    jsxInject: `import React from 'react'`,
  },
})
```

## CSS

ایمپورت فایل‌های `‎.css` محتوای آن‌ها را از طریق یک تگ `<style>` به صفحه اضافه می‌کند و از HMR پشتیبانی می‌کند.

### درون‌خطی کردن و بازنویسی `‎@import`

Vite به صورت پیش‌فرض برای پشتیبانی از درون‌خطی کردن `‎@import` در CSS با `postcss-import` پیکربندی شده است. همچنین، نام‌های مستعار Vite برای `‎@import` در CSS نیز رعایت می‌شوند. علاوه بر این، تمام ارجاعات `url()‎` در CSS، حتی اگر فایل‌های ایمپورت شده در دایرکتوری‌های مختلف باشند، به طور خودکار بازنویسی می‌شوند تا از صحت آن‌ها اطمینان حاصل شود.

نام‌های مستعار `‎@import` و بازنشانی URL برای فایل‌های Sass و Less نیز پشتیبانی می‌شوند (به [پیش‌پردازنده‌های CSS](#پیشپردازندههای-css) مراجعه کنید).

### PostCSS

اگر پروژه شامل پیکربندی معتبر PostCSS باشد (هر فرمتی که توسط [postcss-load-config](https://github.com/postcss/postcss-load-config) پشتیبانی می‌شود، مانند `postcss.config.js`)، به طور خودکار به تمام CSS ایمپورت شده اعمال می‌شود.

توجه داشته باشید که کوچک‌سازی CSS پس از PostCSS اجرا می‌شود و از گزینه [`build.cssTarget`](/config/build-options.md#build-csstarget) استفاده خواهد کرد.

### ماژول‌های CSS

هر فایل CSS که با `‎.module.css` ختم شود، به عنوان یک [فایل ماژول‌های CSS](https://github.com/css-modules/css-modules) در نظر گرفته می‌شود. ایمپورت چنین فایلی آبجکت ماژول مربوطه را برمی‌گرداند:

```css [example.module.css]
.red {
  color: red;
}
```

```js twoslash
import 'vite/client'
// ---cut---
import classes from './example.module.css'
document.getElementById('foo').className = classes.red
```

تنظیمات ماژول‌های CSS را می‌توان از طریق گزینه [`css.modules`](/config/shared-options.md#css-modules) پیکربندی کرد.

اگر `css.modules.localsConvention` تنظیم شده باشد تا نام‌های محلی به صورت camelCase فعال شوند (مثلاً `localsConvention: 'camelCaseOnly'‎`)، می‌توانید از ایمپورت‌های نام‌گذاری شده نیز استفاده کنید:

```js twoslash
import 'vite/client'
// ---cut---
// .apply-color -> applyColor
import { applyColor } from './example.module.css'
document.getElementById('foo').className = applyColor
```

### پیش‌پردازنده‌های CSS

از آنجا که Vite فقط مرورگرهای مدرن را هدف قرار می‌دهد، توصیه می‌شود از متغیرهای بومی CSS با پلاگین‌های PostCSS که پیش‌نویس‌های CSSWG را پیاده‌سازی می‌کنند (مثلاً [postcss-nesting](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-nesting)) استفاده کنید و CSS ساده و مطابق با استانداردهای آینده بنویسید.

با این حال، Vite پشتیبانی داخلی از فایل‌های `‎.scss` ، `‎.sass` ، `‎.less` ، `‎.styl` و `‎.stylus` را فراهم می‌کند. نیازی به نصب پلاگین‌های مخصوص Vite برای آن‌ها نیست، اما باید پیش‌پردازنده مربوطه نصب شده باشد:

```bash
# .scss and .sass
npm add -D sass-embedded # or sass

# .less
npm add -D less

# .styl and .stylus
npm add -D stylus
```

اگر از کامپوننت‌های تک‌فایلی Vue استفاده می‌کنید، این به طور خودکار `<style lang="sass"‎>` و موارد مشابه را فعال می‌کند.

Vite بهبودهایی در ‎`@import` برای Sass و Less ارائه می‌دهد تا نام‌های مستعار Vite نیز رعایت شوند. علاوه بر این، ارجاعات نسبی `url()‎` در فایل‌های Sass/Less ایمپورت شده که در دایرکتوری‌های مختلف از فایل ریشه قرار دارند، به طور خودکار بازنویسی می‌شوند تا از صحت آن‌ها اطمینان حاصل شود. بازنویسی آدرس‌های `url()`‎ که با متغیر یا درون‌گذاری (متغیر یا عبارتی داخل ‎`${}`‎) شروع می‌شوند، به دلیل محدودیت‌های API پشتیبانی نمی‌شود.

نام مستعار `‎@import` و بازنویسی URL برای Stylus به دلیل محدودیت‌های API آن پشتیبانی نمی‌شوند.

همچنین می‌توانید از ماژول‌های CSS همراه با پیش‌پردازنده‌ها استفاده کنید، با اضافه کردن `‎.module` به پسوند فایل، به عنوان مثال `style.module.scss`.

### غیرفعال کردن تزریق CSS به صفحه

تزریق خودکار محتوای CSS را می‌توان از طریق پارامتر `‎?inline` غیرفعال کرد. در این حالت، رشته CSS پردازش شده به عنوان خروجی پیش‌فرض ماژول برگردانده می‌شود، اما استایل‌ها به صفحه تزریق نمی‌شوند.

```js twoslash
import 'vite/client'
// ---cut---
import './foo.css' // به صفحه تزریق خواهد شد
import otherStyles from './bar.css?inline' // تزریق نخواهد شد
```

::: tip نکته
ایمپورت‌های پیش‌فرض و نام‌گذاری شده از فایل‌های CSS (مثلاً `import style from './foo.css'‎`) از Vite 5 حذف شده‌اند. به جای آن از کوئری `‎?inline` استفاده کنید.
:::

### Lightning CSS

از Vite 4.4، پشتیبانی آزمایشی برای [Lightning CSS](https://lightningcss.dev/) وجود دارد. می‌توانید با اضافه کردن [`css.transformer: 'lightningcss'‎`](../config/shared-options.md#css-transformer) به فایل پیکربندی خود و نصب وابستگی اختیاری [`lightningcss`](https://www.npmjs.com/package/lightningcss) از آن استفاده کنید:

```bash
npm add -D lightningcss
```

اگر فعال شود، فایل‌های CSS توسط Lightning CSS به جای PostCSS پردازش خواهند شد. برای پیکربندی آن، می‌توانید گزینه‌های Lightning CSS را به گزینه پیکربندی [`css.lightningcss`](../config/shared-options.md#css-lightningcss) پاس دهید.

برای پیکربندی ماژول‌های CSS، باید از [`css.lightningcss.cssModules`](https://lightningcss.dev/css-modules.html) به جای [`css.modules`](../config/shared-options.md#css-modules) استفاده کنید (که نحوه پردازش ماژول‌های CSS توسط PostCSS را پیکربندی می‌کند).

به طور پیش‌فرض، Vite از esbuild برای کوچک‌سازی CSS استفاده می‌کند. Lightning CSS نیز می‌تواند به عنوان کوچک‌ساز CSS با گزینه [`build.cssMinify: 'lightningcss'‎`](../config/build-options.md#build-cssminify) استفاده شود.

## assets های استاتیک

ایمپورت یک assets استاتیک، URL عمومی ساخته شده آن را برمی‌گرداند:

```js twoslash
import 'vite/client'
// ---cut---
import imgUrl from './img.png'
document.getElementById('hero-img').src = imgUrl
```

کوئری‌های خاص می‌توانند نحوه بارگذاری assets ها را تغییر دهند:

```js twoslash
import 'vite/client'
// ---cut---
// (به‌صورت خودکار و بسته به اندازه فایل، درون‌خطی می‌شود) URL به عنوان assets بارگذاری صریح
import assetAsURL from './asset.js?url'
```

```js twoslash
import 'vite/client'
// ---cut---
// به عنوان رشته assets بارگذاری
import assetAsString from './shader.glsl?raw'
```

```js twoslash
import 'vite/client'
// ---cut---
// Web Workers بارگذاری
import Worker from './worker.js?worker'
```

```js twoslash
import 'vite/client'
// ---cut---
// در زمان بیلد درون‌خطی می‌شوند base64 به صورت رشته‌های Web Workers
import InlineWorker from './worker.js?worker&inline'
```

جزئیات بیشتر در [مدیریت assets های استاتیک](./assets).

## JSON

فایل‌های JSON می‌توانند به طور مستقیم ایمپورت شوند - ایمپورت‌های نام‌گذاری شده نیز پشتیبانی می‌شوند:

```js twoslash
import 'vite/client'
// ---cut---
// import the entire object
import json from './example.json'
// import a root field as named exports - helps with tree-shaking!
import { field } from './example.json'
```

## ایمپورت Glob

Vite از ایمپورت چندین ماژول از فایل-سیستم با استفاده از تابع خاص `import.meta.glob` پشتیبانی می‌کند:

```js twoslash
import 'vite/client'
// ---cut---
const modules = import.meta.glob('./dir/*.js')
```

کد بالا به شکل زیر تبدیل خواهد شد:

```js
// Vite کد تولید شده توسط
const modules = {
  './dir/bar.js': () => import('./dir/bar.js'),
  './dir/foo.js': () => import('./dir/foo.js'),
}
```

سپس می‌توانید بر روی کلیدهای آبجکت `modules` حلقه بزنید تا به ماژول‌های مربوطه دسترسی پیدا کنید:

```js
for (const path in modules) {
  modules[path]().then((mod) => {
    console.log(path, mod)
  })
}
```

فایل‌های پیدا شده به طور پیش‌فرض از طریق ایمپورت داینامیک به صورت lazy-loaded بارگذاری می‌شوند و در زمان بیلد به چندین chunk (بخش) جداگانه تقسیم می‌شوند. اگر ترجیح می‌دهید همه ماژول‌ها را مستقیماً ایمپورت کنید (مثلاً برای اعمال اثرات جانبی این ماژول‌ها در ابتدا)، می‌توانید `{ eager: true }` را به عنوان آرگومان دوم پاس دهید:

```js twoslash
import 'vite/client'
// ---cut---
const modules = import.meta.glob('./dir/*.js', { eager: true })
```

کد بالا به شکل زیر تبدیل خواهد شد:

```js
// Vite کد تولید شده توسط
import * as __vite_glob_0_0 from './dir/bar.js'
import * as __vite_glob_0_1 from './dir/foo.js'
const modules = {
  './dir/bar.js': __vite_glob_0_0,
  './dir/foo.js': __vite_glob_0_1,
}
```

### الگوهای متعدد

آرگومان اول می‌تواند یک آرایه از glob ها باشد، برای مثال:

```js twoslash
import 'vite/client'
// ---cut---
const modules = import.meta.glob(['./dir/*.js', './another/*.js'])
```

### الگوهای منفی

الگوهای glob منفی نیز پشتیبانی می‌شوند (با پیشوند `!`). برای نادیده گرفتن برخی فایل‌ها از نتیجه، می‌توانید الگوهای exclude را به آرگومان اول اضافه کنید:

```js twoslash
import 'vite/client'
// ---cut---
const modules = import.meta.glob(['./dir/*.js', '!**/bar.js'])
```

```js
// Vite کد تولید شده توسط
const modules = {
  './dir/foo.js': () => import('./dir/foo.js'),
}
```

#### ایمپورت‌های نام‌گذاری شده

امکان ایمپورت بخش‌هایی از ماژول‌ها با استفاده از گزینه `import` وجود دارد.

```ts twoslash
import 'vite/client'
// ---cut---
const modules = import.meta.glob('./dir/*.js', { import: 'setup' })
```

```ts
// Vite کد تولید شده توسط
const modules = {
  './dir/bar.js': () => import('./dir/bar.js').then((m) => m.setup),
  './dir/foo.js': () => import('./dir/foo.js').then((m) => m.setup),
}
```

هنگامی که با `eager` ترکیب شود، حتی می‌توان tree-shaking را برای این ماژول‌ها فعال کرد.

```ts twoslash
import 'vite/client'
// ---cut---
const modules = import.meta.glob('./dir/*.js', {
  import: 'setup',
  eager: true,
})
```

```ts
// Vite کد تولید شده توسط
import { setup as __vite_glob_0_0 } from './dir/bar.js'
import { setup as __vite_glob_0_1 } from './dir/foo.js'
const modules = {
  './dir/bar.js': __vite_glob_0_0,
  './dir/foo.js': __vite_glob_0_1,
}
```

برای ایمپورت خروجی پیش‌فرض، `import` را به `default` تنظیم کنید.

```ts twoslash
import 'vite/client'
// ---cut---
const modules = import.meta.glob('./dir/*.js', {
  import: 'default',
  eager: true,
})
```

```ts
// Vite کد تولید شده توسط
import { default as __vite_glob_0_0 } from './dir/bar.js'
import { default as __vite_glob_0_1 } from './dir/foo.js'
const modules = {
  './dir/bar.js': __vite_glob_0_0,
  './dir/foo.js': __vite_glob_0_1,
}
```

#### کوئری‌های سفارشی

همچنین می‌توانید از گزینه `query` برای ارائه کوئری‌ها به ایمپورت‌ها استفاده کنید، به عنوان مثال، برای ایمپورت asset ها [به عنوان رشته](https://vite.dev/guide/assets.html#importing-asset-as-string) یا [به عنوان URL](https://vite.dev/guide/assets.html#importing-asset-as-url):

```ts twoslash
import 'vite/client'
// ---cut---
const moduleStrings = import.meta.glob('./dir/*.svg', {
  query: '?raw',
  import: 'default',
})
const moduleUrls = import.meta.glob('./dir/*.svg', {
  query: '?url',
  import: 'default',
})
```

```ts
// Vite کد تولید شده توسط
const moduleStrings = {
  './dir/bar.svg': () => import('./dir/bar.svg?raw').then((m) => m['default']),
  './dir/foo.svg': () => import('./dir/foo.svg?raw').then((m) => m['default']),
}
const moduleUrls = {
  './dir/bar.svg': () => import('./dir/bar.svg?url').then((m) => m['default']),
  './dir/foo.svg': () => import('./dir/foo.svg?url').then((m) => m['default']),
}
```

همچنین می‌توانید کوئری‌های سفارشی برای استفاده سایر پلاگین‌ها ارائه دهید:

```ts twoslash
import 'vite/client'
// ---cut---
const modules = import.meta.glob('./dir/*.js', {
  query: { foo: 'bar', bar: true },
})
```

#### مسیر پایه (Base Path)

می‌توانید از آپشن `base` برای تعیین مسیر پایه‌ی ایمپورت‌ها استفاده کنید:

```ts twoslash
import 'vite/client'
// ---cut---
const modulesWithBase = import.meta.glob('./**/*.js', {
  base: './base',
})
```

```ts
// تولید می‌شود Vite کدی که توسط
const modulesWithBase = {
  './dir/foo.js': () => import('./base/dir/foo.js'),
  './dir/bar.js': () => import('./base/dir/bar.js'),
}
```

آپشن `base` فقط می‌تواند یک مسیر پوشه باشد که یا نسبت به فایل فراخوان (importer) تعریف شده، یا به صورت مطلق نسبت به ریشه‌ی پروژه باشد. استفاده از aliasها و ماژول‌های مجازی (virtual modules) پشتیبانی نمی‌شود.

فقط الگوهای مسیری (globs) که به صورت نسبی تعریف شده‌اند، نسبت به مسیر پایه‌ی تعیین‌شده تفسیر می‌شوند.

در نهایت، کلیدهای ماژول تولیدشده طوری تغییر می‌کنند که نسبت به مسیر پایه باشند، اگر گزینه‌ی `base` مشخص شده باشد.

### نکات مهم درباره Glob Import

توجه داشته باشید که:

* این یک ویژگی مخصوص Vite است و یک استاندارد وب یا ES نیست.
* الگوهای glob مانند مشخص‌کننده‌های ایمپورت در نظر گرفته می‌شوند: آن‌ها باید یا نسبی باشند (با `‎./‎` شروع شوند) یا مطلق (با `/` شروع شوند و نسبت به ریشه پروژه اضافه شوند) یا یک مسیر مستعار باشند (به گزینه [`resolve.alias`](/config/shared-options.md#resolve-alias) مراجعه کنید).
* تطبیق glob از طریق [`tinyglobby`](https://github.com/SuperchupuDev/tinyglobby) انجام می‌شود.
* همچنین باید توجه داشته باشید که تمام آرگومان‌ها در `import.meta.glob` باید **به صورت ثابت** پاس داده شوند. نمی‌توانید از متغیرها یا عبارات در آن‌ها استفاده کنید.

## ایمپورت داینامیک

مشابه [glob import](#ایمپورت-glob)، ابزار Vite همچنین از ایمپورت داینامیک با متغیرها پشتیبانی می‌کند.

```ts
const module = await import(`./dir/${file}.js`)
```

توجه داشته باشید که متغیرها فقط نام فایل‌ها را در یک عمق نشان می‌دهند. اگر `file` برابر با `'foo/bar'` باشد، ایمپورت شکست خواهد خورد. برای استفاده پیشرفته‌تر، می‌توانید از ویژگی [glob import](#ایمپورت-glob) استفاده کنید.

## WebAssembly

فایل‌های `‎.wasm` پیش‌کامپایل شده را می‌توان با `‎?init` ایمپورت کرد.
خروجی پیش‌فرض یک تابع راه‌اندازی خواهد بود که یک Promise از [`WebAssembly.Instance`](https://developer.mozilla.org/en-US/docs/WebAssembly/JavaScript_interface/Instance) را برمی‌گرداند:

```js twoslash
import 'vite/client'
// ---cut---
import init from './example.wasm?init'

init().then((instance) => {
  instance.exports.test()
})
```

تابع init همچنین می‌تواند یک importObject بگیرد که به عنوان آرگومان دوم به [`WebAssembly.instantiate`](https://developer.mozilla.org/en-US/docs/WebAssembly/JavaScript_interface/instantiate) پاس داده می‌شود:

```js twoslash
import 'vite/client'
import init from './example.wasm?init'
// ---cut---
init({
  imports: {
    someFunc: () => {
      /* ... */
    },
  },
}).then(() => {
  /* ... */
})
```

در بیلد پروداکش، فایل‌های `‎.wasm` که کوچکتر از `assetInlineLimit` هستند به صورت رشته‌های base64 درون‌خطی خواهند شد. در غیر این صورت، به عنوان یک [asset استاتیک](./assets) در نظر گرفته می‌شوند و در صورت درخواست بارگذاری خواهند شد.

::: tip نکته
[پیشنهاد یکپارچه‌سازی ماژول ES برای WebAssembly](https://github.com/WebAssembly/esm-integration) در حال حاضر پشتیبانی نمی‌شود.
از [`vite-plugin-wasm`](https://github.com/Menci/vite-plugin-wasm) یا سایر پلاگین‌های جامعه برای مدیریت این موضوع استفاده کنید.
:::

### دسترسی به ماژول WebAssembly

اگر نیاز به دسترسی به آبجکت `Module` دارید، مثلاً برای نمونه‌سازی چندباره آن، از یک [ایمپورت URL صریح](./assets#explicit-url-imports) برای حل و فصل asset استفاده کنید و سپس نمونه‌سازی را انجام دهید:

```js twoslash
import 'vite/client'
// ---cut---
import wasmUrl from 'foo.wasm?url'

const main = async () => {
  const responsePromise = fetch(wasmUrl)
  const { module, instance } =
    await WebAssembly.instantiateStreaming(responsePromise)
  /* ... */
}

main()
```

### دریافت ماژول در Node.js

در SSR، در `fetch()‎` که به عنوان بخشی از ایمپورت `‎?init` انجام می‌شود، ممکن است با خطای `TypeError: Invalid URL` مواجه شود.
به مشکل [پشتیبانی از wasm در SSR](https://github.com/vitejs/vite/issues/8882) مراجعه کنید.

در اینجا یک روش جایگزین آورده شده است، با فرض اینکه پایه پروژه دایرکتوری فعلی است:

```js twoslash
import 'vite/client'
// ---cut---
import wasmUrl from 'foo.wasm?url'
import { readFile } from 'node:fs/promises'

const main = async () => {
  const resolvedUrl = (await import('./test/boot.test.wasm?url')).default
  const buffer = await readFile('.' + resolvedUrl)
  const { instance } = await WebAssembly.instantiate(buffer, {
    /* ... */
  })
  /* ... */
}

main()
```

## Web Workers

### ایمپورت با سازنده‌ها (Constructors)

یک اسکریپت web worker می‌تواند با استفاده از [`new Worker()‎`](https://developer.mozilla.org/en-US/docs/Web/API/Worker/Worker) و [`new SharedWorker()‎`](https://developer.mozilla.org/en-US/docs/Web/API/SharedWorker/SharedWorker) ایمپورت شود. در مقایسه با پسوندهای worker، این سینتکس به استانداردها نزدیک‌تر است و روش **توصیه‌شده** برای ایجاد workers است.

```ts
const worker = new Worker(new URL('./worker.js', import.meta.url))
```

سازنده Worker همچنین گزینه‌هایی را می‌پذیرد که می‌توان از آن‌ها برای ایجاد «ماژول Worker» استفاده کرد:

```ts
const worker = new Worker(new URL('./worker.js', import.meta.url), {
  type: 'module',
})
```

شناسایی Worker تنها در صورتی کار می‌کند که سازنده `new URL()‎` به‌طور مستقیم در دستور `new Worker()‎` استفاده شده باشد. علاوه بر این، تمامی پارامترها باید مقادیر ثابتی مانند رشته‌های ثابت باشند.

### ایمپورت با پسوندهای دارای کوئری

یک اسکریپت web worker می‌تواند با اضافه کردن `‎?worker` یا `‎?sharedworker` به درخواست ایمپورت، مستقیماً ایمپورت شود. خروجی پیش‌فرض یک سازنده worker سفارشی خواهد بود:

```js twoslash
import 'vite/client'
// ---cut---
import MyWorker from './worker?worker'

const worker = new MyWorker()
```

اسکریپت worker می‌تواند از دستور ESM `import` به جای `importScripts()‎` استفاده کند. **توجه**: در زمان توسعه، این موضوع به [پشتیبانی بومی مرورگر](https://caniuse.com/?search=module%20worker) متکی است، اما در زمان بیلد پروداکشن، کد ماژول‌ها کامپایل و از بین می‌رود.

به طور پیش‌فرض، اسکریپت worker در بیلد پروداکشن به صورت یک chunk جداگانه خروجی گرفته می‌شود. اگر می‌خواهید worker را به صورت رشته‌های base64 درون‌خطی کنید، کوئری `inline` را اضافه کنید:

```js twoslash
import 'vite/client'
// ---cut---
import MyWorker from './worker?worker&inline'
```

اگر مایلید worker را به صورت یک URL دریافت کنید، کوئری `url` را اضافه کنید:

```js twoslash
import 'vite/client'
// ---cut---
import MyWorker from './worker?worker&url'
```

برای مشاهده جزییات درباره نحوه باندل شدن همه‌ی worker ها، به [گزینه‌های Worker](/config/worker-options.md) مراجعه کنید.

## سیاست امنیت محتوایی (CSP)

به دلیل ساختار داخلی Vite، برای استفاده از CSP باید بعضی دستورالعمل‌ها یا تنظیمات خاص اعمال شوند.

### [`'nonce-{RANDOM}'`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/Sources#nonce-base64-value)

وقتی [`html.cspNonce`](/config/shared-options#html-cspnonce) تنظیم شود، Vite یک اتریبیوت nonce با مقدار تعیین‌شده به تمام تگ‌های `<script>` و `<style>` اضافه می‌کند و همچنین تگ‌های `<link>` برای استایل‌ها و ماژول‌های preload. علاوه بر این، وقتی این گزینه تنظیم شود، Vite یک تگ متا نیز تزریق می‌کند.  (`‎<meta property="csp-nonce" nonce="PLACEHOLDER"‎ />‎`).

مقدار nonce در یک تگ متا با `property="csp-nonce"‎` هنگام توسعه و پس از بیلد، در صورت نیاز توسط Vite استفاده می‌شود.

:::warning هشدار
اطمینان حاصل کنید که این placeholder را برای هر درخواست با مقدار یکتایی جایگزین کنید. این کار برای جلوگیری از دور زدن سیاست امنیتی محتوا ضروری است.
:::

### [`data:`‎](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/Sources#scheme-source:~:text=schemes%20\(not%20recommended\).-,data%3A,-Allows%20data%3A)

Vite به طور پیش‌فرض، در زمان بیلد، asset ‌های کوچک را به صورت data URIs درون‌خطی می‌کند. برای استفاده از آن در بخش‌های مرتبط (مثلاً [`img-src`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/img-src) و [`font-src`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/font-src)) باید `data:‎` مجاز باشد، یا با تنظیم [`build.assetsInlineLimit: 0`](/config/build-options#build-assetsinlinelimit) می‌توانید آن را غیرفعال کنید.

:::warning هشدار
هرگز `data:‎` را برای [`script-src`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/script-src) مجاز نکنید. این کار امکان تزریق اسکریپت‌های دلخواه را فراهم می‌کند.
:::

## بهینه‌سازی بیلد

> امکانات زیر به صورت خودکار در فرآیند بیلد اعمال می‌شوند و نیازی به پیکربندی صریح ندارند، مگر در صورتی که بخواهید آن‌ها را غیرفعال کنید.

### تقسیم کد CSS

Vite به صورت خودکار CSS استفاده‌شده توسط ماژول‌های موجود در یک chunk ناهمگام (chunk ناهمگام 'async chunk'، منظور بخشی از کد است که به صورت مجزا و در زمان نیاز بارگذاری می‌شود) را استخراج کرده و یک فایل جداگانه برای آن ایجاد می‌کند. این فایل CSS به صورت خودکار از طریق یک تگ `<link>` هنگام بارگیری chunk ناهمگام لود می‌شود و اطمینان حاصل می‌شود که ارزیابی chunk بعد از بارگیری کامل CSS انجام شود تا از [FOUC](https://en.wikipedia.org/wiki/Flash_of_unstyled_content#:~:text=A%20flash%20of%20unstyled%20content,before%20all%20information%20is%20retrieved.) جلوگیری شود.

اگر ترجیح می‌دهید تمام CSS در یک فایل گردآوری شود، می‌توانید با تنظیم [`build.cssCodeSplit`](/config/build-options.md#build-csscodesplit) روی `false` تقسیم کد CSS را غیرفعال کنید.

### تولید دستورالعمل‌های پیش‌بارگیری

Vite به طور خودکار دستورالعمل‌های `<link rel="modulepreload"‎>` را برای بخش‌های ورودی و ایمپورت‌های مستقیم آن‌ها در HTML نهایی تولید می‌کند.

### بهینه‌سازی بارگیری بخش‌های async

در برنامه‌های دنیای واقعی، Rollup اغلب "بخش‌های مشترک" را تولید می‌کند - کدهایی که بین دو یا چند بخش دیگر به اشتراک گذاشته می‌شوند. همراه با ایمپورت‌های پویا، چنین سناریویی بسیار رایج است:

در سناریوهای بهینه‌نشده، وقتی بخش `A` که async هست ایمپورت می‌شود، مرورگر باید ابتدا `A` را درخواست و پردازش کند تا متوجه شود که به بخش مشترک `C` نیز نیاز دارد. این باعث یک رفت و برگشت اضافی در شبکه می‌شود:

```
Entry ---> A ---> C
```

Vite به طور خودکار فراخوانی‌های ایمپورت پویای تقسیم‌شده کد را با یک مرحله پیش‌بارگیری بازنویسی می‌کند، به طوری که وقتی `A` درخواست می‌شود، `C` به صورت **موازی** دریافت می‌شود:

```
Entry ---> (A + C)
```

ممکن است `C` نیز ایمپورت‌های دیگری داشته باشد که در حالت بهینه‌نشده منجر به رفت و برگشت‌های بیشتری می‌شود. بهینه‌سازی Vite تمام ایمپورت‌های مستقیم را ردیابی می‌کند تا صرف نظر از عمق ایمپورت، رفت و برگشت‌ها را به طور کامل حذف کند.

---

---
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) و نوع ماژول را معمولاً بر اساس پسوند فایل تشخیص می‌دهد، مگر اینکه صراحتاً مشخص شده باشد.

---

---
url: /guide/backend-integration.md
---
# یکپارچه‌سازی با بک‌اند (Backend Integration)

:::tip نکته
اگر می‌خواهید HTML را با یک بک‌اند سنتی مثل Rails یا Laravel ارائه دهید، اما از Vite برای سرویس‌دهی به فایل‌های استاتیک (مثل CSS و JS) استفاده کنید، بهتر است ابتدا بررسی کنید که آیا یکپارچه‌سازی آماده‌ای برای فریم‌ورک مورد نظر شما در [Awesome Vite](https://github.com/vitejs/awesome-vite#integrations-with-backends) وجود دارد یا نه.

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

1. در فایل کانفیگ Vite خود، نقطه ورود (entry) را مشخص کرده و گزینه تولید مانیفست (build manifest) را فعال کنید:

   ```js twoslash [vite.config.js]
   import { defineConfig } from 'vite'
   // ---cut---
   export default defineConfig({
     server: {
       cors: {
         // مبدأیی که قرار است از طریق مرورگر به آن دسترسی داشته باشید
         origin: 'http://my-backend.example.com',
       },
     },
     build: {
       // تولید می‌کند outDir را در مسیر .vite/manifest.json فایل
       manifest: true,
       rollupOptions: {
         // را بازنویسی می‌کند .html ورودی پیش‌فرض
         input: '/path/to/main.js',
       },
     },
   })
   ```

   اگر [polyfill مربوط به preload ماژول](/config/build-options.md#build-polyfillmodulepreload) را غیرفعال نکرده‌اید، باید این polyfill را هم در فایل ورودی (entry) خود وارد کنید.

   ```js
   // ابتدای ورودی برنامه خود را اضافه کنید
   import 'vite/modulepreload-polyfill'
   ```

2. برای محیط توسعه، موارد زیر را در قالب HTML سرور خود وارد کنید (آدرس `http://localhost:5173` را با آدرس محلی که Vite در آن اجرا می‌شود، جایگزین کنید):

   ```html
   <!-- if development -->
   <script type="module" src="http://localhost:5173/@vite/client"></script>
   <script type="module" src="http://localhost:5173/main.js"></script>
   ```

   برای سرویس‌دهی صحیح asset ها، دو راه دارید:

   * اطمینان حاصل کنید که سرور به درستی تنظیم شده باشد تا درخواست‌های asset های استاتیک را به سرور Vite پروکسی کند.
   * گزینه [`server.origin`](/config/server-options.md#server-origin) را تنظیم کنید تا آدرس‌های URL برای asset های تولید شده با استفاده از آدرس سرور بک‌اند اضافه شوند، به جای اینکه از مسیر نسبی استفاده کنند.

   این کار برای بارگذاری صحیح asset هایی مانند تصاویر ضروری است.

   توجه داشته باشید که اگر از React همراه با `‎@vitejs/plugin-react` استفاده می‌کنید، باید این را قبل از اسکریپت‌های بالا اضافه کنید، زیرا این پلاگین قادر به تغییر HTML که شما سرو می‌کنید نیست (آدرس `http://localhost:5173` را با آدرس محلی که Vite در آن در حال اجرا است جایگزین کنید).

   ```html
   <script type="module">
     import RefreshRuntime from 'http://localhost:5173/@react-refresh'
     RefreshRuntime.injectIntoGlobalHook(window)
     window.$RefreshReg$ = () => {}
     window.$RefreshSig$ = () => (type) => type
     window.__vite_plugin_react_preamble_installed__ = true
   </script>
   ```

3. برای پروداکشن: پس از اجرای دستور `vite build`، یک فایل `‎.vite/manifest.json` همراه با سایر فایل‌های asset تولید خواهد شد. نمونه فایل مانفیست به شکل زیر خواهد بود:

   ```json [.vite/manifest.json]
   {
     "_shared-B7PI925R.js": {
       "file": "assets/shared-B7PI925R.js",
       "name": "shared",
       "css": ["assets/shared-ChJ_j-JJ.css"]
     },
     "_shared-ChJ_j-JJ.css": {
       "file": "assets/shared-ChJ_j-JJ.css",
       "src": "_shared-ChJ_j-JJ.css"
     },
     "baz.js": {
       "file": "assets/baz-B2H3sXNv.js",
       "name": "baz",
       "src": "baz.js",
       "isDynamicEntry": true
     },
     "views/bar.js": {
       "file": "assets/bar-gkvgaI9m.js",
       "name": "bar",
       "src": "views/bar.js",
       "isEntry": true,
       "imports": ["_shared-B7PI925R.js"],
       "dynamicImports": ["baz.js"]
     },
     "views/foo.js": {
       "file": "assets/foo-BRBmoGS9.js",
       "name": "foo",
       "src": "views/foo.js",
       "isEntry": true,
       "imports": ["_shared-B7PI925R.js"],
       "css": ["assets/foo-5UjPuW-k.css"]
     }
   }
   ```

   * مانیفست دارای ساختار `Record<name, chunk>‎` است
   * برای چانک‌های ورودی یا چانک‌های ورودی پویا، کلید همان مسیر نسبی فایل src است که از مسیر ریشه پروژه شروع می‌شود.
   * برای چانک‌های غیر ورودی، کلید نام پایه فایل تولید شده با پیشوند `_` است.
   * برای فایل CSS تولید شده هنگامی که [`build.cssCodeSplit`](/config/build-options.md#build-csscodesplit) برابر با `false` است، کلید `style.css` است.
   * چانک‌ها شامل اطلاعاتی درباره ایمپورت‌های استاتیک و پویای خود هستند (هر دو کلیدهایی هستند که به چانک مربوطه در مانیفست اشاره می‌کنند) و همچنین فایل‌های CSS و asset مرتبط (در صورت وجود).

4. می‌توانید از این فایل برای رندر کردن لینک‌ها یا دستورالعمل‌های پیش‌بارگذاری با نام‌های هش‌شده فایل‌ها استفاده کنید.

   در اینجا یک نمونه قالب HTML برای رندر کردن لینک‌های مناسب آورده شده است. سینتکس ارائه‌شده فقط برای توضیح است
   و باید با زبان قالب‌نویسی سرور شما جایگزین شود.
   تابع `importedChunks` فقط برای نمایش است و توسط Vite ارائه نمی‌شود.

   ```html
   <!-- if production -->

   <!-- for cssFile of manifest[name].css -->
   <link rel="stylesheet" href="/{{ cssFile }}" />

   <!-- for chunk of importedChunks(manifest, name) -->
   <!-- for cssFile of chunk.css -->
   <link rel="stylesheet" href="/{{ cssFile }}" />

   <script type="module" src="/{{ manifest[name].file }}"></script>

   <!-- for chunk of importedChunks(manifest, name) -->
   <link rel="modulepreload" href="/{{ chunk.file }}" />
   ```

   به طور مشخص، یک بک‌اند که HTML تولید می‌کند باید با توجه به
   فایل مانیفست و یک نقطه ورودی، تگ‌های زیر را شامل شود:

   * یک تگ `‎<link rel="stylesheet">‎` برای هر فایل در لیست `css` چانک نقطه ورودی.
   * به صورت بازگشتی تمام چانک‌های موجود در لیست `imports` ورودی را دنبال کنید و یک تگ
     `‎<link rel="stylesheet">`‎ برای هر فایل CSS از هر چانک ایمپورت‌شده اضافه کنید.
   * یک تگ برای کلید `file` چانک ورودی (برای جاوااسکریپت `‎<script type="module">‎`،
     یا برای CSS ‎`<link rel="stylesheet">`‎).
   * به صورت اختیاری، یک تگ `‎<link rel="modulepreload">‎` برای `file` برای هر چانک جاوااسکریپت
     ایمپورت‌شده، باز هم به صورت بازگشتی از چانک ورودی شروع کنید.

   با توجه به مثال مانیفست بالا، برای ورودی `views/foo.js`، تگ‌های زیر باید در محیط پروداکشن گنجانده شوند:

   ```html
   <link rel="stylesheet" href="assets/foo-5UjPuW-k.css" />
   <link rel="stylesheet" href="assets/shared-ChJ_j-JJ.css" />
   <script type="module" src="assets/foo-BRBmoGS9.js"></script>
   <!-- optional -->
   <link rel="modulepreload" href="assets/shared-B7PI925R.js" />
   ```

   در حالی که موارد زیر باید برای ورودی `views/bar.js` گنجانده شوند:

   ```html
   <link rel="stylesheet" href="assets/shared-ChJ_j-JJ.css" />
   <script type="module" src="assets/bar-gkvgaI9m.js"></script>
   <!-- optional -->
   <link rel="modulepreload" href="assets/shared-B7PI925R.js" />
   ```

   ::: details پیاده‌سازی شبه‌کد تابع `importedChunks`
   یک مثال از پیاده‌سازی شبه‌کد `importedChunks` در TypeScript
   (این کد نیاز به سازگاری با زبان برنامه‌نویسی و زبان قالب‌بندی شما خواهد داشت):

   ```ts
   import type { Manifest, ManifestChunk } from 'vite'

   export default function importedChunks(
     manifest: Manifest,
     name: string,
   ): ManifestChunk[] {
     const seen = new Set<string>()

     function getImportedChunks(chunk: ManifestChunk): ManifestChunk[] {
       const chunks: ManifestChunk[] = []
       for (const file of chunk.imports ?? []) {
         const importee = manifest[file]
         if (seen.has(file)) {
           continue
         }
         seen.add(file)

         chunks.push(...getImportedChunks(importee))
         chunks.push(importee)
       }

       return chunks
     }

     return getImportedChunks(manifest[name])
   }
   ```

   :::