Skip to content

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:

bash
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:

bash
npm i -D vite @leafphp/vite-plugin
bash
pnpm i -D vite @leafphp/vite-plugin
bash
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:

bash
leaf install vite
bash
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:

blade
{{ vite('css/app.css') }}
php
<?php echo vite('css/app.css'); ?>

You can also load multiple assets at once by passing in an array of assets:

blade
{{ vite(['app.css', 'app.js']) }}
php
<?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:

vite.config.js
js
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:

php
\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:

bash
leaf view:dev
bash
npm i && npm run dev
bash
pnpm i && pnpm run dev
bash
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:

js
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.

Released under the MIT License.