Vite چیست؟ آموزش کامل Vite با React و ساخت پروژه هوش مصنوعی
در این آموزش Vite را از صفر یاد میگیرید؛ از ساخت پروژه React و تنظیم vite.config.js تا Proxy، متغیرهای محیطی، Build و Code Splitting. در پایان یک اپلیکیشن هوش مصنوعی متصل به API درواره میسازیم.
Vite یکی از پرکاربردترین ابزارهای ساخت و توسعه پروژههای مدرن وب است. اگر اخیراً یک پروژه React، Vue، Svelte یا حتی JavaScript ساده ساخته باشید، احتمالاً با دستور npm create vite@latest روبهرو شدهاید.
اما Vite دقیقاً چیست؟ چه تفاوتی با React، Node.js، npm و Webpack دارد؟ چرا پروژههای جدید از Vite استفاده میکنند؟ فایل vite.config.js چه کاری انجام میدهد؟ چگونه باید متغیرهای محیطی، Proxy، مسیرهای Alias و Build پروژه را تنظیم کرد؟
در این آموزش، Vite را از مفاهیم پایه تا استفاده عملی بررسی میکنیم. در بخش پروژه نیز یک رابط React با Vite میسازیم که از طریق یک Backend امن به API هوش مصنوعی درواره متصل میشود.
Vite چیست؟
Vite یک ابزار توسعه و Build برای پروژههای Frontend است. تلفظ نام آن تقریباً «ویت» است و از واژه فرانسوی بهمعنای «سریع» گرفته شده است.
Vite دو وظیفه اصلی دارد:
- اجرای یک Development Server سریع در زمان توسعه
- ساخت فایلهای بهینهشده برای محیط Production
در زمان توسعه، Vite فایلهای پروژه را با استفاده از قابلیت ES Modules مرورگر ارائه میکند. این رویکرد باعث میشود برای مشاهده اولین صفحه، نیازی به Bundle کردن کامل همه فایلهای پروژه نباشد.
در محیط Production، دستور Build فایلهای JavaScript، CSS و Assetهای پروژه را پردازش، بهینه و برای استقرار آماده میکند.
براساس مستندات رسمی Vite، این ابزار یک Development Server با قابلیت HMR سریع و یک فرمان Build برای تولید فایلهای بهینهشده محیط Production فراهم میکند.
Vite چه چیزی نیست؟
برای درک بهتر Vite، باید آن را از ابزارهایی که معمولاً در کنار آن استفاده میشوند جدا کنیم.
Vite یک فریمورک رابط کاربری نیست
React، Vue و Svelte ابزارهایی برای ساخت رابط کاربری هستند. Vite فریمورک رابط کاربری نیست؛ بلکه محیط توسعه و Build پروژه را فراهم میکند.
برای مثال میتوانید از ترکیبهای زیر استفاده کنید:
- Vite و React
- Vite و Vue
- Vite و Svelte
- Vite و Preact
- Vite و JavaScript خالص
- Vite و TypeScript
Vite جایگزین Node.js نیست
Node.js محیط اجرای JavaScript خارج از مرورگر است. Vite برای اجرا شدن روی سیستم توسعهدهنده به Node.js نیاز دارد.
Vite جایگزین npm نیست
npm یک Package Manager یا مدیر بسته است. با npm وابستگیها را نصب و Scriptهای Vite را اجرا میکنید.
برای مثال:
npm install
npm run dev
npm run build
Vite یک Backend Server نیست
Development Server داخلی Vite برای توسعه Frontend طراحی شده است. نباید آن را بهعنوان Backend اصلی برنامه، محل نگهداری API Key یا سرور Production هوش مصنوعی در نظر بگیرید.
چرا Vite محبوب شده است؟
در پروژههای بزرگ، ابزارهای قدیمیتر ممکن بود قبل از نمایش برنامه، تمام فایلها و وابستگیها را پردازش و Bundle کنند. با بزرگ شدن پروژه، این مرحله میتوانست زمانبر شود.
Vite در زمان توسعه از ES Modules بومی مرورگر استفاده میکند و فایلهای Source را در زمان نیاز ارائه میدهد. در نتیجه، شروع Development Server و مشاهده تغییرات معمولاً سریع است.
مزایای مهم Vite عبارتاند از:
- راهاندازی سریع Development Server
- پشتیبانی از Hot Module Replacement
- پشتیبانی داخلی از TypeScript، JSX و CSS
- امکان استفاده با فریمورکهای مختلف
- پیکربندی نسبتاً ساده
- قابلیت توسعه از طریق Plugin
- تولید Build بهینه برای انتشار
- پشتیبانی از Dynamic Import و Code Splitting
- مدیریت ساده فایلهای Static و Assetها
- پشتیبانی از متغیرهای محیطی و Modeهای مختلف
- قابلیت تعریف Proxy در محیط توسعه
HMR چیست؟
HMR مخفف Hot Module Replacement است. این قابلیت اجازه میدهد هنگام تغییر یک فایل، فقط ماژول مرتبط با آن بهروزرسانی شود.
فرض کنید رنگ یک دکمه را در یک کامپوننت React تغییر میدهید. با HMR معمولاً نیازی نیست کل صفحه از ابتدا بارگذاری شود. Vite ماژول تغییرکرده را به مرورگر ارسال میکند و نتیجه سریعتر نمایش داده میشود.
HMR علاوه بر سرعت، میتواند بخشی از State فعلی برنامه را نیز حفظ کند. البته حفظ State به فریمورک و نوع تغییر انجامشده بستگی دارد.
مقایسه Vite با Webpack
Vite و Webpack هر دو در زنجیره ابزارهای Frontend استفاده میشوند، اما رویکرد یکسانی ندارند.
| معیار | Vite | Webpack |
|---|---|---|
| هدف اصلی | توسعه سریع و Build پروژههای مدرن | Bundling قابلتنظیم برای سناریوهای متنوع |
| شروع پروژه | ساده و سریع | معمولاً نیازمند تنظیمات بیشتر |
| Development Server | مبتنی بر ESM و پردازش در زمان نیاز | معمولاً مبتنی بر Bundle |
| HMR | سریع و آماده استفاده | قدرتمند، وابسته به پیکربندی پروژه |
| تنظیمات اولیه | کم | ممکن است گسترده باشد |
| اکوسیستم | مدرن و روبهرشد | قدیمیتر و بسیار گسترده |
| پروژههای Legacy | همیشه انتخاب اول نیست | در بسیاری از پروژههای قدیمی تثبیت شده |
| یادگیری اولیه | سادهتر | معمولاً پیچیدهتر |
این مقایسه بهمعنای برتری مطلق یکی از آنها نیست. اگر پروژه موجود شما با Webpack پایدار است، مهاجرت فقط بهدلیل محبوبیت Vite همیشه تصمیم مناسبی نیست. اما برای بسیاری از پروژههای جدید React و Vue، Vite انتخاب ساده و کاربردی است.
پیشنیازهای نصب Vite
برای اجرای Vite به نسخه سازگار Node.js نیاز دارید. نسخه موردنیاز ممکن است با انتشار نسخههای جدید تغییر کند؛ بنابراین قبل از شروع، بخش Compatibility Note در راهنمای رسمی نصب Vite را بررسی کنید.
نسخه نصبشده Node.js و npm را با این دستورات ببینید:
node --version
npm --version
اگر Node.js نصب نیست، نسخه LTS آن را از وبسایت رسمی Node.js نصب کنید.
ساخت اولین پروژه Vite با React
برای ساخت یک پروژه React و JavaScript اجرا کنید:
npm create vite@latest vite-ai-app -- --template react
برای ساخت پروژه React و TypeScript:
npm create vite@latest vite-ai-app -- --template react-ts
وارد پوشه پروژه شوید:
cd vite-ai-app
وابستگیها را نصب کنید:
npm install
Development Server را اجرا کنید:
npm run dev
Vite معمولاً یک آدرس محلی مانند زیر نمایش میدهد:
http://localhost:5173
آدرس دقیق را از خروجی Terminal باز کنید.
ساختار پروژه Vite و React
ساختار اولیه پروژه تقریباً به این شکل است:
vite-ai-app/
├── public/
├── src/
│ ├── assets/
│ ├── App.css
│ ├── App.jsx
│ ├── index.css
│ └── main.jsx
├── .gitignore
├── eslint.config.js
├── index.html
├── package-lock.json
├── package.json
└── vite.config.js
فایل index.html
در Vite، فایل index.html در ریشه پروژه قرار دارد و بخشی از Source پروژه محسوب میشود.
این فایل معمولاً شامل عنصر ریشه React و ورودی JavaScript است:
<!doctype html>
<html lang="fa" dir="rtl">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta
name="description"
content="دستیار هوش مصنوعی ساختهشده با React، Vite و API درواره"
/>
<title>دستیار هوش مصنوعی</title>
</head>
<body>
<div id="root"></div>
<script type="module" src="/src/main.jsx"></script>
</body>
</html>
Vite فایل index.html و ارجاعهای آن به JavaScript و CSS را در فرایند توسعه و Build پردازش میکند.
فایل main.jsx
این فایل نقطه شروع برنامه React است:
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import "./index.css";
import App from "./App.jsx";
createRoot(document.getElementById("root")).render(
<StrictMode>
<App />
</StrictMode>
);
فایل App.jsx
کامپوننت اصلی برنامه در این فایل قرار میگیرد:
export default function App() {
return <h1>سلام Vite</h1>;
}
فایل package.json
این فایل اطلاعات پروژه، وابستگیها و Scriptها را نگه میدارد:
{
"scripts": {
"dev": "vite",
"build": "vite build",
"lint": "eslint .",
"preview": "vite preview"
}
}
کاربرد Scriptهای اصلی:
npm run dev: اجرای محیط توسعهnpm run build: ساخت نسخه Productionnpm run preview: پیشنمایش محلی Buildnpm run lint: بررسی خطاها و قواعد کدنویسی
دستور preview سرور Production واقعی نیست و فقط برای بررسی محلی خروجی Build استفاده میشود.
فایل vite.config.js چیست؟
تنظیمات اختصاصی Vite در فایل vite.config.js یا نسخه TypeScript آن یعنی vite.config.ts قرار میگیرد.
یک پیکربندی ساده React:
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
export default defineConfig({
plugins: [react()],
});
تابع defineConfig برای خوانایی بهتر و دریافت پیشنهادهای نوعی در ویرایشگر استفاده میشود.
نمونه کاملتر:
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import path from "node:path";
export default defineConfig({
plugins: [react()],
resolve: {
alias: {
"@": path.resolve(import.meta.dirname, "./src"),
},
},
server: {
port: 5173,
open: true,
proxy: {
"/api": {
target: "http://localhost:3000",
changeOrigin: true,
},
},
},
build: {
outDir: "dist",
sourcemap: false,
},
});
تنظیمات Vite با انتشار نسخههای جدید تکامل پیدا میکنند. مرجع کامل هر گزینه در مستندات Config رسمی Vite قرار دارد.
تعریف Alias برای مسیرها
در پروژههای بزرگ، Importهای نسبی طولانی میشوند:
import Button from "../../../components/ui/Button";
با تعریف Alias میتوان آن را خواناتر کرد:
import Button from "@/components/ui/Button";
تنظیم Alias در vite.config.js:
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import path from "node:path";
export default defineConfig({
plugins: [react()],
resolve: {
alias: {
"@": path.resolve(import.meta.dirname, "./src"),
},
},
});
اگر از TypeScript استفاده میکنید، بهتر است Alias را در tsconfig.json نیز تعریف کنید:
{
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@/*": ["src/*"]
}
}
}
مدیریت فایلهای Static و Assetها
در پروژه Vite دو روش رایج برای استفاده از تصویر، فونت و فایلهای دیگر وجود دارد.
قرار دادن فایل در src
فایلهای داخل src را Import کنید:
import logoUrl from "./assets/logo.png";
export default function Header() {
return <img src={logoUrl} alt="لوگوی برنامه" />;
}
Vite این فایل را در فرایند Build پردازش میکند و در صورت نیاز نام Hashشده برای آن میسازد.
قرار دادن فایل در public
فایلهای پوشه public بدون پردازش در ریشه خروجی کپی میشوند.
برای مثال:
public/favicon.svg
در HTML یا React با این مسیر قابل دسترسی است:
<img src="/favicon.svg" alt="" />
برای Assetهایی که باید توسط Vite پردازش، Hash یا بهینه شوند، Import از src معمولاً انتخاب مناسبتری است.
متغیرهای محیطی در Vite
Vite متغیرهای محیطی سمت Client را از طریق import.meta.env ارائه میکند.
برای مثال فایل .env:
VITE_APP_NAME=دستیار هوش مصنوعی درواره
VITE_API_BASE_URL=/api
استفاده در React:
const appName = import.meta.env.VITE_APP_NAME;
const apiBaseUrl = import.meta.env.VITE_API_BASE_URL;
متغیرهای داخلی پرکاربرد:
console.log(import.meta.env.MODE);
console.log(import.meta.env.DEV);
console.log(import.meta.env.PROD);
console.log(import.meta.env.BASE_URL);
هشدار مهم درباره VITE_
متغیرهایی که با VITE_ شروع میشوند، وارد کد Client میشوند و کاربر میتواند مقدار آنها را مشاهده کند.
بنابراین هرگز موارد زیر را در متغیرهای VITE_ قرار ندهید:
- API Key
- رمز عبور
- توکن دسترسی خصوصی
- کلید دیتابیس
- Client Secret
- اطلاعات محرمانه سازمان
این تنظیم ناامن است:
VITE_DARVAREH_API_KEY=secret-key
حتی اگر فایل .env وارد Git نشود، مقدار کلید هنگام Build داخل کد Frontend قرار میگیرد.
طبق مستندات متغیرهای محیطی Vite، متغیرهای دارای پیشوند VITE_ در کد Client در دسترس قرار میگیرند و نباید حاوی اطلاعات حساس باشند.
فایلهای مختلف محیطی
Vite از فایلهای محیطی مختلف پشتیبانی میکند:
.env
.env.local
.env.development
.env.development.local
.env.production
.env.production.local
کاربرد متداول آنها:
.env: تنظیمات مشترک همه محیطها.env.local: تنظیمات محلی و خارج از Git.env.development: تنظیمات محیط توسعه.env.production: تنظیمات محیط Production
برای مثال:
# .env.development
VITE_API_BASE_URL=/api
# .env.production
VITE_API_BASE_URL=https://example.com/api
برای جلوگیری از ثبت تنظیمات محلی در Git، این مقادیر را در .gitignore قرار دهید:
.env.local
.env.*.local
Mode در Vite چیست؟
دستور vite بهصورت پیشفرض در Mode توسعه اجرا میشود و vite build معمولاً از Mode تولید استفاده میکند.
میتوانید Mode سفارشی تعریف کنید:
vite build --mode staging
سپس فایل زیر خوانده میشود:
.env.staging
نمونه:
VITE_API_BASE_URL=https://staging.example.com/api
Mode با NODE_ENV دقیقاً یک مفهوم نیست. برای تشخیص محیط Vite معمولاً از مقادیر زیر استفاده کنید:
import.meta.env.MODE
import.meta.env.DEV
import.meta.env.PROD
تنظیم Proxy در Vite
در زمان توسعه، Frontend ممکن است روی پورت 5173 و Backend روی پورت 3000 اجرا شود.
بدون Proxy، درخواست مستقیم مرورگر به Backend ممکن است به تنظیم CORS نیاز داشته باشد:
Frontend: http://localhost:5173
Backend: http://localhost:3000
میتوانیم درخواستهای /api را از طریق Development Server به Backend هدایت کنیم:
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
export default defineConfig({
plugins: [react()],
server: {
proxy: {
"/api": {
target: "http://localhost:3000",
changeOrigin: true,
},
},
},
});
حالا Frontend درخواست را به مسیر نسبی میفرستد:
fetch("/api/chat");
Vite آن را در محیط توسعه به آدرس زیر هدایت میکند:
http://localhost:3000/api/chat
جزئیات گزینههایی مانند target، changeOrigin و بازنویسی مسیر در مستندات Server Proxy در Vite توضیح داده شده است.
Proxy فقط برای محیط توسعه است
تنظیم server.proxy در Build نهایی اجرا نمیشود. در محیط Production باید یکی از این راهکارها را انتخاب کنید:
- Frontend و Backend را روی یک دامنه منتشر کنید.
- Reverse Proxy مانند Nginx را تنظیم کنید.
- آدرس عمومی Backend را در تنظیمات Frontend قرار دهید.
- از قابلیت Rewrite یا Proxy سرویس میزبانی استفاده کنید.
ساخت پروژه عملی: دستیار هوش مصنوعی با Vite و React
در این پروژه یک رابط ساده میسازیم که پیام کاربر را دریافت میکند و آن را به Backend میفرستد. Backend درخواست را با API Key خصوصی به API درواره ارسال میکند.
معماری برنامه:
مرورگر و React
|
| POST /api/chat
v
Backend با Node.js و Express
|
| API Key خصوصی
v
API هوش مصنوعی درواره
این ساختار دو مزیت مهم دارد:
- API Key در مرورگر افشا نمیشود.
- اعتبارسنجی، محدودسازی و مدیریت خطا در Backend انجام میشود.
مرحله اول: ساخت Frontend
پروژه را ایجاد کنید:
npm create vite@latest darvareh-vite-app -- --template react
cd darvareh-vite-app
npm install
فایل vite.config.js را به شکل زیر تنظیم کنید:
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
export default defineConfig({
plugins: [react()],
server: {
port: 5173,
proxy: {
"/api": {
target: "http://localhost:3000",
changeOrigin: true,
},
},
},
build: {
outDir: "dist",
sourcemap: false,
},
});
ساخت کامپوننت React
محتوای src/App.jsx را جایگزین کنید:
import { useState } from "react";
import "./App.css";
export default function App() {
const [prompt, setPrompt] = useState("");
const [answer, setAnswer] = useState("");
const [loading, setLoading] = useState(false);
const [error, setError] = useState("");
async function handleSubmit(event) {
event.preventDefault();
const cleanPrompt = prompt.trim();
if (!cleanPrompt) {
setError("لطفاً پیام خود را وارد کنید.");
return;
}
if (cleanPrompt.length > 4000) {
setError("متن واردشده بیش از حد طولانی است.");
return;
}
setLoading(true);
setError("");
setAnswer("");
try {
const response = await fetch("/api/chat", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
message: cleanPrompt,
}),
});
const data = await response.json().catch(() => null);
if (!response.ok) {
throw new Error(
data?.error || "دریافت پاسخ از سرویس با خطا روبهرو شد."
);
}
setAnswer(data.answer);
} catch (requestError) {
setError(
requestError instanceof Error
? requestError.message
: "خطای پیشبینینشدهای رخ داد."
);
} finally {
setLoading(false);
}
}
return (
<main className="app">
<section className="assistant">
<header className="assistant__header">
<span className="assistant__badge">Vite + React</span>
<h1>دستیار هوش مصنوعی</h1>
<p>
پرسش خود را بنویسید تا درخواست از طریق Backend امن به API
درواره ارسال شود.
</p>
</header>
<form className="assistant__form" onSubmit={handleSubmit}>
<label htmlFor="prompt">پیام شما</label>
<textarea
id="prompt"
value={prompt}
onChange={(event) => setPrompt(event.target.value)}
placeholder="برای مثال: این مفهوم برنامهنویسی را با یک مثال توضیح بده."
rows="7"
disabled={loading}
/>
<div className="assistant__actions">
<span>{prompt.length.toLocaleString("fa-IR")} کاراکتر</span>
<button type="submit" disabled={loading || !prompt.trim()}>
{loading ? "در حال دریافت پاسخ..." : "ارسال پیام"}
</button>
</div>
</form>
{error && (
<div className="message message--error" role="alert">
{error}
</div>
)}
{answer && (
<section className="message message--answer" aria-live="polite">
<h2>پاسخ</h2>
<p>{answer}</p>
</section>
)}
</section>
</main>
);
}
طراحی رابط کاربری
محتوای src/App.css:
:root {
color: #172033;
background: #f4f3ff;
font-family:
Vazirmatn, IRANSans, system-ui, -apple-system, BlinkMacSystemFont,
"Segoe UI", sans-serif;
}
* {
box-sizing: border-box;
}
body {
margin: 0;
min-width: 320px;
min-height: 100vh;
}
button,
textarea {
font: inherit;
}
.app {
min-height: 100vh;
display: grid;
place-items: center;
padding: 32px 16px;
background:
radial-gradient(circle at top right, #d9d2ff 0, transparent 32%),
linear-gradient(135deg, #f8f7ff, #eef2ff);
}
.assistant {
width: min(760px, 100%);
padding: 32px;
border: 1px solid #dedaf4;
border-radius: 24px;
background: rgba(255, 255, 255, 0.92);
box-shadow: 0 20px 60px rgba(53, 36, 125, 0.12);
}
.assistant__header h1 {
margin: 12px 0 8px;
font-size: clamp(1.8rem, 5vw, 2.8rem);
}
.assistant__header p {
margin: 0;
color: #5e6474;
line-height: 1.9;
}
.assistant__badge {
display: inline-flex;
padding: 6px 12px;
border-radius: 999px;
color: #5b38d1;
background: #eee9ff;
font-weight: 700;
}
.assistant__form {
display: grid;
gap: 12px;
margin-top: 28px;
}
.assistant__form label {
font-weight: 700;
}
.assistant__form textarea {
width: 100%;
resize: vertical;
padding: 16px;
border: 1px solid #cbc7de;
border-radius: 14px;
color: #172033;
background: #fff;
line-height: 1.8;
outline: none;
}
.assistant__form textarea:focus {
border-color: #7653e8;
box-shadow: 0 0 0 4px rgba(118, 83, 232, 0.12);
}
.assistant__actions {
display: flex;
align-items: center;
justify-content: space-between;
gap: 16px;
}
.assistant__actions span {
color: #73798a;
font-size: 0.9rem;
}
.assistant__actions button {
padding: 11px 20px;
border: 0;
border-radius: 12px;
color: #fff;
background: #6842df;
cursor: pointer;
}
.assistant__actions button:disabled {
opacity: 0.55;
cursor: not-allowed;
}
.message {
margin-top: 20px;
padding: 18px;
border-radius: 14px;
line-height: 1.9;
white-space: pre-wrap;
}
.message--error {
color: #8c1d2c;
background: #fff0f2;
}
.message--answer {
color: #283046;
background: #f1efff;
}
.message--answer h2 {
margin-top: 0;
font-size: 1.1rem;
}
.message--answer p {
margin-bottom: 0;
}
@media (max-width: 600px) {
.assistant {
padding: 22px;
border-radius: 18px;
}
.assistant__actions {
align-items: stretch;
flex-direction: column;
}
.assistant__actions button {
width: 100%;
}
}
در src/index.css نیز تنظیمات پیشفرض قالب را حذف کنید تا با CSS جدید تداخل نداشته باشد:
html {
direction: rtl;
}
body {
margin: 0;
}
مرحله دوم: ساخت Backend امن
در ریشه پروژه، پوشهای به نام server بسازید:
mkdir server
cd server
npm init -y
npm install express dotenv
برای استفاده از ES Modules، فایل server/package.json را ویرایش کنید:
{
"name": "darvareh-vite-backend",
"version": "1.0.0",
"private": true,
"type": "module",
"scripts": {
"dev": "node --watch server.js",
"start": "node server.js"
},
"dependencies": {
"dotenv": "^16.0.0",
"express": "^5.0.0"
}
}
شماره نسخههای نصبشده ممکن است با زمان انتشار مقاله متفاوت باشد. فایل package-lock.json نسخه دقیق وابستگیهای پروژه شما را ثبت میکند.
تنظیم متغیرهای محرمانه Backend
در پوشه server فایل .env بسازید:
DARVAREH_API_KEY=YOUR_DARVAREH_API_KEY
DARVAREH_MODEL_ID=YOUR_MODEL_ID
PORT=3000
شناسه مدل مناسب و اطلاعات بهروز مدلها را از صفحه مدلهای درواره دریافت کنید.
فایل .env را به Git اضافه نکنید. در .gitignore ریشه پروژه بنویسید:
node_modules
dist
.env
.env.local
.env.*.local
server/.env
برای مشخص کردن متغیرهای موردنیاز بدون افشای مقدار واقعی، فایل server/.env.example بسازید:
DARVAREH_API_KEY=YOUR_DARVAREH_API_KEY
DARVAREH_MODEL_ID=YOUR_MODEL_ID
PORT=3000
پیادهسازی مسیر API
فایل server/server.js را ایجاد کنید:
import "dotenv/config";
import express from "express";
const app = express();
const port = Number(process.env.PORT || 3000);
app.disable("x-powered-by");
app.use(express.json({ limit: "32kb" }));
app.get("/api/health", (request, response) => {
response.json({
status: "ok",
});
});
app.post("/api/chat", async (request, response) => {
const message =
typeof request.body?.message === "string"
? request.body.message.trim()
: "";
if (!message) {
return response.status(400).json({
error: "متن پیام الزامی است.",
});
}
if (message.length > 4000) {
return response.status(400).json({
error: "طول پیام بیشتر از مقدار مجاز است.",
});
}
const apiKey = process.env.DARVAREH_API_KEY;
const modelId = process.env.DARVAREH_MODEL_ID;
if (!apiKey || !modelId) {
console.error("Darvareh configuration is missing.");
return response.status(500).json({
error: "تنظیمات سرویس کامل نیست.",
});
}
try {
const upstreamResponse = await fetch(
"https://api.darvareh.ir/v1/chat/completions",
{
method: "POST",
headers: {
Authorization: `Bearer ${apiKey}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
model: modelId,
messages: [
{
role: "system",
content:
"شما یک دستیار فارسی دقیق و کاربردی هستید. پاسخها را روشن و ساختاریافته بنویسید.",
},
{
role: "user",
content: message,
},
],
temperature: 0.4,
}),
}
);
const data = await upstreamResponse.json().catch(() => null);
if (!upstreamResponse.ok) {
console.error("Darvareh API error:", {
status: upstreamResponse.status,
details: data,
});
return response.status(502).json({
error: "سرویس هوش مصنوعی در حال حاضر پاسخ معتبری برنگرداند.",
});
}
const answer = data?.choices?.[0]?.message?.content;
if (typeof answer !== "string" || !answer.trim()) {
return response.status(502).json({
error: "ساختار پاسخ سرویس قابل پردازش نبود.",
});
}
return response.json({
answer: answer.trim(),
});
} catch (error) {
console.error("Unexpected server error:", error);
return response.status(500).json({
error: "ارتباط با سرویس هوش مصنوعی برقرار نشد.",
});
}
});
app.listen(port, () => {
console.log(`Backend is running on http://localhost:${port}`);
});
در این نمونه:
- API Key فقط در Backend نگهداری میشود.
- ورودی کاربر قبل از ارسال بررسی میشود.
- محدودیت اندازه JSON اعمال شده است.
- خطای داخلی سرویس مستقیماً به کاربر نمایش داده نمیشود.
- پاسخ API قبل از استفاده اعتبارسنجی میشود.
- Frontend فقط به مسیر محلی
/api/chatدرخواست میفرستد.
اجرای کامل پروژه
در Terminal اول، Backend را اجرا کنید:
cd server
npm run dev
در Terminal دوم، از ریشه پروژه Frontend را اجرا کنید:
npm run dev
سپس آدرس نمایشدادهشده توسط Vite را در مرورگر باز کنید.
برای بررسی مستقیم سلامت Backend:
curl http://localhost:3000/api/health
پاسخ مورد انتظار:
{
"status": "ok"
}
برای آزمایش مسیر Chat بدون رابط کاربری:
curl -X POST http://localhost:3000/api/chat \
-H "Content-Type: application/json" \
-d '{"message":"Vite را در سه جمله توضیح بده."}'
اجرای همزمان Frontend و Backend
برای راحتی توسعه میتوانید پکیج concurrently را در ریشه پروژه نصب کنید:
npm install -D concurrently
سپس Scriptهای package.json ریشه را تنظیم کنید:
{
"scripts": {
"dev": "vite",
"dev:server": "npm --prefix server run dev",
"dev:all": "concurrently \"npm run dev\" \"npm run dev:server\"",
"build": "vite build",
"preview": "vite preview",
"lint": "eslint ."
}
}
اکنون هر دو بخش با یک دستور اجرا میشوند:
npm run dev:all
Build گرفتن از پروژه Vite
برای ساخت نسخه Production اجرا کنید:
npm run build
Vite بهصورت پیشفرض خروجی را در پوشه dist قرار میدهد:
dist/
├── assets/
├── index.html
└── ...
برای بررسی محلی Build:
npm run preview
جزئیات مربوط به خروجی Production، تنظیم Target و گزینههای Build در راهنمای رسمی Building for Production آمده است.
انتشار Frontend و Backend روی یک سرور
یک راه ساده این است که Express فایلهای Buildشده Frontend را نیز ارائه کند.
ابتدا در ریشه پروژه Build بگیرید:
npm run build
سپس در server/server.js ماژولهای موردنیاز را Import کنید:
import path from "node:path";
import { fileURLToPath } from "node:url";
بعد از تعریف مسیرهای API و قبل از app.listen این بخش را اضافه کنید:
const currentFile = fileURLToPath(import.meta.url);
const currentDirectory = path.dirname(currentFile);
const frontendDirectory = path.resolve(currentDirectory, "../dist");
app.use(express.static(frontendDirectory));
app.get("/{*path}", (request, response) => {
response.sendFile(path.join(frontendDirectory, "index.html"));
});
اکنون Backend هم API را ارائه میکند و هم فایلهای Buildشده Frontend را در اختیار مرورگر قرار میدهد.
در محیط واقعی بهتر است موارد زیر نیز متناسب با زیرساخت پروژه تنظیم شوند:
- HTTPS
- Rate Limiting
- محدودیت زمان درخواست
- ثبت Log استاندارد
- Health Check
- سیاست CORS
- اعتبارسنجی دقیق ورودی
- محدودیت مصرف هر کاربر
- مدیریت خطا و مانیتورینگ
- Cache Header برای Assetهای Hashشده
Code Splitting در Vite
اگر تمام بخشهای برنامه در Bundle اولیه قرار بگیرند، حجم JavaScript اولیه افزایش پیدا میکند. با Dynamic Import میتوان بعضی بخشها را فقط هنگام نیاز بارگذاری کرد.
مثال در React:
import { lazy, Suspense } from "react";
const SettingsPanel = lazy(() => import("./SettingsPanel.jsx"));
export default function App() {
return (
<Suspense fallback={<p>در حال بارگذاری تنظیمات...</p>}>
<SettingsPanel />
</Suspense>
);
}
این روش میتواند برای بخشهایی مانند موارد زیر مفید باشد:
- پنل مدیریت
- صفحه تنظیمات
- ویرایشگرهای بزرگ
- نمودارها
- بخش گزارشگیری
- قابلیتهایی که همه کاربران در اولین ورود نیاز ندارند
هر فایل را بدون دلیل جدا نکنید. تعداد زیاد Chunkهای کوچک نیز میتواند تعداد درخواستها و پیچیدگی بارگذاری را افزایش دهد.
بارگذاری تنبل براساس رویداد
برای یک کتابخانه سنگین که فقط بعد از کلیک کاربر لازم است:
async function exportReport() {
const module = await import("./reportExporter.js");
await module.exportReport();
}
در این حالت کد reportExporter.js تا زمان اجرای تابع بارگذاری نمیشود.
تنظیم manualChunks
در پروژههای خاص میتوانید نحوه تقسیم Chunkها را کنترل کنید. این کار باید پس از بررسی واقعی خروجی Build انجام شود، نه صرفاً براساس حدس.
یک نمونه پیکربندی:
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
export default defineConfig({
plugins: [react()],
build: {
rollupOptions: {
output: {
manualChunks: {
react: ["react", "react-dom"],
},
},
},
},
});
بسته به نسخه Vite و موتور Build فعال، جزئیات پیکربندی میتواند تغییر کند. قبل از اعمال تنظیمات پیشرفته، مستندات نسخه مورداستفاده و نتیجه واقعی Bundle Analysis را بررسی کنید.
تنظیم مسیر Base
اگر پروژه در ریشه دامنه منتشر میشود، تنظیم پیشفرض مناسب است:
https://example.com/
اما اگر برنامه در یک زیرمسیر قرار میگیرد:
https://example.com/dashboard/
مقدار base را تنظیم کنید:
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
export default defineConfig({
base: "/dashboard/",
plugins: [react()],
});
برای مسیر نسبی در بعضی استقرارها میتوان از این مقدار استفاده کرد:
export default defineConfig({
base: "./",
});
انتخاب base به نوع میزبانی، Routing و مسیر عمومی پروژه بستگی دارد.
Source Map در Vite
Source Map به توسعهدهنده کمک میکند خطاهای کد Minifyشده را به Source اصلی مرتبط کند.
فعالسازی:
export default {
build: {
sourcemap: true,
},
};
Source Map برای Debug و ابزارهای مانیتورینگ مفید است، اما انتشار عمومی آن ممکن است مشاهده Source اصلی را سادهتر کند.
گزینه مناسب را براساس نیاز پروژه انتخاب کنید:
export default {
build: {
sourcemap: "hidden",
},
};
در این حالت فایل Source Map ساخته میشود، اما ارجاع آن مستقیماً به Bundle اضافه نمیشود. برای استفاده عملی معمولاً باید Mapها را در ابزار مانیتورینگ آپلود و از انتشار عمومی آنها جلوگیری کنید.
استفاده از چند صفحه HTML
Vite فقط برای Single Page Application نیست و میتواند چند ورودی HTML داشته باشد.
ساختار نمونه:
project/
├── index.html
├── about/
│ └── index.html
├── contact/
│ └── index.html
└── src/
هر صفحه میتواند Script و Style اختصاصی خود را داشته باشد. برای پروژههای پیچیدهتر، ورودیهای Build را نیز میتوان بهصورت صریح تنظیم کرد.
Plugin در Vite چیست؟
Plugin قابلیتهای جدیدی به Vite اضافه میکند. برای مثال Plugin رسمی React، تبدیل JSX و قابلیتهای مرتبط با React را فعال میکند:
npm install -D @vitejs/plugin-react
پیکربندی:
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
export default defineConfig({
plugins: [react()],
});
هنگام انتخاب Plugin:
- مستندات آن را بررسی کنید.
- وضعیت نگهداری پروژه را ببینید.
- تعداد وابستگیها را بیدلیل افزایش ندهید.
- از Pluginهای ناشناس برای پردازش اطلاعات حساس استفاده نکنید.
- نسخهها را در فایل Lock ثبت کنید.
- Plugin بدون استفاده را حذف کنید.
بهینهسازی عملکرد پروژه Vite
Vite بهصورت پیشفرض سریع است، اما تنظیمات نامناسب میتوانند سرعت توسعه یا Build را کاهش دهند.
Pluginهای اضافی را حذف کنید
هر Plugin میتواند در پردازش فایلها دخالت کند. فقط Pluginهایی را نگه دارید که واقعاً لازماند.
Importهای بزرگ را کنترل کنید
بهجای Import کل کتابخانه، در صورت پشتیبانی کتابخانه فقط بخش لازم را وارد کنید:
import debounce from "lodash/debounce";
بهجای:
import _ from "lodash";
این رفتار به ساختار بسته و پشتیبانی آن از Tree Shaking نیز بستگی دارد.
وابستگیهای تکراری را بررسی کنید
npm dedupe
npm ls
خروجی Build را ببینید
پس از Build، Vite اندازه Assetها را نمایش میدهد:
npm run build
اگر Chunk بزرگی دارید، بررسی کنید:
- آیا کتابخانه سنگینی وارد شده است؟
- آیا آن قابلیت در صفحه اول لازم است؟
- آیا میتوان از Dynamic Import استفاده کرد؟
- آیا چند نسخه از یک وابستگی نصب شده است؟
- آیا فایل تصویر یا فونت بیش از حد بزرگ است؟
تصاویر را بهینه کنید
برای تصاویر مناسب وب:
- ابعاد را متناسب با محل نمایش انتخاب کنید.
- از فرمتهای مناسب مانند WebP یا AVIF استفاده کنید.
- برای تصاویر پایین صفحه Lazy Loading فعال کنید.
- متن جایگزین مناسب بنویسید.
<img
src={imageUrl}
alt="نمای رابط دستیار هوش مصنوعی"
loading="lazy"
/>
خطاهای رایج Vite و راهحل آنها
خطای npm create vite اجرا نمیشود
ابتدا نسخه Node.js و npm را بررسی کنید:
node --version
npm --version
اگر نسخه Node.js قدیمی است، آن را به نسخه سازگار ارتقا دهید.
پورت 5173 اشغال است
پورت دیگری تعیین کنید:
npm run dev -- --port 5174
یا در Config:
export default {
server: {
port: 5174,
},
};
اگر میخواهید Vite در صورت اشغال بودن پورت متوقف شود:
export default {
server: {
port: 5173,
strictPort: true,
},
};
متغیر محیطی undefined است
موارد زیر را بررسی کنید:
- نام متغیر با
VITE_شروع شده است. - فایل
.envدر ریشه Frontend قرار دارد. - پس از تغییر
.env، Development Server را دوباره اجرا کردهاید. - از
process.envبهجایimport.meta.envاستفاده نکردهاید.
در Frontend:
const value = import.meta.env.VITE_API_BASE_URL;
Proxy کار نمیکند
بررسی کنید:
- Backend روی پورت صحیح اجرا شده باشد.
targetدرست باشد.- درخواست Frontend با
/apiشروع شود. - پس از تغییر
vite.config.js، Vite را Restart کرده باشید.
نمونه درست:
fetch("/api/chat");
صفحه پس از انتشار سفید است
علتهای متداول:
- مقدار نادرست
base - مسیر اشتباه Assetها
- نبود Rewrite برای React Router
- خطای JavaScript در مرورگر
- تفاوت متغیرهای محیط توسعه و Production
کنسول مرورگر و بخش Network را بررسی کنید.
صفحه React در Refresh خطای 404 میدهد
اگر از Client-side Routing استفاده میکنید، سرور باید مسیرهای ناشناخته را به index.html برگرداند. این موضوع به تنظیمات سرویس میزبانی یا Backend مربوط است و با Development Server Vite متفاوت است.
تغییرات نمایش داده نمیشوند
موارد زیر را امتحان کنید:
- Development Server را Restart کنید.
- Cache مرورگر را بررسی کنید.
- خطاهای Terminal را بخوانید.
- مطمئن شوید فایل درست را ویرایش میکنید.
- Pluginهای مرورگر را موقتاً غیرفعال کنید.
- پوشه Cache وابستگیهای Vite را فقط در صورت نیاز بررسی یا پاکسازی کنید.
نکات امنیتی پروژههای Vite
Vite یک ابزار امنیتی نیست. استفاده از آن بهتنهایی برنامه را امن نمیکند.
برای پروژههایی که به API هوش مصنوعی متصل میشوند:
- API Key را فقط در Backend قرار دهید.
- اطلاعات محرمانه را در
VITE_ذخیره نکنید. - ورودی کاربر را در Backend اعتبارسنجی کنید.
- محدودیت اندازه درخواست اعمال کنید.
- برای مسیرهای عمومی Rate Limit در نظر بگیرید.
- خطای داخلی و اطلاعات حساس را به Client ارسال نکنید.
- متغیرهای محیطی واقعی را وارد Git نکنید.
- وابستگیها را از منابع معتبر نصب کنید.
- دسترسی کاربران را در سمت سرور کنترل کنید.
- میزان مصرف API را ثبت و پایش کنید.
- خروجی مدل را در کاربردهای حساس بدون بررسی استفاده نکنید.
چکلیست آمادهسازی برای Production
پیش از انتشار پروژه این موارد را بررسی کنید:
npm run buildبدون خطا اجرا میشود.npm run previewخروجی مورد انتظار را نمایش میدهد.- API Key در Bundle Frontend وجود ندارد.
- فایلهای
.envواقعی وارد Git نشدهاند. - آدرس Backend در محیط Production صحیح است.
- HTTPS فعال است.
- خطاها بدون افشای جزئیات داخلی مدیریت میشوند.
- مسیرهای SPA روی سرور Rewrite شدهاند.
- Assetهای بزرگ بهینه شدهاند.
- صفحات روی موبایل آزمایش شدهاند.
- وضعیت Loading و Error در رابط کاربری وجود دارد.
- درخواست تکراری هنگام Loading کنترل شده است.
- لاگ و مانیتورینگ Backend فعال است.
- محدودیت مصرف و هزینه API تعریف شده است.
- مدل مناسب براساس کیفیت، سرعت و هزینه انتخاب شده است.
برای مشاهده مدلهای قابلاستفاده، شناسه مدل و اطلاعات بهروز قیمت، صفحه مدلهای درواره را بررسی کنید.
چه زمانی از Vite استفاده کنیم؟
Vite برای این پروژهها انتخاب مناسبی است:
- اپلیکیشن React جدید
- داشبورد مدیریتی
- رابط کاربری سرویس هوش مصنوعی
- Single Page Application
- نمونه اولیه سریع
- پروژه Vue یا Svelte
- پنل داخلی سازمان
- Frontend متصل به REST API
- وباپلیکیشن TypeScript
- کتابخانه Frontend
چه زمانی Vite بهتنهایی کافی نیست؟
Vite فقط ابزار توسعه و Build Frontend است. اگر پروژه به این قابلیتها نیاز دارد، ابزارهای دیگری نیز لازم خواهند بود:
- اجرای کد امن سمت سرور
- نگهداری API Key
- اتصال مستقیم به دیتابیس
- احراز هویت سمت سرور
- پردازش پرداخت
- Jobهای زمانبر
- Webhook
- Rate Limiting
- Server-side Rendering
- تولید صفحه پویا روی سرور
- صف پردازش و Worker
برای چنین سناریوهایی میتوانید Vite را برای Frontend و یک Backend مانند Node.js، Express، FastAPI یا ASP.NET Core را برای منطق سمت سرور به کار ببرید.
آیا برای استفاده از Vite باید React بلد باشیم؟
خیر. Vite از قالب JavaScript خالص نیز پشتیبانی میکند:
npm create vite@latest vanilla-app -- --template vanilla
نسخه TypeScript:
npm create vite@latest vanilla-ts-app -- --template vanilla-ts
React فقط یکی از فریمورکهایی است که میتوان همراه Vite استفاده کرد.
آیا Vite برای پروژههای بزرگ مناسب است؟
بله، Vite میتواند در پروژههای بزرگ استفاده شود، اما عملکرد نهایی فقط به Build Tool وابسته نیست. معماری کد، تعداد وابستگیها، Pluginها، نحوه تقسیم Bundle، تست، Routing، مدیریت State و زیرساخت انتشار نیز مهماند.
برای پروژه بزرگ بهتر است:
- ساختار ماژولار تعریف کنید.
- وابستگیها را کنترل کنید.
- Build را در CI اجرا کنید.
- اندازه Bundle را پایش کنید.
- برای صفحات سنگین Code Splitting در نظر بگیرید.
- از تنظیمات پیچیده بدون نیاز واقعی اجتناب کنید.
- زمان Build و عملکرد مرورگر را با داده واقعی اندازهگیری کنید.
آیا Vite برای SEO مناسب است؟
Vite بهخودیخود ابزار SEO نیست. یک برنامه React که فقط در مرورگر Render میشود ممکن است برای بعضی صفحات محتوایی، نیازهای متفاوتی نسبت به یک سایت دارای Server-side Rendering یا Static Generation داشته باشد.
برای داشبوردها و ابزارهای تعاملی، Client-side Rendering معمولاً قابلقبول است. برای سایتهای محتوایی که ترافیک ارگانیک اهمیت زیادی دارد، باید موارد زیر را نیز بررسی کنید:
- HTML اولیه صفحه
- عنوان و Meta Description
- Canonical URL
- Structured Data
- سرعت بارگذاری
- لینکهای داخلی
- Sitemap
- دسترسی خزندهها به محتوا
- Server-side Rendering یا Static Generation
- کیفیت واقعی و غیرتکراری محتوا
بنابراین انتخاب Vite یا هر Build Tool دیگری بهتنهایی تضمینکننده رتبه یا ایندکس شدن نیست.
پرسشهای متداول
Vite را چگونه تلفظ کنیم؟
تلفظ رایج آن «ویت» و نزدیک به واژه انگلیسی veet است.
آیا Vite رایگان است؟
Vite یک پروژه متنباز است. بااینحال هزینه زیرساخت، میزبانی، Backend و سرویسهای API پروژه جداگانه محاسبه میشود.
آیا Vite بدون npm کار میکند؟
Vite را میتوان با Package Managerهای مختلف اجرا کرد، اما در اکوسیستم Node.js معمولاً از npm، pnpm، Yarn یا Bun استفاده میشود.
تفاوت npm run dev و npm run build چیست؟
npm run dev محیط توسعه را با HMR اجرا میکند. npm run build فایلهای بهینهشده قابلانتشار را در پوشه خروجی میسازد.
آیا npm run preview برای Production مناسب است؟
خیر. vite preview برای بررسی محلی Build طراحی شده است و جایگزین سرور Production نیست.
آیا میتوان API Key را در فایل .env پروژه Vite قرار داد؟
اگر متغیر با VITE_ شروع شود و در Frontend استفاده شود، مقدار آن وارد کد Client خواهد شد. کلید خصوصی باید در محیط Backend نگهداری شود.
چرا از process.env استفاده نمیکنیم؟
در کد Client پروژه Vite، متغیرهای محیطی معمولاً از طریق import.meta.env خوانده میشوند:
const apiUrl = import.meta.env.VITE_API_BASE_URL;
آیا Proxy Vite در Production هم کار میکند؟
خیر. server.proxy مربوط به Development Server است. Proxy یا مسیر Backend محیط Production باید جداگانه پیکربندی شود.
چگونه مدل هوش مصنوعی را عوض کنیم؟
در پروژه نمونه، مقدار DARVAREH_MODEL_ID را در فایل .env سمت Backend تغییر دهید:
DARVAREH_MODEL_ID=YOUR_MODEL_ID
شناسه درست مدل و اطلاعات قیمت را از صفحه مدلهای درواره بردارید.
جمعبندی
Vite یک Build Tool مدرن برای توسعه Frontend است که راهاندازی سریع، HMR، پشتیبانی از JavaScript و TypeScript، مدیریت Assetها، متغیرهای محیطی، Pluginها و Build بهینه را در اختیار توسعهدهنده قرار میدهد.
مهمترین نکاتی که باید به خاطر داشته باشید:
- Vite فریمورک رابط کاربری یا Backend نیست.
- React و Vite نقشهای متفاوتی دارند.
npm run devبرای توسعه وnpm run buildبرای ساخت خروجی است.- فایل
vite.config.jsبرای تنظیم Plugin، Proxy، Alias و Build استفاده میشود. - متغیرهای دارای پیشوند
VITE_محرمانه نیستند. - API Key هوش مصنوعی باید در Backend نگهداری شود.
- Proxy داخلی Vite فقط در محیط توسعه فعال است.
- برای انتشار باید خروجی Build و Backend را بهدرستی پیکربندی کنید.
اگر میخواهید یک اپلیکیشن React، دستیار متنی، ابزار تولید محتوا یا سرویس مبتنی بر مدلهای هوش مصنوعی بسازید، میتوانید از Vite برای Frontend و API هوش مصنوعی درواره برای دسترسی برنامهنویسی به مدلها استفاده کنید.
مقالات مرتبط
- آموزش ساخت چتبات هوش مصنوعی با Next.js، React و API درواره
- آموزش Node.js و Express برای اتصال به API هوش مصنوعی درواره
- ساخت اپلیکیشن هوش مصنوعی با Vue.js و Nuxt
- ساخت اپلیکیشن هوش مصنوعی با Angular و TypeScript
- ساخت اپلیکیشن هوش مصنوعی با Svelte و SvelteKit
- آموزش JSON در Python، JavaScript و APIهای هوش مصنوعی
- آموزش HTTP، متدها و Status Codeهای API
- ساخت افزونه Chrome با JavaScript و API درواره
- ساخت اپلیکیشن Desktop با Electron و API درواره
منابع تکمیلی
- راهنمای شروع Vite
- تنظیمات Vite
- متغیرهای محیطی و Modeها در Vite
- تنظیمات Development Server و Proxy
- راهنمای Build برای Production
برای مطالعه شرایط استفاده و محدودیتهای مسئولیت، صفحه «سلب مسئولیت» را مشاهده کنید.