DEV Community: Matheus Dal'Pizzol

Introducing Laravel VILTify: a Vue CLI & Vuetify powered alternative to Breeze for the VILT stack

Matheus Dal'Pizzol — Wed, 15 Dec 2021 13:29:06 +0000

Some time ago I wrote about how to integrate Laravel with a Vue app generated by the Vue CLI and how to integrate all of that with Inertia.js. That was fine and I use that setup to this day. But back then, my intent was to document what I needed to do when I was starting a new project with Laravel and wanted to replace Laravel Mix with Vue CLI.

Now, there are two more tools that I always use on my projects: Vuetify and TailwindCSS. And, off course, I also need to set those up, making sure that their classes don't clash and do some Vuetify configuration as well, like replacing Material Design Icon's WebFont by it's JavaScript SVG alternative.

On top of that, there are some Inertia.js conveniences that I'd like to have, like global Inertia Link components and a Vuetify Button alternative that supports Inertia Link. A server driven toast notification system that plays well with Inertia and Vuetify together would also be nice.

So... Here it is:

Laravel VILTify

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.

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

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

Vue CLI instead of Laravel Mix

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

Vuetify's full power in your hands

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.

The perfect Marriage between Vuetify and TailwindCSS

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

Inertia.js conveniences

The v-link global component

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
</v-link>

Server driven toast notifications

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

Easily create custom endpoints

If you need a separate build for an entirely different endpoint, for instance, and admin area, you can use 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')
  }

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

Isolated client side environment settings

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.

Resonable defaults with production builds in mind

Code Splitting out of the box

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.

Material Design Icons JS SVG instead of WebFont

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.

Is there any drawbacks to this?

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

Another thing is that since we're using Vue CLI v4, it uses PostCSS 7, and newer versions of Tailwind requires PostCSS 8. Because of that, we can't use recently released TailwindCSS v3, and when using ^v2.1 we can't use JIT mode. HOWEVER, since we're using Vuetify, TailwinCSS will probably be used sparingly. So, chances are that this will not be a HUGE problem.

Conclusion

So, that's it! Hope you enjoy the package and feel free to give feedback.

Integrate Laravel and Inertia.js with a Vue CLI app

Matheus Dal'Pizzol — Wed, 26 May 2021 23:28:18 +0000

What is Inertia.js

Inertia.js was invented to integrate backend frameworks Like Laravel and Rails with modern frontend frameworks like React, Vue and Svelte and building SPAs without the need for a backend API nor a client-side router. I became a fan of the project and I'm using it with Vue.js.

Why do we need this tutorial though?

Now, if you blindly follow the instructions at Inertia's client-side setup page, you'll find that it only covers its installation with Code Splitting enabled using Laravel Mix. Although I'm a Jeffrey Way (the author of Laravel Mix) fan - I'm still subscribed at Laracasts, he's learning platform - and I understand the intent of Laravel Mix, my experience with it is that when it comes to advanced usage, you'll quickly find yourself wasting days (yes, I had that experience), fighting Webpack configurations and finding out that the problems come down to multiple outdated dependencies and stuff like that.

On the other hand, Vue CLI always made my life easier. I have absolutely nothing bad to say about it. Everything always works as expected (at least for me, at least until now).

So, I wanted to use Inertia.js with a Vue CLI app.

Heads up

Now, this article will be short and easy, but this is because we already did the heavy lifting in a previews article on how to integrate Laravel with a Vue CLI app with Hot Module Replacement. If you missed that, go ahead and follow that step by step until you get to the Routing section. Feel free to read that section there, if you want, but it's not a requirement for this tutorial.

Setting up the client-side

Install Inertia.js adapter for Vue.js:

cd resources
npm install @inertiajs/inertia @inertiajs/inertia-vue
cd ../

Create a page component at resources/src/pages:

mkdir resources/src/pages
nano resources/src/pages/Home.vue

// resources/src/pages/Home.vue

<template>
  <h1>Hello from Home</h1>
</template>

<script>
export default {}
</script>

Edit your main.js file to use the Inertia App component and to load page components from the proper directory:

// resources/src/main.js

import Vue from 'vue'
import { App, plugin } from '@inertiajs/inertia-vue'

Vue.config.productionTip = false

Vue.use(plugin)

const el = document.getElementById('app')

new Vue({
  render: h => h(App, {
    props: {
      initialPage: JSON.parse(el.dataset.page),
      resolveComponent: name => import('@/pages/' + name + '.vue').then(module => module.default)
    }
  })
}).$mount(el)

Edit resources/src/template.blade.php replacing <div id="app"></div> with the @inertia Blade directive:

