Environment API

آزمایشی

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

منابع:

• بحث و گفتگو جایی که ما در حال جمع‌آوری نظرات درباره APIهای جدید هستیم.
• PR مربوط به Environment API جایی که 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 اجرا شوند که محدودیت‌های متفاوتی دارند. اپلیکیشن‌های مدرن همچنین ممکن است در بیشتر از دو محیط اجرا شوند، مثلاً یک مرورگر، یک سرور Node و یک سرور لبه. Vite 5 قادر به نمایاندن مناسب این محیط‌ها نبود.

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

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

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

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

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

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

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، در سطح بالا نگه داشته شده‌اند.

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 نام‌گذاری کند.

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

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

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

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

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
• HMR hotUpdate Plugin Hook
• انتقال به API‌های مخصوص هر محیط
• SSR با استفاده از ModuleRunner API
• پلاگین‌های مشترک در طول فرآیند ساخت

کاربران هدف

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

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

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

برای ارائه‌دهندگان رانتایم (Runtime providers)، راهنمای API محیط برای رانتایم توضیح می‌دهد که چگونه می‌توان یک محیط سفارشی را برای استفاده توسط فریم‌ورک‌ها و کاربران ارائه داد.