استقرار Vite در ابران

ابران dependency به vite را تشخیص می‌دهد، برنامه را build می‌کند و پوشه dist را با runtime سبک Caddy ارائه می‌دهد. این مسیر برای SPAهای React، Vue و پروژه‌های static مبتنی بر Vite مناسب است.

۱. build محلی را بررسی کنید

package.json باید script ساخت داشته باشد:

{
  "engines": { "node": "22" },
  "scripts": {
    "build": "vite build"
  }
}

قبل از deploy اجرا کنید:

npm ci
npm run build

خروجی پیش‌فرض باید در dist ساخته شود. اگر build.outDir را تغییر داده‌اید، Generated builder عمومی فعلی راهی برای انتخاب output directory ندارد؛ از Dockerfile صریح استفاده کنید یا خروجی را به dist برگردانید.

۲. متغیرهای frontend را کنترل کنید

Vite فقط متغیرهای دارای پیشوند VITE_ را در کد client در دسترس می‌گذارد. هر مقداری با این پیشوند public و قابل‌مشاهده در browser bundle است.

رمز، API token، پسورد دیتابیس و secretهای server را هرگز با VITE_ تعریف نکنید. برنامه static backend امن برای نگهداری secret ندارد.

مقدارهای ثبت‌شده با abrun app env set در runtime اعمال می‌شوند و generated source build فعلی آن‌ها را به vite build تزریق نمی‌کند. برای آدرس عمومی API، مقدار غیرحساس را در source/config محیط production قرار دهید یا build را با Dockerfile کنترل کنید. گزینه دیگر این است که برنامه static هنگام اجرا یک config عمومی را از endpoint امن backend دریافت کند.

۳. App و health path را تعریف کنید

یک پورت ثابت انتخاب کنید؛ نمونه زیر از 8080 استفاده می‌کند:

abrun app create my-frontend --plan <plan> --port 8080

برای health endpoint اختصاصی، در ریشه repository بنویسید:

runtime:
  port: 8080
  health: /healthz

ابران Caddyfile موقت تولید می‌کند که روی 0.0.0.0 و PORT گوش می‌دهد، /healthz را پاسخ می‌دهد، compression را فعال می‌کند و برای routeهای SPA به index.html fallback دارد.

۴. deploy و بررسی کنید

abrun deploy my-frontend --logs

در build plan باید framework برابر vite، runtime kind برابر static و output برابر dist باشد. پس از Ready، هم صفحه اصلی و هم یک route داخلی مانند /dashboard را مستقیم refresh کنید تا SPA fallback تأیید شود.

Caddyfile سفارشی

اگر repository در ریشه build context فایل Caddyfile داشته باشد، generated static runtime از آن استفاده می‌کند. در این حالت خودتان باید bind address، PORT، health path، file root، compression و SPA fallback را درست نگه دارید. برای نیاز ساده، فایل تولیدشده ابران انتخاب امن‌تری است.

monorepo

abrun deploy my-frontend . --root-directory apps/web

package هدف باید package.json و lockfile قابل‌حل داشته باشد. اگر از workspace dependency استفاده می‌کنید، root workspace و نام package را نیز درست تعریف کنید.

رفع مشکل

• صفحه سفید است: browser console، base path و URL assetهای تولیدشده را بررسی کنید.
• route داخلی 404 می‌شود: Caddyfile سفارشی باید fallback به /index.html داشته باشد.
• env جدید دیده نمی‌شود: مقدار VITE_ build-time است و runtime env ابران وارد bundle قبلی نمی‌شود؛ روش پیکربندی build را اصلاح کنید.
• output پیدا نمی‌شود: خروجی را به dist برگردانید یا Dockerfile سفارشی بسازید.
• Bun تشخیص داده می‌شود: generated Node builder فعلی Bun را پشتیبانی نمی‌کند.

قدم بعدی

• پیکربندی build
• دامنه اختصاصی و TLS
• مراحل و لاگ‌های استقرار
• چک‌لیست production