Made withOctober CMSTutorial

Making Websites With October CMS - Part 04 - Setting Up Laravel Elixir

W

Watch and Learn

Creator on the October CMS channel

Watch on YouTube ↗

38K viewsAug 3, 201616:57 runtime

Streamline your front-end development workflow in October CMS by setting up Laravel Elixir. This guide walks you through installing Node.js dependencies like Gulp, configuring a custom gulpfile.js for your theme, and automating asset compilation. Learn to compile and concatenate…

Chapters

#octobercms#tutorial#cmscrm

Summary

This guide details how to set up Laravel Elixir in an October CMS project to automate front-end asset compilation, including Sass and JavaScript files, and enable LiveReload for a more efficient development workflow.

Project Initialization

Before you can use Elixir, you need to set up your project's Node.js environment.

Initialize NPM: Run npm init in your project's root directory to create a package.json file.
Install Dependencies: Install Laravel Elixir and the LiveReload extension as development dependencies.
```
npm install --save-dev laravel-elixir
npm install --save-dev laravel-elixir-livereload
```

Note
This process assumes you have Node.js, NPM, and the Gulp CLI (gulp-cli) installed globally on your machine.

Gulpfile Configuration for October CMS

A gulpfile.js in your project root is where you configure Elixir's behavior. The key is to adjust Elixir's default paths to match October CMS's theme structure.

Require Modules: Start by requiring laravel-elixir and laravel-elixir-livereload.
Customize Paths: Override the default asset and public paths.

Important
The default asset paths in Laravel Elixir do not match the October CMS theme structure. You must override them using elixir.config.assetsPath and elixir.config.publicPath.
- assetsPath: Set to your theme's assets folder (e.g., themes/your-theme/assets).
- publicPath: Set to the same folder. Elixir will create a css and js subfolder within this path for the compiled output.
Mix Assets: Use the mix object to define compilation tasks.
- mix.sass('app.scss'): Compiles assets/sass/app.scss into assets/css/app.css.
- mix.scripts(['jquery.js', 'app.js']): Concatenates the specified JS files into assets/js/all.js.
- mix.livereload([...paths]): Watches specified files and triggers a browser refresh on change.

Updating October CMS Layouts

To use the newly compiled assets, you must update your theme's layout file (.htm).

Remove any existing separate <link> and <script> tags.
Add a single link to your compiled CSS and a single script tag for your compiled JavaScript.

Use the Twig | theme filter to generate the correct URL to the asset within your theme.

<link href="{{ 'assets/compiled/css/style.css' | theme }}" rel="stylesheet">
<script src="{{ 'assets/compiled/js/all.js' | theme }}"></script>

Workflow Commands

gulp: Run this command to perform a one-time compilation of all assets defined in your gulpfile.js.
gulp watch: Run this command to start a process that watches your source files for changes and automatically recompiles them and reloads the browser.

Tip
For LiveReload to work, you need a browser extension (like the LiveReload plugin for Chrome) enabled for your site and you must have gulp watch running in your terminal.

Introduction & GitHub Repository

In the last episode, we created a theme for our October CMS website and in this episode, we are going to set up Laravel Elixir to work with that theme. Laravel Elixir is going to compile our Sass files and it's also going to compile our JS files and concatenate them. And also we are going to enable live reload so that whenever we make changes to our files, it's going to automatically refresh our browser so that we can see the changes immediately.

Before we begin doing Laravel elixir or installing it, I just want to show you this GitHub repository. In this repository, we will store all of the files that we make in this video tutorials so you can check them out. The link will be in the description below this video. Every part of this tutorial series is going to be in this releases right here. So right now we have one release and it's for this video because this is the first time that we are actually doing some coding. So you will be able to just download the source code if you don't want to follow the video with me and type everything. Okay, so now that we got that settled, let's setup Laravel Elixir on our October CMS installation.

Installing Elixir Dependencies via NPM

