Gulp logo

Compile your assets using Laravel Elixir in Drupal 8

I have built many sites using Grunt in the past and I recently switched to a Laravel package called Elixir to make my life slightly easier when defining tasks for my Drupal theme. In this article I will cover some the benefits of using Laravel Elixir in a Drupal 8 theme.

Install Laravel Elixir

The installation and setup of Laravel Elixir is already well covered by the online documentation. This article will assume that your environment is setup and Node.js is installed.

Getting started

Create your package.json file by either running npm init from your theme of manually create it. Whatever floats your boat. In our example we will just define the bare minimum.

{
  "private": true,
  "devDependencies": {
    "gulp": "^3.8.8"  
  },
  "dependencies": {
    "laravel-elixir": "^4.0.0"
   }
}

Next, we need to create our gulpfile.js with the bare minimum again.

/**
 * @file
 * Basic tasks for our theme.
 */
var elixir = require('laravel-elixir');

elixir(function(mix) {

});

Cool! We can now install our dependencies by running the npm install command in our theme directory.

If you're in Perth you must have waited for little while because of our crabby connection, but if you cd into node_modules you should see that we have two packages available, gulp and laravel-elixir.

Overriding Laravel Elixir default settings

If you have a look at the Laravel Config file [link to Config.js on github], you will see that Elixir is highly configurable and doesn't lock you down into a folder structure you didn't want or like. Those variables can be overridden from the gulpfile.js we originally created.

In our case we will go ahead and override assetPath and publicPath.

/**
 * Elixir configuration overrides.
 */
elixir.config.assetsPath = '';
elixir.config.publicPath = '';

Compiling our CSS

Alright, so the first task we have to run will allow us to compile our sass to css. Luckily Elixir supports sass out of the box and compiling/mixing our sass can be done in one line of code.

/**
 * @file
 * Basic tasks for our theme.
 */
var elixir = require('laravel-elixir');

/**
 * Elixir configuration overrides.
 */
elixir.config.assetPath = '';
elixir.config.publicPath = '';

elixir(function(mix)) {

  mix.sass('app.scss');

});

Run the gulp command and wait until your sass is compiled.

Adding Javascript and CSS assets to our Drupal 8 theme

Now we need to define our assets in a THEME.libraries.yml. We will go ahead and create it, our compiled app.css is going to go under the global-styling asset library. 

We are certain that we need to attach our app.css to all pages. Open up your THEME.info.yml and add a new section for libraries.

Just like Drupal 7, after editing the THEME.info.yml file you will have to clear the cache to see some changes.

Importing a third party library to our theme.

Cool, we've deviated a little bit from our main topic (Elixir) but we should be back on track now. Let's install my favourite slideshow plugin using the following npm command with the save option.

npm install slick-carousel --save

Open up your package.json file. You will see that slick-carousel is now a dependency of our theme. Remember to add node_modules to your .gitignore file, all we need to commit is the package.json file.

Now what we need to do is:

  • fetch only the files we need from the node_modules directory and bring it to our libraries.
  • load the library and its dependencies when needed in our theme

First create a libraries directory within your theme and open up your gulpfile.js. We will use the copy method to copy files and directories to the new locations.

mix.copy('node_modules/slick-carousel/slick/slick.js', 'libraries/slick/slick.js');
mix.copy('node_modules/slick-carousel/slick/slick.css', 'libraries/slick/slick.css');

Run the gulp command in your terminal and checkout your libraries directory. Since this is automated, libraries can go in our .gitignore file. We'll let the build server deal with pulling and reshuffling our theme dependencies.

We now need to add the Slick library to our THEME.libraries.yml.

slick:
  version: 1.x.x
  css:
    theme:
      libraries/slick/slick.css
    js:
      libraries/slick/slick.js
    dependencies:
      - core/jquery

We won't be going in depth in this article on how to attach this library to our pages, but there are multiple ways to do this. 

  • Attach a library in a Twig Template only when you need it
  • Attach it to all pages from your THEME.info.yml file
  • Or implement a THEME_preprocess_HOOK() function in your .theme file

Conclusion

Writing a gulpfile.js without Laravel Elixir isn't complicated but Elixir allows us to achieve the same thing in less lines. Less lines mean easier project to maintain. But for those who aren't exposed to Gulp or Grunt yet I would recommend starting by learning Gulp before moving on to Elixir just to get a basic understanding of how it works.

Elixir also provides helpers for your Javascript files including compiling ECMAScript 6, CoffeeScript, Browserfiy or even simply concatenating plain Javascript files.

Meet The Author

Written By
yohann.catherine
Published date : Feb 23, 2016
Last updated : Jun 07, 2018