آموزش Vite در Laravel؛ نصب، پیکربندی و مدیریت فایل‌های فرانت‌اند

در پروژه‌های مدرن وب، مدیریت فایل‌های CSS و JavaScript اهمیت زیادی دارد. زمانی که یک پروژه Laravel را توسعه می‌دهید، ممکن است لازم باشد فایل‌های استایل، کدهای JavaScript، کتابخانه‌های فرانت‌اند و ابزارهایی مانند Tailwind CSS را به شکل اصولی مدیریت کنید.

لاراول برای انجام این کار از Vite پشتیبانی می‌کند. Vite ابزاری برای توسعه فرانت‌اند است که فرایند اجرای کدها در محیط توسعه و آماده‌سازی فایل‌های نهایی برای انتشار را ساده‌تر می‌کند.

در این مقاله یاد می‌گیریم Vite چیست، چگونه در Laravel کار می‌کند، چطور فایل‌های CSS و JavaScript را به صفحات Blade متصل کنیم و چگونه خطاهای رایج آن را برطرف کنیم.

Vite چیست و چه کاربردی در Laravel دارد؟

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

در پروژه Laravel، معمولاً فایل‌های CSS و JavaScript در پوشه resources قرار می‌گیرند. Vite این فایل‌ها را مدیریت می‌کند و هنگام ساخت نسخه نهایی، خروجی مناسب برای استفاده در محیط عملیاتی را تولید می‌کند.

مهم‌ترین کاربردهای Vite در Laravel عبارت‌اند از:

• مدیریت فایل‌های CSS و JavaScript پروژه
• مشاهده سریع تغییرات هنگام توسعه
• پشتیبانی از قابلیت Hot Module Replacement یا HMR
• آماده‌سازی فایل‌های بهینه‌شده برای محیط production
• مدیریت وابستگی‌های فرانت‌اند از طریق npm
• فراهم کردن زیرساخت مناسب برای استفاده از ابزارهایی مانند Vue و React

تفاوت Vite با روش سنتی بارگذاری فایل‌ها

در روش سنتی، ممکن است فایل‌های CSS و JavaScript را مستقیماً از پوشه public در صفحات HTML بارگذاری کنید. این روش برای پروژه‌های کوچک قابل استفاده است، اما با افزایش تعداد فایل‌ها، مدیریت وابستگی‌ها و نسخه‌های مختلف فایل‌ها دشوارتر می‌شود.

در روش مبتنی بر Vite، فایل‌های اصلی در پوشه resources قرار می‌گیرند و ابزار ساخت، خروجی نهایی را تولید می‌کند. در محیط production نیز Laravel از اطلاعات manifest برای شناسایی فایل‌های ساخته‌شده استفاده می‌کند.

پیش‌نیازهای استفاده از Vite در Laravel

برای استفاده از Vite در یک پروژه Laravel، به موارد زیر نیاز دارید:

1. یک پروژه Laravel که به‌درستی نصب شده باشد.
2. نصب بودن Node.js و npm.
3. نصب وابستگی‌های فرانت‌اند پروژه.
4. آشنایی اولیه با فایل‌های Blade و ساختار پوشه‌های Laravel.

برای بررسی نسخه‌های نصب‌شده، ترمینال را باز کنید و دستورات زیر را اجرا کنید:

node -v

npm -v

اگر هر دو دستور نسخه نصب‌شده را نمایش دهند، می‌توانید به مرحله بعد بروید. در غیر این صورت، ابتدا باید Node.js و npm را نصب یا به‌روزرسانی کنید.

بررسی ساختار Vite در پروژه Laravel

در پروژه‌های استاندارد Laravel که از Vite استفاده می‌کنند، معمولاً ساختار زیر را مشاهده می‌کنید:

project/

├── app/

├── public/

│   └── build/

├── resources/

│   ├── css/

│   │   └── app.css

│   ├── js/

│   │   └── app.js

│   └── views/

│       └── welcome.blade.php

├── package.json

├── vite.config.js

└── ...

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

• resources/css/app.css: فایل اصلی استایل‌های پروژه
• resources/js/app.js: فایل اصلی JavaScript پروژه
• vite.config.js: تنظیمات مربوط به Vite
• package.json: فهرست وابستگی‌ها و اسکریپت‌های npm
• public/build: محل معمول خروجی نسخه production

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

نصب و راه‌اندازی Vite در Laravel

اگر پروژه شما از ابتدا با ساختار استاندارد Laravel ایجاد شده باشد، معمولاً فایل‌های تنظیمات و وابستگی‌های لازم Vite از قبل در پروژه وجود دارند. بنابراین پیش از نصب مجدد، ابتدا فایل‌های package.json و vite.config.js را بررسی کنید.

مرحله اول: نصب وابستگی‌های فرانت‌اند

وارد پوشه اصلی پروژه شوید؛ همان پوشه‌ای که فایل package.json در آن قرار دارد.

سپس اجرا کنید:

npm install

این دستور وابستگی‌های تعریف‌شده در package.json را نصب می‌کند.

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

مرحله دوم: بررسی فایل package.json

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

{

    "scripts": {

        "dev": "vite",

        "build": "vite build"

    }

}

این بخش دو دستور اصلی را در اختیار شما قرار می‌دهد:

• npm run dev: اجرای سرور توسعه Vite
• npm run build: ساخت فایل‌های نهایی برای انتشار

اگر package.json شما اسکریپت‌های دیگری دارد، آن‌ها را حذف نکنید. فقط مطمئن شوید دستورات موردنیاز پروژه تعریف شده‌اند.

مرحله سوم: بررسی پیکربندی vite.config.js

فایل vite.config.js تنظیمات مربوط به ورودی‌ها و افزونه‌های Vite را مشخص می‌کند.

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

import { defineConfig } from 'vite';

import laravel from 'laravel-vite-plugin';



export default defineConfig({

    plugins: [

        laravel({

            input: [

                'resources/css/app.css',

                'resources/js/app.js',

            ],

            refresh: true,

        }),

    ],

});

در این تنظیمات:

• laravel-vite-plugin ارتباط Vite با Laravel را فراهم می‌کند.
• input فایل‌هایی را مشخص می‌کند که باید به‌عنوان ورودی فرایند ساخت استفاده شوند.
• refresh: true امکان تازه‌سازی مرورگر هنگام تغییر برخی فایل‌های پروژه را فراهم می‌کند.

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

اتصال Vite به صفحات Blade

پس از پیکربندی Vite، باید فایل‌های موردنیاز را در قالب‌های Blade بارگذاری کنید.

برای این کار از دستور @vite استفاده می‌شود.

برای مثال، فایل resources/views/welcome.blade.php را باز کنید و در بخش head قالب، کد زیر را قرار دهید:

<!DOCTYPE html>

<html lang="fa" dir="rtl">

<head>

    <meta charset="UTF-8">

    <meta name="viewport" content="width=device-width, initial-scale=1.0">



    <title>آموزش Vite در Laravel</title>



    @vite([

        'resources/css/app.css',

        'resources/js/app.js'

    ])

</head>

<body>

    <h1>سلام، به پروژه Laravel خوش آمدید!</h1>

</body>

</html>

دستور @vite با توجه به محیط اجرا، فایل‌های مناسب را بارگذاری می‌کند. در محیط توسعه، این دستور با سرور توسعه Vite ارتباط برقرار می‌کند و در محیط production از فایل‌های ساخته‌شده استفاده می‌کند.

در نتیجه، لازم نیست آدرس فایل‌های خروجی را در تمام قالب‌های پروژه به‌صورت دستی تغییر دهید.

استفاده از Vite در قالب اصلی پروژه

اگر چندین صفحه Blade دارید، بهتر است یک قالب اصلی برای آن‌ها ایجاد کنید. سپس دستور @vite را فقط در همان قالب قرار دهید تا صفحات مختلف بتوانند از آن استفاده کنند.

برای نمونه:

{{-- resources/views/layouts/app.blade.php --}}



<!DOCTYPE html>

<html lang="fa" dir="rtl">

<head>

    <meta charset="UTF-8">

    <meta name="viewport" content="width=device-width, initial-scale=1.0">



    <title>@yield('title', 'پنل سایت')</title>



    @vite([

        'resources/css/app.css',

        'resources/js/app.js'

    ])

</head>

<body>

    @yield('content')

</body>

</html>

صفحه‌ای که از این قالب استفاده می‌کند، می‌تواند به شکل زیر نوشته شود:

@extends('layouts.app')



@section('title', 'صفحه اصلی')



@section('content')

    <h1>صفحه اصلی سایت</h1>

    <p>این صفحه از فایل‌های مدیریت‌شده توسط Vite استفاده می‌کند.</p>

@endsection

این ساختار باعث می‌شود مدیریت فایل‌های فرانت‌اند در صفحات مختلف پروژه ساده‌تر شود.

اجرای Vite در محیط توسعه

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

در ترمینال و پوشه اصلی پروژه دستور زیر را اجرا کنید:

npm run dev

با اجرای این دستور، Vite شروع به کار می‌کند و آدرس سرور توسعه را در ترمینال نمایش می‌دهد.

تا زمانی که در حال توسعه هستید، این فرایند باید فعال بماند. اگر آن را متوقف کنید، ممکن است صفحه Laravel نتواند فایل‌های فرانت‌اند را از سرور توسعه دریافت کند.

قابلیت HMR در Vite چیست؟

HMR مخفف Hot Module Replacement است. این قابلیت کمک می‌کند تغییرات فایل‌های فرانت‌اند با سرعت بیشتری در مرورگر اعمال شوند، بدون اینکه برای هر تغییر مجبور باشید تمام فرایند ساخت را دوباره انجام دهید.

برای مثال، فرض کنید در فایل زیر یک قانون CSS اضافه می‌کنید:

/* resources/css/app.css */



body {

    font-family: sans-serif;

    background: #f5f5f5;

}



h1 {

    color: #2563eb;

}

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

البته نحوه اعمال تغییرات به نوع فایل و ابزارهای مورد استفاده بستگی دارد. برای بعضی تغییرات JavaScript ممکن است بارگذاری مجدد صفحه انجام شود.

ساخت فایل‌های نهایی برای محیط production

اجرای npm run dev برای توسعه مناسب است؛ اما برای انتشار پروژه، معمولاً باید نسخه نهایی فایل‌های فرانت‌اند را بسازید.

برای این کار اجرا کنید:

npm run build

این دستور فایل‌های ورودی را پردازش می‌کند و خروجی موردنیاز محیط production را می‌سازد.

در پیکربندی استاندارد Laravel، خروجی معمولاً در مسیر زیر قرار می‌گیرد:

public/build/

├── assets/

└── manifest.json

نام و ساختار دقیق فایل‌ها به نسخه Vite و تنظیمات پروژه بستگی دارد.

تفاوت npm run dev و npm run build

در سرور عملیاتی، نباید به فعال بودن سرور توسعه Vite وابسته باشید. فایل‌های خروجی build باید همراه نسخه منتشرشده پروژه در دسترس باشند.

اگر فرایند انتشار شما از CI/CD یا Docker استفاده می‌کند، بهتر است ساخت فایل‌ها در مرحله build انجام شود و خروجی تولیدشده به همراه نسخه برنامه منتشر شود.

استفاده از فایل‌های CSS و JavaScript در Vite

یکی از مزیت‌های Vite این است که می‌توانید فایل‌های اصلی فرانت‌اند را از طریق ورودی‌های مشخص مدیریت کنید.

اضافه کردن CSS

برای اضافه کردن استایل‌های جدید، می‌توانید فایل resources/css/app.css را ویرایش کنید.

برای مثال:

.card {

    padding: 20px;

    border-radius: 12px;

    background: white;

    box-shadow: 0 4px 16px rgb(0 0 0 / 8%);

}



.card-title {

    font-size: 20px;

    font-weight: 700;

}

سپس در قالب Blade از کلاس‌ها استفاده کنید:

<div class="card">

    <h2 class="card-title">عنوان کارت</h2>

    <p>این یک نمونه کارت ساده است.</p>

</div>

اضافه کردن JavaScript

برای اضافه کردن رفتارهای تعاملی، می‌توانید کدهای JavaScript را در resources/js/app.js بنویسید.

برای مثال:

document.addEventListener('DOMContentLoaded', () => {

    const button = document.querySelector('#show-message');



    if (!button) {

        return;

    }



    button.addEventListener('click', () => {

        alert('سلام! فایل JavaScript با موفقیت اجرا شد.');

    });

});

سپس دکمه زیر را در قالب Blade قرار دهید:

<button id="show-message" type="button">

    نمایش پیام

</button>

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

مدیریت تصاویر و فایل‌های استاتیک

در Laravel باید بین فایل‌هایی که به‌صورت مستقیم از مسیر عمومی ارائه می‌شوند و فایل‌هایی که توسط Vite پردازش می‌شوند تفاوت قائل شوید.

اگر تصویر را در پوشه public/images قرار دهید، می‌توانید آن را مستقیماً در Blade فراخوانی کنید:

<img src="{{ asset('images/logo.png') }}" alt="لوگوی سایت">