So right now I am in my October movies root directory and of course since Laravel Elixir is using Gulp, you will have to have Gulp installed and of course Node.js installed. But if you have been following any of the videos on my channel, I hope you already got those installed. You can install them on Windows, on Linux, on macOS, and so on.

So first thing we need to do, we need to initialize the package.json file and to do that you just do npm init. And now we wait a little bit. Okay, so it's going to ask you some questions. Most of the time you can just do enter, enter, enter. So the name is going to be October movies, version, description: Laravel Elixir, entry point, whatever. Test command, whatever. Git repository, who cares. And that should be it. Is this okay? Yes. And now we got our package.json file initialized.

Next thing we need to do, we need to install Laravel Elixir. So to do that, we do npm install --save-dev laravel-elixir and then we wait for a few minutes. Okay, so now that the Laravel Elixir is installed, the next thing we need to do is we need to install Laravel Elixir LiveReload. So to do that, you do pretty much the same thing but you do laravel-elixir-livereload, and of course wait for a few minutes since node packages are pretty slow to download.

Creating the Gulpfile and Reviewing Asset Structure

Now that this is also done, I'm just going to create gulpfile.js. Okay, and now we have a Gulp file. Next thing we need to do, we need to configure that Gulp file so that it will work with our installation of October CMS.

Before we start configuring our Gulp file, I just want to show you what I did behind the scenes. So in this assets folder right now you have CSS, so this is what we did the last time. JS, also what we did the last time. And of course, Sass, which I added behind the scenes. So this is pretty much the SCSS files from my Olympus theme. You can of course add any files you want right here. So I just added some CSS files so that I can show you how the Laravel Elixir compiles all those files into one file. And you have this app.scss file which actually imports Suzy, grid, resets, mixins, variables, and so on, all of the files that you see right here on the left side. So this is what I did behind the scenes.

Now we are going to go to our gulpfile.js and in that file we are going to set up our Laravel Elixir configuration.

Configuring the Gulpfile for October CMS

So that it works with the October CMS. So first of all, I'm going to create a variable called elixir and in that variable, I am going to require laravel-elixir. Next thing we need to do, we need to require laravel-elixir-livereload. Okay, now that we got that set up, so we are going to use this variable so that we can configure Laravel Elixir, so set some assets path and public path. So to do that, you do elixir.config.assetsPath and then we are going to set them up to be, so the path to our assets. So as you can see, we have themes/olympus/assets. So we have to write that.

Okay, and one more thing we need to do, we need to define a public path. So this is the path that Laravel Elixir is going to save our compiled files, so our Sass files and our JS files. So we do the same thing, elixir.config and then we do publicPath equals, we can just copy this. And instead of themes/olympus/assets, we are going to just add compiled. So this is where our CSS and JS files are gonna live, and then we are going to call them from that place in our theme.

I'm first going to make this a little bit bigger so that you can better see it. And now we are going to create an Elixir function, and we're going to pass a variable called mix. And next thing we need to do, we need to tell it which file to use to compile our Sass. Since we already set up this, Laravel Elixir already knows that all the Sass files are in the sass folder. So we don't have to write sass right here or something like that. We just do this, so we just add mix.sass('style.scss'). Laravel elixir will automatically know to go to this folder to find that file.

Also we need to mix our scripts, so we want to concatenate our script. To do that, we just do almost the same thing. So we create mix.scripts() and in that mix.scripts, we define an array of the files that we want to mix together or combine together so that our Javascripts are compiled. So the first thing we need to do is of course jQuery, and then we need to mix our app.js file. So if we go to this js directory, we have app.js and jQuery. So first of all, of course, jQuery, because we require it, and then we do app.js and that's it. And I'm just going to save this file right now.

Compiling Assets with Gulp

And the next thing I'm going to do is I'm actually going to delete this CSS folder because we don't need it anymore. Delete it. Okay. Now if we go to our web page and refresh it, we should get an error. Okay, so we get this exception because as you can see it is trying to call asset('css/style.css'). Of course we don't want to call that file, we want to call our compiled file. So to compile it, we go to our terminal and just do gulp. And if we did everything correctly with the configuration, it should actually work.

