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

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

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.

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:

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

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

<?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 for Vite. With this, you can set a couple of defaults for your assets.

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

Once again if you're using Leaf MVC or if you installed Vite using the view:install command, this is done for you automatically.

Running Vite

Vite comes with a development server that you can use to serve your assets. This is true for the Leaf Vite integration as well. 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 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.