<!-- ... -->
<body>
  <!-- ... -->
  @inertia
  <!-- built files will be auto injected -->
</body>

Setting up the server-side

Install Inertia's server side adapter:

composer require inertiajs/inertia-laravel

Publish and register the Inertia middleware:

php artisan inertia:middleware

// app/Http/Kernel.php

'web' => [
    // ...
    \App\Http\Middleware\HandleInertiaRequests::class,
],

Create a configuration file for Inertia based on the contents of the config file on the official repo and set page_paths properly:

nano config/inertia.php

// config/inertia.php

return [

    /*
    |--------------------------------------------------------------------------
    | Inertia
    |--------------------------------------------------------------------------
    |
    | The values described here are used to locate Inertia components on the
    | filesystem. For instance, when using `assertInertia`, the assertion
    | attempts to locate the component as a file relative to any of the
    | paths AND with any of the extensions specified here.
    |
    */

    'testing' => [      
        'ensure_pages_exist' => true,
        'page_paths' => [
            resource_path('src/pages'),
        ],
        'page_extensions' => [
            'js',
            'svelte',
            'ts',
            'vue',
        ],
    ],
];

Setup a route and you're good to go

// routes/web.php

use Illuminate\Support\Facades\Route;
use Inertia\Inertia;

Route::get('/', function () {
    return Inertia::render('Home');
});

And that's it!

Article repo

I've made a GitHub repo with all of this work done for you to clone and see things working for yourself.

DON'T FORGET TO CREATE YOUR resources/.env.local FILE AND SET THE VUE_APP_ASSET_URL ENVIRONMENT VARIABLE

Conclusion

As you can see, we're not locked up with Laravel Mix in order to use Inertia.js. With some efort we can use Inertia.js in conjunction with a Vue CLI app.

IMO, this is the best setup I've ever worked with in almost 14 years working with web development. What do you think? Hope you enjoy it as much as I do. Cheers!

Integrate Laravel with a Vue CLI app with Hot Module Replacement and no backend API

Matheus Dal'Pizzol — Wed, 26 May 2021 23:26:12 +0000

Every time someone wants to use a Vue.js app generated by the Vue CLI with Laravel, there's always that "YOU'RE GONNA NEED A BACKEND API" guy to crush your hopes and make you feel bad/sad. Well, there's nothing wrong with that approach. But every time I hear that, I always ask myself: WHY? Why do I need to use Laravel only as a backend API just because I'm going to use Vue CLI to serve my assets?

Sometimes it seems like people get stuck in a box of how things MUST be done and simply forget how the web works.

Let's stop for a second...

Think about what the npm run serve from Vue CLI does.

It grabs some code, compiles it, lifts up a simple web server and delivers the compiled assets.

Did you notice something? it LIFTS UP a server and it DELIVERS assets. Isn't that what we do when we serve static assets from a CDN for our app? We have a server up, somewhere, that delivers static assets. That's all.

And NO ONE, EVER came down to you saying: "Oh, your serving static assets, now you need a backend API." I think you'll agree with me that this would be nonsense.

So, at the end, it seems that people forgot that when you do npm run serve and get Webpack DevServer running at http://localhost:8080, it's just like serving your assets from a CDN.

Ok! I Get it, but...

Now I see, but there's this: Vue CLI is the one responsible for generating and serving MY HTML PAGE with all the hashed .js and .css file references. THAT'S why we serve the Vue CLI result upfront and use the Laravel app as a backend API, right?

Right, but what exactly is stopping us from using the HTML page generated by Vue CLI as a view for Laravel to render instead?

Let's start from there...

Where should I create the Vue CLI app?

That's your choice, but the way I like to go about this is to make my resources folder the Vue app.

Backup your resources folder to resources-bkp.
Create the Vue app as a new resources folder
Place your resources/lang back to where it belongs
Create a new empty resources/views directory
Create a resources/vue.config.js file
If there's nothing important at resources-bkp, delete it

mv resources resources-bkp
vue create resources
mv resources-bkp/lang resources/lang
mkdir resources/views
nano resources/vue.config.js
rm -rf resources-bkp

NOTICE: Keep in mind that, from now on, all of your npm commands must be run at the resources folder. I usually save some time by keeping 2 terminals open on my VSCode workspace: one at the project root and another at the resources folder. This way I can run commands at the project root (php artisan, composer) without having to stop the DevServer running on a separate terminal.

Make a base Blade template

Move your resources/public/index.html inside resources/src/ and rename it to template.blade.php.

mv resources/public/index.html resources/src/template.blade.php

Separating development and production builds