It takes a bit longer for all of that to compile once you run it the first time, but as you will see when we gulp watch it or when we watch our files, it's going to go pretty fast. So if we go to our code editor right now and if we check out this assets folder right here you can see that we have compiled. So Laravel is smart enough to know to create two new folders in compiled folder. One is CSS where we have our style.css which is this, so it's compiled. And we also have this all.js file which consists of jQuery currently and our app.js file. So as you can see, it's all here, it's compiled.

Updating the Twig Layout to Use Compiled Assets

Now we just need to go to our layout folder and we need to call those files instead of these. So as I mentioned in the previous episode, when we call our files like this, it's automatically going to concatenate them. So it's going to go through the October asset pipeline and compile your files. But since we are not going to be using October's default asset pipeline, what I'm going to do is I'm just going to remove this square brackets right here. And this is the way you call the CSS files that you need. So we are currently calling assets/css/style.css, but we don't want to call them. We want to call compiled/css/style.css, and then you use this filter for the theme. So it's going to automatically add our absolute URL to your CSS file, as you will see. And we also need to do the same thing for the scripts. So we are only going to be calling one script.

Okay, so assets/compiled/js and we are not calling app.js but all.js. So Laravel Elixir automatically calls that file all. Of course if you check out the Laravel Elixir documentation, you will see the ways that you can change those names for the files if you really want to. But I'm going to leave it as it is right now. So in compiled, we have js and we have this all.js. Also, take a look that it's creating style.css.map files, which you can use with your web developer tools in Chrome, and all.js.map files for your JS files. Okay, if we save this right now and go to our page and refresh it, as you can see now it says 'This is our home page' and since there are some stylings in our CSS file, it is looking like this. Also, we'll check out the page source, we can see that it's calling this link right here: october-movies.dev/themes/olympus/assets/compiled/css/style.css. And the same thing goes for this right here, so for our Javascripts. So this is the theme filter that you can use in Twig to get the URL of your current working site and your theme.

Enabling and Testing LiveReload

So now I'm just going to go to my gulpfile.js and paste this in. So this is a mix for live reload. So what we are saying right here is watch themes/olympus/assets/compiled/style.css, watch all the HTM files, and also watch all the compiled JavaScript files. So when we run gulp watch right now, we should be able to make a change to our CSS or Sass and then it will automatically be refreshed. So let me just save this, go right here, and I'm going to go to my terminal and I'm just going to say gulp watch.

Now that Gulp is watching, we can go to our code editor and open, let's say, globals.scss file. And right here we have body background is white. Let's just try to change it to be black. Actually, before you do that, if you want to see how live reload works, you should go to Chrome and turn on the LiveReload plugin. So enable it. And now we will just say 000. Save this. And now we wait for the page to reload because the first time that you compiled CSS with watch, it takes a bit longer, but then it works pretty fast. So we can check it out right here. So as you can see, it's not compiled yet, but it's going to be in a second. So now it's compiled and as you can see our page is black right now. So if we go right here and do FFF, save it, it's white right now. Okay.

So the next thing we can do, we can go to our pages, to home.htm and say, "This is our home page, yay!" Save this, go to our site, and as you can see, the page is already refreshing and it says, "This is our home page, yay!" Okay, so now this way you get live reload working. Don't forget to turn on the live reload plugin for Chrome.

Conclusion & Next Steps

As you have seen, this has been pretty easy, only a few lines of code and you got all your Gulp working. So that's the benefit of Laravel Elixir, that you don't have to write, I don't know, 50 lines of code to get the same thing as we did right here.

So this is for this video, guys. Thank you for watching. Do remember everything we did here will be available for you on Github, the link will be in the description below. Please follow me on Twitter or on Facebook if you want. Also, if you like this video please like it. If you like the channel, please subscribe to it. Thank you for watching once again and I will see you in the next episode.