Setting up a local development environment

Everything we will be creating with Drupal revolves around having a proper local development environment, and with the move from Drupal 7 to Drupal 8, there has been a more aligned workflow between local development, staging, and production environments. This is evident with the introduction of the additional files and services that are now included within our sites folder, all aimed at allowing us to have more control during development.

For example, while creating a theme, we will often find ourselves having to clear Drupal's cache to see any changes that we applied. This includes render cache, page cache, and Twig cache. Having to go constantly through the process of clearing cache not only takes up time but also becomes an unnecessary step.

Let's discuss the setup and configuration of our local environment to use a local settings file that will allow us to disable CSS/JS aggregation, disable render and page cache, and enable Twig debugging.

Managing sites/default folder permissions

The first step in configuring our local development environment requires making changes to various files that will live within our sites/default folder or need to be placed within it. By default, Drupal protects the sites/default folder and any files within it from being written to. We will need to modify the permissions to make sure that the owner of the folder has read, write, and execute permissions while everyone else has only read and execute.

These steps assume that we are familiar with managing permissions, but for further reference, we can take a look at http://www.wikihow.com/Change-File-Properties.

Once we have made the required permission changes, we can proceed to creating and configuring our local settings file.

Configuring settings.local.php

We are all familiar with Drupal's settings.php file. However, in Drupal 8, we can now have different configurations per environment by creating a settings.local.php file that the default settings.php file can reference.

We can follow these simple steps to create and enable the new file:

1. First, we will need to copy and rename example.settings.local.php located in the sites folder to settings.local.php within the sites/default folder.
2. Next, we need to open settings.php located in our sites/default folder and uncomment the following lines:

   if (file_exists(__DIR__ . '/settings.local.php')) {
     include __DIR__ . '/settings.local.php';
   }

3. Save the changes to our settings.php file.

Uncommenting the lines allows settings.php to include our new settings.local.php file within our default settings while allowing us to manage different environment configurations.

Disabling CSS and JS aggregation

As part of the performance settings, Drupal will aggregate both CSS and JS to optimize bandwidth. During development, we are not concerned with bandwidth as we are developing locally. Using a settings.local.php file, CSS and JS aggregation are disabled for us. However, if for some reason we want to re-enable aggregation, we would simply change the TRUE values to FALSE as follows:

/**
 * Disable CSS and JS aggregation.
 */
$config['system.performance']['css']['preprocess'] = TRUE;
$config['system.performance']['js']['preprocess'] = TRUE;

Disabling render and page cache

Another configuration option we can address while having the settings.local.php file open is render and page cache. This setting allows us to avoid having to clear Drupal's cache constantly when we make a file change.

Locate and uncomment the following lines:

$settings['cache']['bins']['render'] = 'cache.backend.null';
$settings['cache']['bins']['dynamic_page_cache'] = 'cache.backend.null';

Disabling test modules and themes

One last configuration we will want to make to our settings.local.php file has to do with test modules and themes. By default, our local settings file enables the display of various modules and themes meant for testing purposes only. We can disable them by changing the following TRUE value to FALSE:

$settings['extension_discovery_scan_tests'] = FALSE;

With all of these changes made, we will want to make sure that we save our settings.local.php file. Now, each time we refresh our browser, we will get a new copy of all files without the need to clear Drupal's cache to see any changes.

In some instances, we may need to rebuild Drupal's cache before the above settings will work. If that is the case, we can navigate to /core/rebuild.php, which will fix any issues.

Now that we have our local development environment configured its time we took a closer look at default versus custom themes.