Laravel VILTify is a heavily opinionated Laravel starter kit. It's intent is to seamlessly integrate Vue, Inertia.js, Laravel, TailwindCSS and Vuetify, so you don't waste your time learning how to do it and focus on writing your application, leaving setup behind.

• Requirements

• Quick start

• Troubleshooting

• Why would I use this instead of Laravel Breeze or Laravel Jetstream?

  • Vue CLI instead of Laravel Mix
  • Vuetify's full power in your hands
  • No conflicts between Vuetify and TailwindCSS classes
  • Inertia.js conveniences
    • The v-link global component
    • Server driven toast notifications
  • Resonable defaults with production builds in mind
    • Code Splitting out of the box
    • Material Design Icons JS SVG instead of WebFont
  • Separeted builds for different endpoints
  • Isolated client side environment settings

• Drawbacks

• License

• Operating System: This package should work on MacOS and Linux. If you're using Windows, you're gonna need WSL.

• Laravel 9

• Vue CLI: Under the hood, this package will call the Vue CLI tool. Make sure you have Vue CLI V5 installed before continuing. If you don't, the installation is fairly simple.

HEADS UP: this package is meant to be used ONLY ON FRESH LARAVEL INSTALLATIONS.

# Create a new Laravel project
composer create-project laravel/laravel my-app

# Enter the project folder
cd my-app

# Install Laravel VILTify
composer require dalpizzol/laravel-viltify

# Create your base tables
php artisan migrate

# Run the installer
php artisan viltify:install

# Remove the package so you don't accidentally run it again in the future
composer remove dalpizzol/laravel-viltify

# Enter the resources folder
cd resources

# Lift the assets devserver
npm run serve

# Lift the PHP server in another terminal
# (if you're not already running one)
php artisan serve

HEADS UP:

Be aware that you're running two servers, just like when you use Laravel Mix. Your PHP application runs at port 80 while the devserver runs at 8080. So, in your browser, you navigate to your PHP application at port 80, for instance: https://localhost.

In some scenarios, if you're using Node.js 17.x.x or higher, you might encounter an ERR_OSSL_EVP_UNSUPPORTED error when running the resources/package.json scripts, like npm run serve or npm run build.

This is related to changes introduced by Node.js 17 and you can read more about this here, here, and here.

You don't need to downgrade Node.js. Instead, just prepend NODE_OPTIONS=--openssl-legacy-provider to your resources/package.json scripts:

// resources/package.json

{
  scripts: {
    "serve": "NODE_OPTIONS=--openssl-legacy-provider vue-cli-service serve",
    "build": "NODE_OPTIONS=--openssl-legacy-provider vue-cli-service build"
  }
}

This package is actually heavily based on Laravel Breeze. A lot of code was simply ripped off from that. But there's some advantages here:

This package actually turns your resources folder into a Vue app generated by Vue CLI. This means that inside resources you can do things like vue add some-vue-cli-plugin which you can't when using Laravel Mix. Vue CLI is also much more stable than Laravel Mix and much more focused and battle tested for use with Vue, so you are probably going to save some time avoiding common issues related to Laravel Mix.

This also allows you to use Vue CLI's GUI inside resources, if that's your thing...

While official Laravel starter kits delivers a dozen Vue components, they are fairly simple. Laravel VILTify comes with Vuetify UI component library already installed and configured so you can take advantage of 70+ highly customizable, responsive and beautiful components based on Google's Material Design.

Laravel VILTify comes with Vuetify and TailwindCSS already configured so you can use both without worrying about class collisions. All you have to do is to prefix your tailwind classes with tw-.

Laravel VILTify offers a globally registered v-link component which is a Vuetify v-btn component wrapped by an Inertia.js Link component. This way you can use Inertia.js links everywhere without having to remember to include the Link component locally on every component and they can use every style available to v-btn components. Inertia's Link component is also registered globally.

<v-link :href="someUrl"
  color="success"
  rounded
  outlined
  x-large
>
  This is an Inertia.js link rendered as a Vuetify Button
</v-link>

It also ships with a server driven toast notification system specifically crafted to work nicely with Inertia.js. This means you can do things like this:

// Success message
return redirect()
  ->route('dashboard')
  ->toast('Laravel VILTify is awesome');

// Error message
return redirect()
  ->route('dashboard')
  ->toast('You didn\'t give Laravel VILTify a star. =(', 'error');

Another cool feature it offers are validation toasts. This is usefull when you have some "invisible data" on a form that may not be valid. For instance, a reCaptcha V3 token. Since there's no visible form element for the token, you may want to toast the validation error if the token validation fails.

Toast::validation('recaptcha_token');

request()->validate([
  'recaptcha_token',
  // ...
]);

// It also accepts an array:
// Toast::validation(['recaptcha_token', 'another_field'])

Make sure you call Toast::validation before you actually run your validations.

Since we're dealing with SPAs, Laravel VILTify makes sure that code splitting takes place. All the files needed by any route are loaded on demand by default.

By default Vuetify comes configured to use @mdi/js instead of a regular WebFont, so it enforces that you only ever load the icons you really need. Learn more here.

If you need a separate build for an entirely different endpoint, for instance, an admin area, follow these steps:

1. Duplicate resources/src/templates/app.blade.php and rename it to resources/src/templates/app-admin.blade.php. This will be your Inertia's rootView.

2. Create a new entry in the pages prop at resources/vue.config.js.

  pages: {
    ...page('main', 'app'),
    ...page('admin', 'app-admin')
  },

  // The following disables prefetch links generation for each endpoint
  chainWebpack: config => {
    config.plugins.delete('prefetch-main'),
    config.plugins.delete('prefetch-admin')
  }

3. Duplicate the resources/src/main.js and rename it to resources/src/admin.js.

4. Then, you need to instruct Inertia to use the app-admin.blade.php view when rendering an admin page.

return Inertia::setRootView('app-admin')
  ->render('admin/Dashboard');

When using Laravel Mix, client side environment settings are put into MIX_ prefixed variables inside .env file. Here, since our resources folder is actually a Vue CLI generated app, you can leverage the pattern shipped by Vue CLI do deal with environment variables. Laravel VILTify comes out of the box with a resources/.env.local for the devserver and a resources/.env.production example file, so you can deal with every client side setting separated from Laravel settings.

Since the intent here is to use Vuetify, we're still using Vue 2 and Webpack instead of Vue 3 and Vite, since Vuetify support for Vue 3 hasn't released yet.

This software is provided free of charge and without restriction under the MIT License