7th February 2017

Getting started with Drupal 8 and Composer

Mark Pavlitski
Development Manager

At Deeson we are constantly looking for ways to improve the way we work, iterating on past projects to incorporate new techniques and best-practices.

We starting playing with Composer recently, as a tool for speeding up Drupal module updates. There were a few quirks, but it generally worked.

Then we discovered the Drupal Composer project, which makes it much simpler to manage Drupal core as well as modules.

This is great! We can use Composer to install and update Drupal core, modules and themes, and all in a consistent manner; anyone can run Composer and end up with the exact same set of code.

So now we can start excluding some of the off-the-shelf code from our Git repository (contrib modules, themes, and libraries.) This slims down our repositories and speeds up development for the whole team.

Combined with our approach to managing settings we’re really starting to limit the amount of custom stuff in the docroot now.

Having recently completed a site using this approach I started thinking: “Why do we even need the docroot in Git?”

So we got rid of it! One of the many benefits of working in self-managing teams!

We now have a very flat repository structure where the entire docroot is compiled during deployments. The project repository contains a CMI config directory, settings.php, modules and themes directories, and the all-important composer.json which manages everything that isn’t project-specific custom code.

Internally we use Bitbucket pipelines to manage building and deploying our projects.

Every commit triggers a pipelines build. The docroot is built, tests are run, and if all goes well, it gets pushed to the hosting platform.

We have put together a small Composer script which simply symlinks the modules, themes and settings into the docroot when running composer install. The rest of the build is vanilla composer.

Our composer.json is based on the version provided by Drupal Composer, but with a change to the post-install-cmd and post-update-cmd hooks.

  "scripts": {
 "drupal-scaffold": "DrupalComposer\\DrupalScaffold\\Plugin::scaffold",
 "pre-install-cmd": [
 "pre-update-cmd": [
 "post-install-cmd": [
 "post-update-cmd": [

Here we have replaced the script handler plugin with our own customised version, which creates the symlinks mentioned above during composer install and composer update. We also run the Drupal Scaffold plugin on every Composer install or Composer update, to ensure that all of the extra Drupal files like index.php and update.php exist in the docroot.

Taking the Drupal docroot out of our project repositories has required a shift in the way we think about developing Drupal projects, but ultimately we believe it has streamlined and simplified our development workflows.

We have turned this approach into a Drupal 8 Quick Start template, which can be used to very quickly get up and running with Drupal 8 using a composer-based workflow. The project is available on Github. PRs welcome!