Week 4: Configure Your Environment for Theme Development

This is Week 4 of the 7-week course Hands-On: Theming. Get started with Drupal theming in 1 hour a week for 7 weeks. Based on our popular Drupal Theming Workshop featured at DrupalCon.

Time to complete: About 1 hour

This week you will configure your local environment for theme development. Go through each tutorial and then apply what you've learned in the final hands-on exercise. Be sure to complete the last tutorial listed (Exercise: Configure Your Environment for Theme Development) before you move on to Week 5: Override the Main Page Template.


  1. Understand the use cases and benefits of configuring local settings for theme development
  2. Complete Exercise: Configure Your Environment for Theme Development:
  • Configure Drupal settings on a per-environment basis
  • Disable caching via local settings changes
  • Enable Twig debugging mode via local settings changes

Sign-up for weekly email reminders

Sign-up for the Hands-On Theming email list and get reminders and tips about each week's exercises!


Own this course

You can also purchase the Practical Drupal Theming course on Thinkific. The course material is the same, but you can access the content without a Drupalize.Me membership and you will own the course forever.

Tutorials in this course
More information

Making Drupal fast by default implies having caching layers and CSS and JavaScript aggregation utilities enabled out-of-the-box. As a theme developer this can be annoying, because you must clear these various caches in order to preview any changes. In addition, inspecting variables with debugging tools often produces PHP errors. We'll make some recommendations for PHP settings on your local environment that can prevent these errors from happening so often.

By the end of this tutorial, you should be able to:

  • Set up your local Drupal site for theme development
  • Prepare your local development environment for working on and debugging themes
More information

Drupal has a few handy settings you can tweak to make developing themes a little more intuitive and a lot more awesome. This includes disabling some of the caching that Drupal does so you don't need to clear the cache as frequently. We'll also turn off CSS and JS aggregation in a settings file (overriding anything set on the Performance configuration form) so you can see your changes to .js and .css files with just a page refresh. Finally, turning on the Twig debug service will give us some additional contextual information about the templates being used when we view the source code of any page on our site. Walk through the exercise steps, and if you get stuck you can watch the video to see how we implemented this.

If you want to try and complete this on your own you'll need to:

  • Make changes to your site's settings.php file. Hint: check out the example.settings.local.php file included with core.
  • Modify configuration via a services.yml file. Hint: check out the default.services.yml file included with core.

Once this is done, if you view the source of any page on your Drupal site you should see extra HTML comments with helpful information about which template file was used to generate a section of markup.


<!-- THEME DEBUG -->
<!-- THEME HOOK: 'node' -->
   * node--view--frontpage--page-1.html.twig
   * node--view--frontpage.html.twig
   * node--2--teaser.html.twig
   * node--2.html.twig
   * node--page--teaser.html.twig
   * node--page.html.twig
   * node--teaser.html.twig
   x node.html.twig
<!-- BEGIN OUTPUT from 'themes/icecream/templates/node.html.twig' -->

Note: At the end of this exercise, you'll find a video walk-through of the solution.

This course appears in the following guides:
Drupal 8, 9, and 10