Blog

Drupal Theme Cache

Drupal Theme Caching

Drupal is powerful - but if you’ve ever modified a Twig template and wondered why your changes didn’t show up immediately, or struggled with blocks not updating, you’ve already experienced Drupal’s caching layers in action.
Among these layers, the two most important for front-end developers and themers are:

  • Twig Cache

  • Render Cache

Understanding how they work will save hours of frustration, improve site performance, and prevent “Why isn’t this updating?” confusion during development.

This post covers how both caches work, how to clear or disable them during development, and the best practices & precautions you must take while theming.

1. What Is Twig Cache?

Twig is the templating engine Drupal uses.
Every time you write a template such as:

  • page.html.twig

  • node.html.twig

  • block--views.html.twig

Drupal compiles the Twig template into PHP and stores it in a cache for performance.

Why Twig caching exists

  • Compiling Twig → PHP is expensive

  • The compiled result can be reused

  • It speeds up page rendering significantly

What gets cached?

  • Compiled PHP version of .twig files

  • Template discovery and suggestions

  • Twig variables preparations

So when you update a Twig file and don’t see any changes, it’s usually because a cached compiled template is still being used.

2. How to Clear or Disable Twig Cache (Development Mode)

Method 1: Disable Twig cache temporarily
sites/default/services.yml

Under twig.config, set:

parameters:
  twig.config:
    debug: true
    cache: false
    auto_reload: true
This forces Drupal to reload Twig templates on every page refresh.

Best for: Local development
Not recommended: Production (slows down rendering)

Method 2: Clear cache using Drush
drush cr

This clears:

  • Twig cache

  • Render cache

  • Routing cache

  • Plugin cache

  • Config cache
    …everything.

Best for: Development + Production

Method 3: Clear cache from Admin UI
/admin/config/development/performance

Click Clear all caches

3. What Is Render Cache? (The Most Important Cache in Drupal)

Render cache is the caching system that stores render arrays after they are converted into HTML.

When you render something like:

  • Nodes

  • Blocks

  • Menus

  • Views

  • Paragraphs

  • Fields

Drupal creates a render array, attaches cache metadata, and then saves the rendered output.

How Render Cache Works

Every render array includes:

1. Cache Contexts (What varies the output)

Examples:

  • user.roles

  • languages

  • url.path

  • theme

Cache context defines the variation key, e.g.:

A menu may change on mobile vs desktop → theme: bartik vs theme: stark.

2. Cache Tags (What invalidates it)

Examples:

  • node:5

  • taxonomy_term:3

  • config:block.block.header

When the related entity updates → Drupal auto-invalidates the cached item.

3. Max-age (Expiration time)

  • max-age: 0 → no caching

  • max-age: 3600 → 1 hour

  • max-age: -1 → permanent cache

4. Examples of Render Cache in Action

Example 1: A block varies by user role
cache:
  contexts:
    - user.roles

The block is cached once per role:

  • Anonymous

  • Authenticated

  • Administrator

Example 2: Node page cache invalidation

If you update Node 20:

cache tag: node:20

Drupal invalidates this tag → All caches referencing this tag are rebuilt.

Example 3: A menu block
contexts:
  - url.path
tags:
  - config:system.menu.main
max-age: -1

Menu updates → cached HTML auto-rebuilds.

5. How Themes Interact With Render Cache

Even when you modify Twig templates, render cache can prevent changes from showing, because:

  • Drupal uses cached rendered HTML, not Twig

  • Page or block may be cached permanently

  • You must clear render cache after structural changes

Symptoms that render cache is active

  • Changing template doesn’t reflect until “Clear cache”

  • Custom block markup doesn’t change

  • Preprocess variables not updating

  • Debug output missing

Solution

Clear render cache:

drush cr

or disable the block/page cache for development:

/admin/config/development/performance

Disable:

  • Dynamic Page Cache

  • Internal Page Cache

6. Common Issues & Fixes (Real-World Scenarios)

Issue 1: Twig template updates not showing

Fix:

  • Clear cache

  • Disable Twig caching

  • Verify correct template is being used (Twig debug)

Issue 2: Block or field not updating

Likely Render Cache.

Fix:

In preprocess:

$variables['#cache']['max-age'] = 0;
Issue 3: Custom preprocess variable not appearing

Add cache context:

$variables['#cache']['contexts'][] = 'user';
Issue 4: Changing menu doesn’t update

Reason: Cache Tag config:system.menu.main

Clear using:

drush cr

or edit the menu to trigger auto invalidation.

7. How to Debug Render Cache

Enable Twig Debug

Shows:

  • Template file name

  • Template suggestions

  • Cache metadata

Use Devel + Kint

Inspect full render arrays:

kint($variables);

Look for:

  • #cache

  • #markup

  • #children

Use "Cacheability Headers"
/admin/config/development/performance
→ Debug cacheability headers

Browser inspector shows:

X-Drupal-Cache-Tags:
X-Drupal-Cache-Contexts:
X-Drupal-Cache-Max-Age:

Drupal uses multiple caching layers:

LayerPurposeAffects
Twig CacheCompiles Twig → PHP templatesTemplate changes
Render CacheCaches rendered HTML of blocks, nodes, fieldsContent changes
Dynamic Page CacheCaches page responsesEntire page
Internal Page CacheCaches pages for anonymous usersEntire page

As a themer, you mainly deal with:

  • Twig Cache (template changes not showing)

  • Render Cache (block/node not updating)

Once you understand cache contexts, tags, and max-age, Drupal theming becomes predictable and fast.