The HTML generated during development will be different from the one generated for production. For example, link and script tags will have distinct base URLs depending on the environment:

<!-- development -->
<link href="http://localhost:8080/css/0.d09619e2.css" rel="prefetch">
<script type="text/javascript" src="http://localhost:8080/js/chunk-vendors.js"></script>

<!-- production -->
<link href="https://assets.mywebapp.com/css/0.d04519e3.css" rel="prefetch">
<script type="text/javascript" src="https://assets.mywebapp.com/js/chunk-vendors.a07692ee.js"></script>

So, we need to keep them separated. During development, we're going to put the generated views at resources/views/devserver/, while in production, at resources/views/.

We don't want to check in which environment we are every time we need to render a view. So, instead of cluttering our code with if statements, we're gonna change our view paths config at configs/view.php.

This way, during development, Laravel will first lookup for views inside resources/views/devserver/, only if it can't find it there, it will look at resources/views/.

// config/view.php

    'paths' => (env('APP_ENV', 'production') === 'local')
        ? [
            resource_path('views/devserver'),
            resource_path('views')
        ]
        : [
            resource_path('views')
        ],

We also don't want to commit our development views to our repository, so, add the path to your .gitignore file.

# .gitignore
/resources/views/devserver

Regarding our assets, we're gonna dump them at public/dist/. During development, however, they are going to be served directly from memory by Webpack DevServer.

Configuring Vue CLI properly

Here's the Vue CLI config we'll need. I commented it in details.

const path = require('path')

let environmentViewsDirectory = ''
let outputDir = 'dist/'

/**
 * This is a precaution
 * In case we accidentally write dev-server files to disk,
 * we're not going to mess with our production ready dist folder
 */
if (process.env.NODE_ENV === 'development') {
  environmentViewsDirectory = 'devserver/'
  outputDir = 'dist-devserver/'
}

/**
 * A helper function to create Vue CLI page entries
 * @param {string} name The name of the JavaScript entry point for the page
 * @param {string} outputPath The path to the resulting HTML Blade file without the extension
 * @param {string} template An optional template file to be used as base for the Blade view
 * @returns 
 */
const page = (name, outputPath, template) => {
  return {
    [name]: {
      entry: `src/${name}.js`,
      filename: path.resolve(__dirname, `views/${environmentViewsDirectory}${outputPath}.blade.php`),
      template: template || 'src/template.blade.php'
    }
  }
}

module.exports = {
  /**
   * If you're not aiming for a SPA
   * You can add as many pages here as you want
   * as long as you create an entry .js file at resources/src/
   * You can also use this to create a separate template for an admin endpoint or any other endpoint you need
   */
  pages: {
    ...page('main', 'app'),
    // ...page('contact', 'contact'),
    // ...page('admin', `admin`),
  },
  // Where to dump resulting files
  outputDir: `../public/${outputDir}`,
  // The URL from which assets will be served
  // AND WHICH will be used by injected assets inside the HTML
  publicPath: process.env.VUE_APP_ASSET_URL,
  css: {
    extract: (process.env.NODE_ENV === 'development')
      ? {
        filename: 'css/[name].css'
      }
      : true
  },
  devServer: {
    // Public needs to be explicitly set since we're not using the defaults
    public: process.env.VUE_APP_ASSET_URL,
    // During development, we want to write ONLY the HTML files to the disk
    // This is needed because Laravel won't be able to read the view directly from memory
    // But we want our .js and .css assets to still be served directly from memory
    // So, we're writing to disk ONLY if the output file is at views/devserver/
    writeToDisk: (filePath) => {
      return /views\/devserver\//.test(filePath);
    },
    // Allows you to point any host to the devserver port.
    // Eg.: http://assets.localhost:8080 will also work
    // Alternatively you could use the "allowedHosts" option
    disableHostCheck: true,
    // Avoid CORS issues
    headers: {
      "Access-Control-Allow-Origin": "*",
      "Access-Control-Allow-Methods": "GET, POST, PUT, DELETE, PATCH, OPTIONS",
      "Access-Control-Allow-Headers": "X-Requested-With, content-type, Authorization"
    }
  }
}

IMPORTANT: process.env.VUE_APP_ASSET_URL

The process.env.VUE_APP_ASSET_URL will be set at resources/.env.local and resources/.env.production.

