Managing Drupal 8 website using Composer

This post is about:

  • Drupal 8.0.0+

In my previous posts I shared some notes on how to set up a Drupal 8 website from scratch using Composer template and how to manage Drupal 8 site configuration via Git.

This post is a collection of notes on some of the day to day tasks one typically performs while managing Drupal 8 site:

Adding new contributed projects (modules or themes)

To add new contributed project (module or theme) to your website (e.g. Admin toolbar module):

1. Run from the project root (one level above Drupal root):

 composer require drupal/admin_toolbar 8.1.*@dev

You will see something like:

 => composer require drupal/admin_toolbar 8.1.*@dev
./composer.json has been updated
Loading composer repositories with package information
Updating dependencies (including require-dev)
- Installing drupal/admin_toolbar (8.1.11)
  Loading from cache

Writing lock file
Generating autoload files

2. Enable the module either via 'drush en admin_toolbar' or by going to /web/admin/modules.
3. Commit change to Git:

 git status
    modified: composer.json
    modified: composer.lock

git commit -am "Adding admin_toolbar"

4. Export configuration changes if new config was added with the module. Commit that and sync up to prod.


Adding custom modules or themes

Custom modules or themes are private pieces of code you write, which are custom to your site, and not published on

To add custom module or theme:

1. Create folder 'custom' in /web/modules or /web/themes if one does not already exist.

2. Move your custom module/theme there.

3. Add new folders/files to Git.

Git can try to be smart and add the new folder as a sub-module. Make sure that does not happen by typing full path to the new folder being added instead of "git add .". For example:

 git add web/themes/custom/themename/.

This will add the folder and all the files inside of it to Git as normal.

4. Commit the changes and push to external repo.

5. If any config changes happened (e.g. you enabled the new theme and made it default), export config, commit and push it.

6. On production pull changes from external repo. Import config settings if necessary.


Updating Drupal core and contrib modules/themes

[0.] Update composer.json.

If you have absolute version numbers for core or contrib projects in composer.json file, e.g. "8.1.3", you'll need to update those numbers first to whatever versions you want to update to.

If you have relative version numbers, e.g. "8.1.*@dev", you don't need to do anything. The package will be updated to the latest version that matches the rule (8.1.x stable only, not dev, in this case).

1. In the project root (one level above /web) run 'composer update'.

To update everything in your project:

 composer update

It'll take some time to download and install updates for core/modules/themes and their dependencies.

To update Drupal core only:

 composer update drupal/core

To update specific package, e.g. Admin toolbar module:

 composer update drupal/admin_toolbar

2. Run updatedb script from Drupal root:

 cd /web drush updb

3. IF you updated Drupal core and IF you use the old version of Composer template, you might need to manually run update-scaffold script to update files in the /web directory:


Run 'git diff' to review the files for any changes. Restore any customizations to .htaccess or robots.txt.

4. Test everything.

5. If all good, commit the changes to Git, and push to external repo.

6. On production pull the changes.

7. Repeat steps 1-4 on production.


Other posts in the series: