Vite + Leaf
Vite is a modern build tool for frontend applications. It aims to provide a faster and leaner development experience for modern web projects.
Leaf provides a Vite integration which you can use to seamlessly bundle your CSS and JS assets. This allows you to have more complex frontend setups without the need for extra configuration.
New to bundling?
Check out these articles from SitePoint and Next JS:
Setting Up
You can install the Vite module with the Leaf CLI:
leaf view:install --vite
This command will install vite and the vite-leaf plugin, and will also install the vite module which will be used to load your assets on the server side. It will also create a vite config file at the root of your project. This config file can be used to configure vite, add plugins and more.
If you are using Leaf MVC, all of this is done for you automatically. You just need to start your Vite server and add your assets.
Manually Installing Vite
If you don't have the Leaf CLI installed, you can manually install Vite although it's a bit more complex. First, you need to install all the JavaScript dependencies:
npm i -D vite @leafphp/vite-plugin
pnpm i -D vite @leafphp/vite-plugin
yarn add -D vite @leafphp/vite-plugin
After that, you need to install the server component for Vite. This will allow you to load your assets on the server side using PHP. You can install this by running:
leaf install vite
composer require leafs/vite
Finally, Vite requires a configuration file to run. You can create a vite.config.js
file at the root of your project and add your configuration there. You can learn more about Vite configuration files here.
Loading your assets
Once you've installed Vite, you can start loading your assets using the the vite()
helper function. This function takes in 2 parameters:
- The path to your asset
- The folder to load the asset from (optional, defaults to the assets path in leaf config or
app/views
if not set)
Here's an example of how you can load a CSS file:
{{ vite('css/app.css') }}
<?php echo vite('css/app.css'); ?>
You can also load multiple assets at once by passing in an array of assets:
{{ vite(['app.css', 'app.js']) }}
<?php echo vite(['app.css', 'app.js']); ?>
The vite()
helper function will automatically load the correct assets depending on the environment. In development, it will load the assets from the vite server with Hot Module Replacement, while in production, it will load the assets from the build folder.
Vite Config
Vite uses a vite.config.js
file to configure your Vite setup. This file can be used to configure Vite, add plugins and more. Here's an example of a Vite config file:
import { defineConfig } from 'vite';
import leaf from '@leafphp/vite-plugin';
export default defineConfig({
plugins: [
leaf({
input: [
'path/to/entrypoint.css',
'path/to/entrypoint.js'
],
refresh: true
})
]
});
The Leaf Vite plugin requires an array of entry points for your application. These may be JavaScript or CSS files, and include preprocessed languages such as TypeScript, JSX, and Sass. You don't need to pass all your assets here, just the entry points.
Besides the Vite config file, you can also configure the server component to set a few defaults for Vite. This is is only necessary if you are NOT using Leaf MVC. You can configure the server component by calling the config
method on the Vite
class:
\Leaf\Vite::config([
'assets' => 'app/views',
'build' => 'public/build'
]);
Unlike the vite.config.js
file, this configuration is done in PHP and is completely optional.
Running Vite
Vite comes with a development server that you can use to serve your frontend assets. This is a bit different from the traditional way of serving assets with PHP because you need to run a separate server for your assets. You can start your Vite server by running:
leaf view:dev
npm i && npm run dev
pnpm i && pnpm run dev
yarn && yarn dev
This will install the necessary dependencies and start your Vite server. You don't need to do anything with the Vite server, just keep it running in the background and Leaf will take care of the rest.
You need to keep the Vite server running in a separate terminal window while you work on your project.
Adding Aliases
Vite allows you to set up aliases for your assets. This can be done by adding an alias
key to your vite config. For example, to set up an alias for the @
symbol, you can do:
import { defineConfig } from 'vite';
import leaf from '@leafphp/vite-plugin';
export default defineConfig({
plugins: [
leaf({
input: [
'path/to/entrypoint.css',
'path/to/entrypoint.js'
],
refresh: true
})
],
resolve: {
alias: {
'@': '/path/to/folder',
}
}
});
Vite + other frameworks
Using a combination of Leaf and Vite, you can use React with your favourite frontend technologies like React, Vue and Svelte. We've added a guide to setting up frontend frameworks using Inertia over here.