# Local development services.
#
# To activate this feature, follow the instructions at the top of the
# 'example.settings.local.php' file, which sits next to this file.
parameters:
http.response.debug_cacheability_headers: true
twig.config:
debug: true
auto_reload: true
cache: false
services:
cache.backend.null:
class: Drupal\Core\Cache\NullBackendFactory
This tutorial explains how to set up a local Drupal site specifically for theme development by turning off caches and asset aggregation, adjusting PHP settings, and enabling debugging so changes are easy to see and troubleshoot.
As of Drupal 10.1 you can enable Twig's debug mode and disable Drupal's caching via the administrative UI ( Manage administration menu navigate to Configuration > Development) . Just go to admin/config/development/settings and enable the development settings you want.
The second step you can do in the admin ui interface is go to Configuration > Performance (admin/config/development/performance) and disable any css / js aggregation caching.
This is nice and easy as long as you know what you are doing plus you do not want to end up with these settings via the configuration synchronization yaml files into your live environment.
But besides these 2 easy ui options you need to be sure none of these are setup like this in your prouduction environment.
The prefered method is when setting up a development environment, change these settings directly in your settings.php file.
Now as a first step is to update the settings.php file to include our local settings.php file (local.settings.php) by uncommenting these
if (file_exists(__DIR__ . '/settings.local.php')) { include __DIR__ . '/settings.local.php'; }
these lines and copying pasting the default sites/example.settings.local.php to sites/default/settings.local.php. By doing this, you can safely override things like error levels, cache backends, and aggregate settings without affecting production. With this pattern, your theme development environment stays fast and debuggable, while your live site keeps the performance and caching settings it needs.
Now in settings.local.php you can have the following.
#Disable CSS and JavaScript aggregation features.
$config['system.performance']['css']['preprocess'] = FALSE;
$config['system.performance']['js']['preprocess'] = FALSE;
#Bypass (disable) the Render API cache
$settings['cache']['bins']['render'] = 'cache.backend.null';
#Disable the Dynamic Page Cache
$settings['cache']['bins']['dynamic_page_cache'] = 'cache.backend.null';
#this bypasses any settings at admin/config/development/performance.
We need to add one more file and we are almost done. We need to turn on Twig debug mode in development.services.yml
If you do not have this file already create it in web/sites/development.services.yml. Add these.
# Local development services.
#
# To activate this feature, follow the instructions at the top of the
# 'example.settings.local.php' file, which sits next to this file.
parameters:
http.response.debug_cacheability_headers: true
twig.config:
debug: true
auto_reload: true
cache: false
services:
cache.backend.null:
class: Drupal\Core\Cache\NullBackendFactory
Depending your setup and the workflow of your team you might need to use something different like local.development.services.yml if so you can update this in your local.settings.php file. It will be somewhere in the beginning of the file.
/**
* Enable local development services.
*/
$settings['container_yamls'][] = DRUPAL_ROOT . '/sites/development.services.yml';
Update the development.services.yml to match your local version of the file if you need to update it.
There is a new optional debug container parameter since Drupal 9.5.0 and 10.0.0. This is called : render caching debugging.
To enable this update your development.services.yml file like this.
parameters:
http.response.debug_cacheability_headers: true
twig.config:
debug: true
auto_reload: true
cache: false
renderer.config:
required_cache_contexts: ['languages:language_interface', 'theme', 'user.permissions']
auto_placeholder_conditions:
max-age: 0
contexts: ['session', 'user']
tags: []
debug: true
Now by adding this we will see a new of HTML comments that contain cache related information for cache tags, cache contexts, and cache keys. The output will look like this :
<!-- START RENDERER -->
<!-- CACHE-HIT: No -->
<!-- CACHE TAGS:
* user_view
* user:27
* config:core.entity_view_display.user.user.default
-->
<!-- CACHE CONTEXTS:
* route.name.is_layout_builder_ui
* url.site
* languages:language_interface
* theme
* user.permissions
-->
<!-- CACHE KEYS:
* entity_view
* user
* 27
* full
-->
<!-- CACHE MAX-AGE: -1 -->
<!-- PRE-BUBBLING CACHE TAGS:
* user_view
* user:27
-->
<!-- PRE-BUBBLING CACHE CONTEXTS:
* route.name.is_layout_builder_ui
* url.site
* languages:language_interface
* theme
* user.permissions
-->
<!-- PRE-BUBBLING CACHE KEYS:
* entity_view
* user
* 27
* full
-->
<!-- PRE-BUBBLING CACHE MAX-AGE: -1 -->
<!-- RENDERING TIME: 0.169826984 -->
<!-- THEME DEBUG -->
<!-- THEME HOOK: 'user' -->
<!-- FILE NAME SUGGESTIONS:
▪️ user--full.html.twig
✅ user.html.twig
-->
<!-- 💡 BEGIN CUSTOM TEMPLATE OUTPUT from 'themes/custom/demo/templates/user/user.html.twig' -->
<!-- 🥖 Component start: radix:user -->
Now you can see the cache tags, cache contexts and the max-age properties of each cacheable render element.
One last step regarding PHP settings is to add these :
memory_limit = 256M
max_execution_time = 60
error_reporting = E_ALL
display_errors = TRUE
display_startup_errors = TRUE
html_errors = 1
in your php.ini file.
In case you are using ddev you can do this.
mkdir -p .ddev/php
nano .ddev/php/dev-overrides.ini
DDEV will copy any *.ini file in .ddev/php/ into /etc/php/[version]/(cli|fpm)/conf.d inside the container, so these directives apply to both web and CLI. That means that you should put the previous mentioned php settings in your dev-overrides.ini file and do a ddev restart.
