Skip to content

Instantly share code, notes, and snippets.

What would you like to do?
Drupal Site Building Best Practices

Better Drupal Building

  • Custom glue should be accomplished with configuration first and PHP code second.

Configuration Management and Dependencies

  • Use Composer (or Drush Make) to build your project and it's depencies.
  • Store your work in files.
  • Set your config directory above the webroot.
  • Sync UUIDs across all developers.


  • Frontend automation should use Gulp to automate tasks like livereload and sass.
  • Yeoman should be used to generate project themes.
  • SCSS syntax SASS should be used to generate CSS.
  • Themes should apply to Drupal without using #id,content-type, block-id, or view-id in the source.
  • Each theme should have reusable patterns rather than top down pages.
  • Themes should use Blockify rather than hard coding blocks into templates.
  • Single field, node, block, view PHP Templates should be avoided.

Editor Experience

  • Content should be editable by the site editor without modifying code, css or complex configuration.
  • Content should have an edit in place contextual gear.
  • Content should not be defined in code.
  • It should not require admin access to figure out how to edit content.
  • The editor user should have links or a dashboard that links to “hidden” editor pages.
  • Editors should be given the Clear Cache permission.
  • CKeditor should be the JavaScript editor.
  • Editors should be able to apply custom CSS via a drop down menu.
  • Taxonomy can be used to apply additional page styles


  • Content should be a node.
  • Taxonomy should categorize nodes. It should not store content.
  • A site should have as few content types as reasonable (4 - 6 is a good goal).
  • Content types should be singular
  • Taxonomy vocabulary should be plural
  • Field names should be singular or plural based on the number of values in the field.
  • Fields should be reused when possible.


  • Context should be used to place blocks.
  • Blocks should only be used sparingly. Consider creating a block view of a node marked by taxonomy instead.


  • Lists should render the teaser view mode of content
  • Custom displays should be accomplished by adding additional view modes.
  • Content should be listed with views.
  • Views should use the rendered entity format unless it’s impossible to do so.
  • List should be ordered with draggable views.


  • Search boxes should not be labeled and they should contain HTML5 placeholder text.
  • Search API should power site search. Core search should not be used.
  • Search API should be powered by Solr or Elastic Search backend.
  • Facets should be avoided in favor of views filters.
  • All fields should be indexed including category names.
  • Search should allow stemming, spelling correction and related searches.
  • Current Search should not be used.


  • Breadcrumbs that don't match URL structure should be avoided.
  • Easy Breadcrumbs module should be used to map URLs to breadcrumbs.

Permissions and Roles

  • Editors should have permissions limited to the set of tasks they perform 80% of the time.
  • Testing should be done as the editor user.


  • Varnish should be used.
  • Block Caching must be enabled.
  • If users log in, then modules that disable block caching should not be used.
  • Page cache should be on.
  • Views Content Cache should be added and used on all views except random views.
  • Random Views should be avoided. If used, they should be set to 30 minute time cache.
  • Views Cache should be set to not expire.
  • System cron should be run weekly to avoid resetting HTML page cache.


  • JavaScript should be non-blocking and loaded in the footer.
  • JQuery can be loaded from Google.
  • Javascript should not write inline CSS.
  • Yeoman and Gulp should be used to construct the primary frontend toolsets


  • CSS should be loaded in the header in external files.
  • CSS should be preprocessed from SCSS.
  • A Classless asymmetric grid system should be used to create responsive columns.


  • Transparent pngs should be avoided.
  • Images should always be compressed as well as possible.
  • Larger images should be resized to fit the size of the device.


  • FOUT should be dealt with using the responsive typography method championed by Jason Pamental.
  • Google webfont loader should not be used.
  • Custom fonts should be used in limited amounts.
  • Custom fonts should be less than 50kb each.

Responsive Features

  • Responsive customizations should be accomplished in JavaScript and be fully cachable by Varnish.


  • Code should never go into the database inside eval functions.
  • Code should be separated into discrete modules based on function, not content type.
  • There should be more than one feature.
  • All source code should follow Drupal coding standards.
  • TODOs should be marked with TODO.

Source Control

  • Remote hosted git should be used to manage all source code.
  • Gitflow should be used to manage git branches.
  • Production sites should run off of a different branch than development.


  • LocalStorage should be used instead of cookies.


  • Development servers should deploy automatically on a push to the master branch.
  • Production servers should be deployed from the production branch using git pull or a deployment tool.
  • Database changes should be deployed with Features.


  • Sites should load in under 1 second from the nearest data center on Pingdom performance test.
  • Pages should not exceed 1 MB.
  • Pages should not exceed 100 requests.

Web Hosting

  • Web hosting should make use of a globally distributed CDN.
  • PHP 5.5 should be used.
  • OPcache should be enabled for PHP with at least 64 MB of memory.
  • A cache should be used such as APCu for single web servers or memcache for multiple.
  • All websites should be behind a Varnish server.
  • Solr should be hosted on a dedicated Tomcat server
  • The latest stable MariaDB should be used as a database server.
  • If apache is used, it should use mod-php and have AllowOverrides off.
  • Drupal should only have permission to write to /tmp/* and sites/default/files/*
  • Servers will be monitored for uptime and load.
  • All servers will have image backups daily and weekly.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.