LocomotiveCMS

The Locomotive V4 Developer Hub

Welcome to the Locomotive V4 developer hub. You'll find comprehensive guides and documentation to help you start working with Locomotive V4 as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Manage JS and CSS with Webpack

This functionality requires Wagon v3

For a long time, Wagon had been using Sprockets to process and compile CSS (Sass, Less, ...etc) and Javascript (CoffeeScript, ES6) assets.
One of the nice things about Sprockets is its super easy installation. Nothing to setup, it just works out of the box. Assets were gzipped without any weird configuration.

Things have changed a lot in the Javascript world. Sites embed now a lot of Javascript code in charge of handling animations and building complex UI components. Those Javascript libraries or packages are managed through a central repository (npm) dealing with dependencies and libs versioning.
However, in top of that, frontend developers must use a tool to compile all the package assets required by their sites. To achieve this, developers came up with tools.
One of the most popular is Webpack. This is an incredible tool which, unfortunately, can be a burden to set up correctly.

Since the philosophy behind LocomotiveCMS is to remove the painful tasks when it comes to create sites, we decided to integrate Webpack inside Wagon and set it up so that spinning a new site project should take as less time as possible.

Regarding the sections and more specifically the javascript events as described here, we also made the integration with Webpack easier. It means that when you generate a new section, we'll create the associated javascript file with all its lifecycle methods and we'll do all the plumbery for you.

Webpack requires the installation of NodeJS and YARN (or NPM)

Installation

There is almost nothing to do. Creating a new site will automatically generate all the files we need to start using Webpack. Those files will go under the app/assets folder of your Wagon site.
The package.json file is located at the root of the Wagon site.

Want to add Webpack to a site built with Wagon v3?

At the root of your site, type the following command: bundle exec wagon generate webpack then modify the "name" value in the generated package.json file to match your site's root folder name.

You just have to download and install the packages which can be done in one statement in the console.

yarn install

Usage in development

All you have to do is to run the following statement.

yarn start

Note: You will probably need 2 terminals. One for wagon serve and the other one for Webpack.

Once launched, the command outputs logs about the compilation of 2 files: bundle.css and bundle.js.

By default, we included the live reload functionality thanks to the webpack-livereload-plugin package. So, if you try to modify one of your JS/CSS assets in app/assets, the browser will automatically reload the bundle.css or the bundle.js files.

Prepare assets for deployment

Assets generated through the yarn start command are not optimized for production. For instance, they're not minified.

So, before you deploy your theme assets to your production environment, you'll have to generate optimized assets. This can be achieved with the following command:

yarn build:prod

How to use Webpack with Bulma

Bulma is an open source CSS framework based on Flexbox and lighter than Bootstrap. Some of its benefits: 100% responsive, modular, pure CSS (no javascript).

In your terminal, run this statement:

yarn add bulma

Note: Don't forget to stop and re-start, yarn start

Next, let's modify the app/assets/stylesheets/app.scss file by adding the following code:

// Bulma
@import './bulma_variables';
@import '~bulma/bulma.sass';

Then, create a file overriding the Bulma default configuration. This file is named bulma_variables.scss and it has to be located in the app/assets/stylesheets folder.
Here is a sample:

$family-sans-serif: 'Roboto Condensed', sans-serif;

// Colors
$lighter-blue: #bdd1e4;
$light-blue: #8aacd4;
$dark-blue: #224261;
$dark-grey: #636466;
$light-grey: #a7a9ac;
$brown-orange: #E3A346;

$primary: $dark-blue;
$warning: $brown-orange;

// Navbar
$navbar-height: 7.25rem !default;

Manage JS and CSS with Webpack


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.