Front end tooling set up

This page is out of date and needs reviewing.

Who is this guide for?

These are advanced instructions for developers to configure the front end stack in Lando so that anyone can work on the front end without needing to install specific tools. If you are looking for a guide on how to use the front end and theme stack then we have you covered.

Depending on the site and the theme it uses you will need to configure your Lando node container differently so that it has the correct set of tools. You will also need to configure gulp to proxy the correct domain.

The different themes and their node requirements

There are three different iterations of the theme we use at Agile Collective for our client sites. Below are the instructions for each one.

The stack

Each theme needs a specific front end stack. Generally this is already covered by the .lando.yml boilerplate for Drupal 7 and Drupal 8+. Some themes will require different tools or a specific version of Node. You can modify the .lando.yml boilerplate to specify the node version. Both boilerplates come with gulp installed globally. Other tools can be installed but it is outside the scope of this guide, instead refer to the Lando documentation on node versions and the documentation on additional tooling.

Current site_theme using gulp as task runner (Drupal 8+ sites)

The default node container provided in the D8 boilerplate .lando.yml file will work fine.

To set up browsersync and compile Sass to css you should cd to the site_theme directory

cd web/themes/custom/site_theme

You will need to modify the site_theme's gulpconfig.js file and change the domain key around line 181 to have the value appserver (the internal domain name for the webserver container). You will also need to generate a random number for the port:

awk 'BEGIN{srand();print int(rand()*(61000-32768))+32768 }'

Make a note of the number and change the value of the port key in gulpconfig.js

The gulpconfig.js will look something like this afterwards (make sure you update the port!):

  browserSync: {
    enabled: true,
    port: 37579,
    watchFiles: [],
    // enable when full CMS is set up
    domain: 'appserver',
    baseDir: './',
    startPath: 'pattern-lab/public/',

If you want to use Pattern Lab then leave the domain commented out (but still change the value for future use).

You then need to edit the .lando.yml file in the git root and add that same port number to the ports key of the node container's overrides section. It will currently look like:

    overrides:
      services:
        ports: [3050:3050] # You should change this port to something random and then update gulpfile.js in the theme to match

After updating it should look something like this:

    overrides:
      services:
        ports: [37579:37579]

If you don't change from the default 3050:3050 then you'll get port clashes when running multiple projects at once.

Restart your containers with:

lando restart

To compile Sass and start watching for file changes run gulp using npm as usual but prefixed with lando:

lando npm start

You should then see your Drupal site proxied through browsersync when you visit http://localhost with the port number you generated earlier, for example:

http://localhost:37579

Drupal 8+ sites with custom theme name using gulp as task runner (Older Drupal 8 sites)

To be written... should be the same as Omega themes. Needs confirmation.

Omega based themes using gulp as task runner (Newer Drupal 7 sites)

Change directory to the custom theme (change theme_name in the following command):

cd web/sites/all/themes/custom/theme_name

You will need to modify the site_theme's gulpfile.js file and change the domain key around line 181 to have the value appserver (the internal domain name for the webserver container). You will also need to generate a random number for the port:

awk 'BEGIN{srand();print int(rand()*(61000-32768))+32768 }'

Make a note of this port number.

Edit the gulpfile.js in the theme directory and change the proxy key (around line 76) so it has the value appserver (the internal domain name for the webserver container). It will look like this afterwards (add and change the port number):

// Sets up browserSync.
gulp.task('browser-sync', function() {
  browserSync.init({
    proxy: "appserver",
    open: false,
    port: 12345 // <- Change this port!
  });
});

You then need to edit the .lando.yml file in the git root and add that same port number to the ports key of the node container's overrides section. It will currently look like:

    overrides:
      services:
        ports: [3000:3000] # You should change this port to something random and then update gulpfile.js in the theme to match

After updating it should look something like this:

    overrides:
      services:
        ports: [12345:12345]

If you don't change from the default 3000:3000 then you'll get port clashes when running multiple projects at once.

To use browsersync and compile Sass to css you should be in the custom theme directory.

You may need to install the node modules the theme needs:

lando npm install

Then run gulp as usual but prefixed with lando:

lando gulp

You should then see your Drupal site proxied through browsersync when you visit http://localhost with the port number you generated earlier, for example: http://localhost:12345

Troubleshooting

If browsersync connects but you don't see updates getting pushed it is most likely one or a combination of these things:

  1. Aggregation is currently turned on. Solution: Turn it off, either in the UI or by adding a line to settings.php or settings.local.php
  2. link_css module is not enabled. On D7 sites the link_css module must be enabled. Browsersync only works with css files added by the <link> method, not Drupal's default @import method.

Last updated: