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:

• JavaScript Modules: Bundling & Transpiling

• How Next.js Works

Setting Up

Leaf MVC comes with Vite pre-installed, so you only need to start your server and you're good to go. If you are not using Leaf MVC, you can setup Vite using the Leaf CLI:

leaf view:install --vite

This command will install vite, and the leaf-vite module which will be used to load your assets on the server side plus all vite-specific dependencies and config files.

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')

BareUI

<?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'])

BareUI

<?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

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 which is separate from your PHP server. If you use Leaf MVC or the Leaf CLI, this server will be automatically fired up when you run the serve command:

Leaf MVC CLI

php leaf serve

Leaf CLI

leaf serve

Running Vite manually

If you are not using Leaf MVC, you need to start the Vite server manually in a separate terminal process:

Leaf CLI

leaf view:dev

npm

npm i && npm run dev

pnpm

pnpm i && pnpm run dev

yarn

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.

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.

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

npm i -D vite @leafphp/vite-plugin

pnpm

pnpm i -D vite @leafphp/vite-plugin

yarn

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 CLI

leaf install vite

Composer

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.