At resources/.env.local, VUE_APP_ASSET_URL must be your DevServer host (don't forget the trailing slash):

Create the files.

nano resources/.env.local
nano resources/.env.production

# resources/.env.local
VUE_APP_ASSET_URL=http://localhost:8080/

At resources/.env.production it depends. Usually, in production, I setup a subdomain with its root pointing to public/dist/. This way I can easily cache all of its contents.

In this case, VUE_APP_ASSET_URL will simply be the subdomain. Otherwise, we'll have to add dist/ at the end of the address.

# resources/.env.production

# subdomain pointing to public/dist/
VUE_APP_ASSET_URL=https://assets.mywebapp.com/

# same domain
VUE_APP_ASSET_URL=http://www.mywebapp.com/dist/

Now you can run npm run serve from the resources folder.

cd resources
npm run serve

Routing

Now, there's two ways you can go about routing:

Method 1

Generate a separate view file for each page (see the comment on the resources/vue.config.js pages property). This means that every time you create a new page, you'll need to add a new entry .js file at resources/src/ (Eg.: resources/src/mypageentry.js) and add it to that object, like mentioned in that comment (...page('mypageentry', 'mybladefile')). In this case, you simply return views like you always did with Laravel.

// routes/web.php

Route::get('/', function () {
    return view('app');
});

// Route::get('/contact', function () {
//    return view('mybladefile');
// });

Method 2 (recommended)

Use the same view for every request and decide which component to load on the client side based on a page key. I prefer this approach, but it'll require some work to get Code Splitting working. This is to avoid loading components that are not required on the current page.

Create a dedicated folder for your page components.

mkdir resources/src/pages

Create a Home.vue page.

// resources/src/pages/Home.vue

<template>
  <div class="home">
    <h1>Hello from Home component</h1>
  </div>
</template>

Change your App.vue.

// resources/src/App.vue

<template>
  <div id="app">
    <Page />
  </div>
</template>

<script>
export default {
  name: 'App',
  components: {
    Page: () => import('@/pages/' + window.app.page.component + '.vue')
  }
}
</script>

As you can see, we're now getting which page should be rendered through a global object attached to the window object. To get this in place, add the following to your resources/src/template.blade.php:

<head>
  <!-- ... -->
  <script>
    window.app = @json($jsapp)
  </script>  
</head>

Then, pass the data through your route:

// routes/web.php

Route::get('/', function () {
    return view('app', [
        'jsapp' => [
            'page' => [
                'component' => 'Home'
            ]
        ]
    ]);
});

This is a bit bitter... A little sugar, please?

Off course we're not gonna be passing all this array every time we render a view. We're not troglodytes!

Let's create a View Macro to simplify this task.

// app/Providers/AppServiceProvider.php

public function boot()
{
    View::macro('vue', function ($component, $data = []) {
        return view('app', [
            'jsapp' => [
                'page' => [
                    'component' => $component,
                    'data' => $data
                ]
            ]
        ]);
    });
}

Then we can just do this:

// routes/web.php

Route::get('/', function () {
    return View::vue('Home'); // Cool, huh?
});

But... how do I pass server data to Vue components?

The server side part is done. Our View::vue macro accepts an array of data as a second parameter.

Let's make that data easily accessible to all of our components using a global mixin (if you have a better way of doing this, go ahead).

// resources/src/main.js

Vue.mixin({
    data () {
      return {
        page: window.app.page.data
      }
    }
})

new Vue({
  render: h => h(App)
}).$mount('#app')

Now, pass some data from your route:

// routes/web.php

Route::get('/', function () {
    return View::vue('Home', [
        'title' => 'Imaginations from the server side!!'
    ]);
});

Now we can simply use that title in our components:

// resources/scr/components/Home.vue

<template>
  <div class="home">
    <h1>{{ page.title }}</h1>
  </div>
</template>

Isn't that awesome? We have transcended the limits between the PHP server and the Vue.js components world!

What about SPAs?

Well, the second routing method we saw is the mechanism used by Inertia.js, an awesome way of creating SPAs with Laravel and Vue.js. You can learn how to integrate Inertia.js with Vue CLI here. Spoiler alert: if you followed this article, you already did 90% of the work and all you did here will be used there. In fact, everything from the Routing section of this article won't be needed. I HIGHLY recommend you to take that step further. Inertia.js is awesome.

Article repo

I've made a GitHub repo with all of this work done for you to clone and see things working for yourself.

DON'T FORGET TO CREATE YOUR resources/.env.local FILE AND SET THE VUE_APP_ASSET_URL ENVIRONMENT VARIABLE

Conclusion

As we saw, using Laravel as a simple API backend for your Vue CLI app isn't the only way to get an app with a Vue.js based frontend. You can use the full routing power and other awesome features of Laravel like you always did and just use Vue.js for what it was initially intended: working with the view layer of your app. And, if you're all about SPAs, you can take one more step and integrate Inertia.js with a Vue CLI app.

Hope this helps anyone out there. Cheers!