So you’re ready to start working on your first Drupal 8 project, but not quite sure where to start? There are a number of changes since Drupal 7, so hopefully this guide will help you to dive right in.


  • An IDE configured for Drupal development. See my previous blog post on Configuring PHPStorm for Drupal Development. You can also use Eclipse, SublimeText or any other IDE, but please make sure it helps you adhere to the Drupal coding standards.
  • A local web server. If you don’t already have a preference I would suggest Acquia DevDesktop due to its simplicity to install and use.
  • Drupal 8, installed on your local web server. If you’re on DevDesktop you can install this automatically with a few clicks. I would recommend using PHP 7.
  • Drush and Composer. Installing these is outside the scope of this blog post which is another reason I’m recommending DevDesktop.
  • Git, either command line or via a client application. I prefer command line for bulk commits and SourceTree for granular commits.

Once you have Drupal 8 running locally you can open it up in your IDE so we can get started.

Version control

Before you make any changes to Drupal it’s a good idea to commit the project to git. Drupal no longer ships with a .gitignore file, instead there is an example.gitignore file which you can copy to .gitignore. This makes it easy to customise your .gitignore file, but means you’ll have to manually add any suggested changes when they are released.

Go ahead and copy example.gitignore to .gitignore - if you’re on Windows you might need to do this via your IDE, or via the command line. You’ll also want to make sure you have a global gitignore file which excludes files from your IDE and OS, eg .idea, .project, .DS_Store, etc.

The example.gitignore file also excludes the vendor directory from git. The idea is the production server and every developer would run composer update after checking out from git. If this makes you uncomfortable then go ahead and comment out that line.

Now you can initialise your git repository and commit Drupal core.

git init
git add -A
git commit -m "Initial commit"

Development modules

Now that Drupal is installed let’s install some modules that will be helpful for development. From your project root, run the following drush commands

drush dl admin_toolbar config_update devel
drush en -y admin_toolbar admin_toolbar_tools config_update config_update_ui devel kint


Drupal now ships with some suggested local configuration files which we can use.

Copy sites/example.settings.local.php to sites/default/settings.local.php - note that you’re copying it into the sites/default directory and removing the word example.

Open up sites/default/settings.php in your IDE and uncomment the section about settings.local.php - it should be at or near the bottom.

Local settings

Open up sites/default/settings.local.php and take a look at what’s there. Take time to read through the comments.

To help with development, particularly for theming, you’ll likely want to disable the render cache and dynamic page cache, so uncomment these two lines:

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

On top of this there are a few other settings that can be set for local development, which you can add to this file. Choose which ones are relevant to you.

 // If your private or temporary file system path is different to that of
// production (where your database is synced from) then you’ll need to hardcode
// the paths in settings.local.php.
$settings['file_private_path']  = '../files-private';
$config['system.file']['path']['temporary'] = '../tmp';

// Log all emails instead of sending them.
$config['system.mail']['interface']['default'] = 'devel_mail_log';

// Just in case some module tries to bypass Drupal mail, prevent the server from
// sending at the PHP level.
ini_set('SMTP', '');

// Or if you prefer the Maillog module ...
$config['maillog.settings']['send'] = FALSE;
$config['maillog.settings']['log'] = TRUE;
$config['maillog.settings']['verbose'] = TRUE;

// Make Views easier to build.
$config['views.settings']['ui']['show']['advanced_column'] = TRUE;
$config['views.settings']['ui']['show']['master_display'] = TRUE;
$config['views.settings']['ui']['show']['display_embed'] = TRUE;

// I don't like the Live Preview in Views because I don't wan't it to reload 
// while I'm still making changes.
$config['views.settings']['ui']['always_live_preview'] = FALSE;

// We should disable the automated_cron module and run cron at the server level.
// But let's disable it here too in case you need it enabled on the server and
// it might still be enabled after you sync your database.
$config['automated_cron.settings']['interval'] = 0;

// Kint is the new replacement for Krumo and it can cause PHP to exhaust your
// memory limit. We can limit the number of levels it prints here.
require_once DRUPAL_ROOT . '/modules/devel/kint/kint/Kint.class.php';
Kint::$maxLevels = 6; 

If there are any other modules that you like to configure you can easily find the variable by browsing the config directory of that module. For example, browse to core/modules/system/config/install and you’ll find system.performance.yml. Inside you’ll find the max_age setting. To hardcode this in your settings.local.php file you’ll need to set $config[‘system.performance’][‘cache’][‘page’][‘max_age’] = 0; You can also see what configuration options are available by running drush config-list.

Theme debugging

If you’re going to be developing a custom theme you may like to enable Twig debugging. This prints out some handy comments in the page source indicating which template files are in use, as well as suggestions for creating more granular templates.

HTML captions when using theme debugging

To enable this, add the following to your file. Note you’ll want to merge the twig.config part in with the existing parameters section.

# Enable Twig debugging.
   debug: true
   auto_reload: true
   cache: false

You should now be ready to get started with your custom modules and themes. Stay tuned to the blog for more tips for Drupal 8 development.

Share this content