اما اگر تصویر بخشی از ورودی‌های فرانت‌اند باشد و در فرایند ساخت پردازش شود، می‌توانید آن را از داخل فایل CSS یا JavaScript وارد کنید تا Vite آن را مدیریت کند.

این دو روش کاربردهای متفاوتی دارند. فایل‌هایی مانند لوگوهای عمومی و فایل‌های قابل دسترسی مستقیم معمولاً می‌توانند در public باقی بمانند؛ درحالی‌که فایل‌های وابسته به فرایند ساخت می‌توانند در ساختار resources مدیریت شوند.

استفاده از Vite در پروژه‌های Vue و React

Vite تنها برای پروژه‌های Blade کاربرد ندارد. اگر در پروژه Laravel از Vue یا React استفاده می‌کنید، Vite می‌تواند ابزار اصلی مدیریت فایل‌های فرانت‌اند شما باشد.

برای این کار، علاوه بر پیکربندی Laravel، باید افزونه متناسب با فریم‌ورک موردنظر را نصب و در فایل تنظیمات Vite فعال کنید.

برای مثال، در پروژه React معمولاً از افزونه @vitejs/plugin-react استفاده می‌شود. فایل‌های ورودی نیز باید با ساختار واقعی برنامه React هماهنگ باشند.

نکته مهم این است که صرفاً نصب افزونه React یا Vue به معنای آماده بودن کامل پروژه نیست؛ تنظیم ورودی‌ها، نصب وابستگی‌ها و نحوه اتصال برنامه فرانت‌اند به قالب Laravel نیز باید درست انجام شود.

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

خطاهای رایج Vite در Laravel و روش رفع آن‌ها

هنگام کار با Vite ممکن است با خطاهایی مواجه شوید. در ادامه چند مورد متداول و راه‌حل‌های آن‌ها را بررسی می‌کنیم.

خطای Vite manifest not found

این خطا معمولاً زمانی رخ می‌دهد که Laravel نتواند فایل manifest موردنیاز را در مسیر مورد انتظار پیدا کند.

برای رفع مشکل، ابتدا وارد پوشه اصلی پروژه شوید و وابستگی‌ها را نصب کنید:

npm install

سپس فایل‌های نهایی را بسازید:

npm run build

در ادامه بررسی کنید فایل زیر ایجاد شده باشد:

public/build/manifest.json

اگر همچنان خطا وجود دارد، موارد زیر را بررسی کنید:

• آیا دستور build در پوشه صحیح اجرا شده است؟
• آیا فایل‌های خروجی به سرور عملیاتی منتقل شده‌اند؟
• آیا مسیر خروجی Vite با تنظیمات Laravel هماهنگ است؟
• آیا فایل manifest در نسخه منتشرشده وجود دارد؟
• آیا فرایند انتشار، پوشه public/build را حذف یا نادیده می‌گیرد؟

در محیط Docker یا CI/CD، ممکن است build روی یک مرحله انجام شده باشد اما خروجی آن به image یا نسخه نهایی برنامه منتقل نشده باشد.

خطای npm run dev

اگر اجرای دستور زیر با خطا مواجه می‌شود:

npm run dev

ابتدا مطمئن شوید در پوشه‌ای هستید که فایل package.json در آن قرار دارد.

سپس نسخه Node.js و npm را بررسی کنید:

node -v

npm -v

در ادامه، وجود وابستگی Vite و اسکریپت dev در package.json را بررسی کنید.

اگر پروژه از یک نسخه مشخص Node.js پشتیبانی می‌کند، از نسخه سازگار با همان پروژه استفاده کنید. تغییر تصادفی نسخه‌ها یا حذف فایل lock ممکن است باعث ناسازگاری وابستگی‌ها شود.

تغییرات CSS یا JavaScript در مرورگر نمایش داده نمی‌شوند

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

1. آیا npm run dev در حال اجرا است؟
2. آیا فایل موردنظر در input فایل vite.config.js تعریف شده یا از ورودی اصلی وارد شده است؟
3. آیا دستور @vite در قالب Blade قرار دارد؟
4. آیا مرورگر فایل‌های قدیمی را از کش دریافت می‌کند؟
5. آیا خطایی در کنسول مرورگر یا ترمینال Vite وجود دارد؟

همچنین مطمئن شوید در محیط production پس از تغییر فایل‌های فرانت‌اند، build جدید ایجاد و منتشر شده باشد.

تفاوت تنظیمات محیط توسعه و production

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

اگر فایل موقتی public/hot باقی مانده باشد، Laravel ممکن است تصور کند سرور توسعه همچنان فعال است. در صورت مشاهده چنین وضعیتی، ابتدا مطمئن شوید فرایند Vite واقعاً متوقف شده است؛ سپس در صورت باقی ماندن فایل قدیمی، آن را بررسی و با رعایت ساختار انتشار پروژه حذف کنید.

از حذف فایل‌ها یا پوشه‌های عمومی پروژه بدون بررسی خودداری کنید؛ مخصوصاً اگر در همان مسیر فایل‌های دیگری مانند تصاویر آپلودشده کاربران قرار دارند.

بهترین روش‌ها برای استفاده از Vite در Laravel

برای اینکه مدیریت فایل‌های فرانت‌اند در پروژه شما ساده‌تر و مطمئن‌تر باشد، نکات زیر را رعایت کنید:

• فایل‌های CSS و JavaScript را بر اساس نقش و کاربردشان سازمان‌دهی کنید.
• تنظیمات فعلی vite.config.js را پیش از هر تغییر بررسی کنید.
• از npm run dev برای توسعه و از npm run build برای ساخت نسخه نهایی استفاده کنید.
• فایل‌های خروجی موردنیاز را در فرایند انتشار پروژه لحاظ کنید.
• وابستگی‌های پروژه را با فایل lock مدیریت کنید تا نصب‌ها قابل تکرار باشند.
• فایل‌های استاتیک عمومی را از فایل‌هایی که باید توسط Vite پردازش شوند، تفکیک کنید.
• در پروژه‌های چندبخشی، ورودی‌های Vite را به شکل مشخص و قابل نگهداری تعریف کنید.
• در صورت استفاده از React، Vue یا Tailwind CSS، نسخه‌ها و تنظیمات سازگار را مطابق ساختار پروژه انتخاب کنید.

سؤالات متداول درباره Vite در Laravel

آیا Vite به‌صورت پیش‌فرض در Laravel نصب است؟

در پروژه‌های استاندارد و جدید Laravel، معمولاً پیکربندی و وابستگی‌های لازم Vite وجود دارند. بااین‌حال، وضعیت پروژه‌های قدیمی یا پروژه‌هایی که از قالب سفارشی استفاده می‌کنند ممکن است متفاوت باشد.

آیا برای اجرای Laravel باید همیشه npm run dev فعال باشد؟

خیر. این دستور برای محیط توسعه است. در محیط production معمولاً باید فایل‌های نهایی را با npm run build تولید کنید و آن‌ها را همراه نسخه منتشرشده پروژه قرار دهید.

آیا می‌توان بدون Vite از CSS و JavaScript در Laravel استفاده کرد؟

بله. می‌توانید فایل‌های عمومی را مستقیماً از پوشه public بارگذاری کنید. اما در پروژه‌هایی که به مدیریت وابستگی‌ها، HMR و فرایند ساخت نیاز دارند، Vite امکانات کاربردی‌تری ارائه می‌دهد.

آیا Vite فقط برای React و Vue است؟

خیر. Vite برای مدیریت فایل‌های فرانت‌اند در پروژه‌های مبتنی بر Blade نیز کاربرد دارد و می‌تواند بدون استفاده از React یا Vue به کار گرفته شود.

چرا بعد از انتشار پروژه خطای manifest not found نمایش داده می‌شود؟

معمولاً فایل manifest ساخته نشده، در مسیر مورد انتظار قرار ندارد یا در فرایند انتشار به سرور منتقل نشده است. اجرای build و بررسی مسیر public/build/manifest.json نقطه شروع مناسبی برای عیب‌یابی است.

جمع‌بندی

Vite یکی از ابزارهای مهم در توسعه فرانت‌اند با Laravel است که مدیریت فایل‌های CSS و JavaScript را ساده‌تر می‌کند. با استفاده از پیکربندی مناسب، دستور @vite در قالب‌های Blade و دستورات npm run dev و npm run build می‌توانید فرایند توسعه و انتشار فایل‌های فرانت‌اند را به شکل منظم مدیریت کنید.

اگر قصد دارید پروژه‌های حرفه‌ای Laravel، پنل‌های مدیریت یا برنامه‌های مبتنی بر React و Vue بسازید، آشنایی با Vite به شما کمک می‌کند ساختار فرانت‌اند پروژه را بهتر مدیریت کنید.